feat: transfer api for stock module

stock/migrations/0007_transferorder.py

@@ -0,0 +1,66 @@
+# Generated by Django 5.2.7 on 2025-12-02 00:00
+
+from django.conf import settings
+from django.db import migrations, models
+import django.db.models.deletion
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('basic_info', '0009_product_minimum_quantity'),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+        ('stock', '0006_remove_purchaseorder'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='TransferOrder',
+            fields=[
+                ('created_at', models.DateTimeField(auto_now_add=True, verbose_name='创建时间')),
+                ('updated_at', models.DateTimeField(auto_now=True, verbose_name='更新时间')),
+                ('id', models.BigAutoField(primary_key=True, serialize=False)),
+                ('mode', models.IntegerField(choices=[(1, '严进宽出'), (2, '严进严出'), (3, '宽进宽出')], verbose_name='调拨模式')),
+                ('transfer_date', models.DateField(verbose_name='调拨日期')),
+                ('status', models.IntegerField(choices=[(1, '待完成'), (2, '已完成'), (3, '已取消')], default=1, verbose_name='状态')),
+                ('remarks', models.TextField(blank=True, null=True, verbose_name='备注')),
+                ('request_id', models.CharField(blank=True, max_length=64, null=True, verbose_name='请求ID')),
+                ('created_by', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.PROTECT, related_name='created_transfer_orders', to=settings.AUTH_USER_MODEL, verbose_name='创建人')),
+                ('from_warehouse', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='outgoing_transfer_orders', to='basic_info.warehouse', verbose_name='调出仓')),
+                ('incoming_record', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.PROTECT, related_name='transfer_in_orders', to='stock.stockchangerecord', verbose_name='调入出入库记录')),
+                ('merchant', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='transfer_orders', to='basic_info.merchant', verbose_name='所属商户')),
+                ('operator', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='transfer_orders', to='basic_info.employee', verbose_name='经办人')),
+                ('outgoing_record', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.PROTECT, related_name='transfer_out_orders', to='stock.stockchangerecord', verbose_name='调出出入库记录')),
+                ('to_warehouse', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='incoming_transfer_orders', to='basic_info.warehouse', verbose_name='调入仓')),
+            ],
+            options={
+                'verbose_name': '调拨单',
+                'verbose_name_plural': '调拨单',
+            },
+        ),
+        migrations.CreateModel(
+            name='TransferOrderItem',
+            fields=[
+                ('created_at', models.DateTimeField(auto_now_add=True, verbose_name='创建时间')),
+                ('updated_at', models.DateTimeField(auto_now=True, verbose_name='更新时间')),
+                ('id', models.BigAutoField(primary_key=True, serialize=False)),
+                ('unit', models.IntegerField(choices=[(1, '米'), (2, '码'), (3, '公斤')], verbose_name='单位')),
+                ('total_quantity', models.DecimalField(decimal_places=2, max_digits=10, verbose_name='数量合计')),
+                ('num_of_rolls', models.PositiveIntegerField(default=1, verbose_name='匹数')),
+                ('product', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='transfer_order_items', to='basic_info.product', verbose_name='产品')),
+                ('transfer_order', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='items', to='stock.transferorder', verbose_name='调拨单')),
+            ],
+            options={
+                'verbose_name': '调拨单明细',
+                'verbose_name_plural': '调拨单明细',
+            },
+        ),
+        migrations.AddConstraint(
+            model_name='transferorder',
+            constraint=models.UniqueConstraint(condition=models.Q(request_id__isnull=False), fields=('merchant', 'request_id'), name='unique_transfer_request_per_merchant'),
+        ),
+        migrations.AddConstraint(
+            model_name='transferorder',
+            constraint=models.CheckConstraint(check=~models.Q(from_warehouse=models.F('to_warehouse')), name='transfer_different_warehouses'),
+        ),
+    ]

stock/models.py

@@ -371,3 +371,134 @@ class StockFreeze(ModelBase):
     class Meta:
         verbose_name = '库存冻结'
         verbose_name_plural = '库存冻结'
+
+
+class TransferOrderStatusEnum(models.IntegerChoices):
+    DRAFT = 1, '待完成'
+    COMPLETED = 2, '已完成'
+    CANCELLED = 3, '已取消'
+
+
+class TransferOrder(ModelBase):
+    """跨仓调拨单"""
+
+    id = models.BigAutoField(primary_key=True)
+    merchant = models.ForeignKey(
+        basic_info_models.Merchant,
+        on_delete=models.PROTECT,
+        related_name='transfer_orders',
+        verbose_name='所属商户',
+    )
+    from_warehouse = models.ForeignKey(
+        basic_info_models.WareHouse,
+        on_delete=models.PROTECT,
+        related_name='outgoing_transfer_orders',
+        verbose_name='调出仓',
+    )
+    to_warehouse = models.ForeignKey(
+        basic_info_models.WareHouse,
+        on_delete=models.PROTECT,
+        related_name='incoming_transfer_orders',
+        verbose_name='调入仓',
+    )
+    mode = models.IntegerField(
+        choices=basic_info_models.WareHouseModeEnum.choices,
+        verbose_name='调拨模式',
+    )
+    operator = models.ForeignKey(
+        basic_info_models.Employee,
+        on_delete=models.PROTECT,
+        related_name='transfer_orders',
+        verbose_name='经办人',
+    )
+    created_by = models.ForeignKey(
+        'auth.User',
+        on_delete=models.PROTECT,
+        null=True,
+        blank=True,
+        related_name='created_transfer_orders',
+        verbose_name='创建人',
+    )
+    transfer_date = models.DateField(verbose_name='调拨日期')
+    status = models.IntegerField(
+        choices=TransferOrderStatusEnum.choices,
+        default=TransferOrderStatusEnum.DRAFT,
+        verbose_name='状态',
+    )
+    remarks = models.TextField(blank=True, null=True, verbose_name='备注')
+    request_id = models.CharField(max_length=64, blank=True, null=True, verbose_name='请求ID')
+    outgoing_record = models.ForeignKey(
+        'stock.StockChangeRecord',
+        on_delete=models.PROTECT,
+        related_name='transfer_out_orders',
+        null=True,
+        blank=True,
+        verbose_name='调出出入库记录',
+    )
+    incoming_record = models.ForeignKey(
+        'stock.StockChangeRecord',
+        on_delete=models.PROTECT,
+        related_name='transfer_in_orders',
+        null=True,
+        blank=True,
+        verbose_name='调入出入库记录',
+    )
+
+    class Meta:
+        verbose_name = '调拨单'
+        verbose_name_plural = '调拨单'
+        constraints = [
+            models.UniqueConstraint(
+                fields=['merchant', 'request_id'],
+                condition=models.Q(request_id__isnull=False),
+                name='unique_transfer_request_per_merchant',
+            ),
+            models.CheckConstraint(
+                check=~models.Q(from_warehouse=models.F('to_warehouse')),
+                name='transfer_different_warehouses',
+            ),
+        ]
+
+    def clean(self):
+        super().clean()
+        if self.from_warehouse_id and self.to_warehouse_id:
+            if self.from_warehouse_id == self.to_warehouse_id:
+                raise ValidationError('调拨的出入库仓库不能相同')
+            if self.from_warehouse.merchant_id != self.merchant_id or self.to_warehouse.merchant_id != self.merchant_id:
+                raise ValidationError('调拨仓库必须属于当前商户')
+            if self.from_warehouse.mode != self.to_warehouse.mode:
+                raise ValidationError('调拨要求出入库仓库的模式一致')
+            if self.mode and self.mode != self.from_warehouse.mode:
+                raise ValidationError('调拨模式与仓库模式不一致')
+
+    def __str__(self):
+        return f'调拨单 {self.id} - {self.from_warehouse.name} -> {self.to_warehouse.name}'
+
+
+class TransferOrderItem(ModelBase):
+    id = models.BigAutoField(primary_key=True)
+    transfer_order = models.ForeignKey(
+        TransferOrder,
+        on_delete=models.CASCADE,
+        related_name='items',
+        verbose_name='调拨单',
+    )
+    product = models.ForeignKey(
+        basic_info_models.Product,
+        on_delete=models.PROTECT,
+        related_name='transfer_order_items',
+        verbose_name='产品',
+    )
+    unit = models.IntegerField(
+        choices=basic_info_models.ProductUnitEnum.choices,
+        verbose_name='单位',
+    )
+    total_quantity = models.DecimalField(max_digits=10, decimal_places=2, verbose_name='数量合计')
+    num_of_rolls = models.PositiveIntegerField(default=1, verbose_name='匹数')
+
+    class Meta:
+        verbose_name = '调拨单明细'
+        verbose_name_plural = '调拨单明细'
+
+    def __str__(self):
+        return f'调拨明细 {self.id} - 产品: {self.product.name}'

stock/services.py

@@ -678,6 +678,123 @@ class StockFlowService:
         return payload
 
 
+def _aggregate_transfer_details(details: List[models.StockChangeDetail]) -> Dict[int, Dict[str, Any]]:
+    aggregated: Dict[int, Dict[str, Any]] = {}
+    for detail in details:
+        product_id = detail.product_id
+        if product_id not in aggregated:
+            aggregated[product_id] = {
+                'product': detail.product,
+                'unit': detail.unit,
+                'total': Decimal('0'),
+                'num_of_rolls': 0,
+            }
+        aggregated[product_id]['total'] += Decimal(detail.quantity)
+        aggregated[product_id]['num_of_rolls'] += 1
+    return aggregated
+
+
+def create_transfer_order(
+    *,
+    merchant: basic_models.Merchant,
+    created_by,
+    operator: basic_models.Employee,
+    from_warehouse_id: int,
+    to_warehouse_id: int,
+    items: List[Dict[str, Any]],
+    transfer_date=None,
+    remarks: str | None = '',
+    request_id: str | None = None,
+) -> models.TransferOrder:
+    if not merchant:
+        raise ValueError('必须提供商户信息')
+    if operator is None:
+        raise ValueError('必须提供调拨经办人')
+    if operator.merchant_id != merchant.id:
+        raise ValueError('经办人不属于当前商户')
+    if not items:
+        raise ValueError('调拨产品明细不能为空')
+    if not from_warehouse_id or not to_warehouse_id:
+        raise ValueError('必须提供调出仓和调入仓')
+    if from_warehouse_id == to_warehouse_id:
+        raise ValueError('调入仓与调出仓不能相同')
+
+    transfer_date = transfer_date or timezone.now().date()
+
+    if request_id:
+        existing = models.TransferOrder.objects.filter(merchant=merchant, request_id=request_id).first()
+        if existing:
+            return existing
+
+    try:
+        from_warehouse = basic_models.WareHouse.objects.get(id=from_warehouse_id, merchant=merchant)
+    except basic_models.WareHouse.DoesNotExist:
+        raise ValueError('调出仓不存在或不属于当前商户')
+
+    try:
+        to_warehouse = basic_models.WareHouse.objects.get(id=to_warehouse_id, merchant=merchant)
+    except basic_models.WareHouse.DoesNotExist:
+        raise ValueError('调入仓不存在或不属于当前商户')
+
+    if from_warehouse.mode != to_warehouse.mode:
+        raise ValueError('调拨要求调出仓与调入仓的出入库模式一致')
+    if from_warehouse.mode == basic_models.WareHouseModeEnum.RESTRICT_IN_OUT:
+        raise ValueError('调拨暂不支持严进严出模式，请先转为其他模式')
+
+    flow_service = StockFlowService(merchant=merchant, created_by=created_by)
+
+    with transaction.atomic():
+        transfer_order = models.TransferOrder.objects.create(
+            merchant=merchant,
+            from_warehouse=from_warehouse,
+            to_warehouse=to_warehouse,
+            operator=operator,
+            created_by=created_by,
+            transfer_date=transfer_date,
+            status=models.TransferOrderStatusEnum.DRAFT,
+            remarks=remarks or '',
+            mode=from_warehouse.mode,
+            request_id=request_id,
+        )
+
+        out_record, out_details, _ = flow_service.stock_out(
+            warehouse_id=from_warehouse.id,
+            source_type=models.StockChangeSourceEnum.TRANSPORT_OUT,
+            source_id=transfer_order.id,
+            items=items,
+        )
+        in_record, _, _ = flow_service.stock_in(
+            warehouse_id=to_warehouse.id,
+            source_type=models.StockChangeSourceEnum.TRANSPORT_IN,
+            source_id=transfer_order.id,
+            items=items,
+        )
+
+        make_stock_change_completed(out_record)
+        make_stock_change_completed(in_record)
+
+        aggregated = _aggregate_transfer_details(out_details)
+        transfer_items = [
+            models.TransferOrderItem(
+                transfer_order=transfer_order,
+                product=data['product'],
+                unit=data['unit'],
+                total_quantity=data['total'],
+                num_of_rolls=data['num_of_rolls'],
+            )
+            for data in aggregated.values()
+        ]
+        if transfer_items:
+            models.TransferOrderItem.objects.bulk_create(transfer_items)
+
+        transfer_order.outgoing_record = out_record
+        transfer_order.incoming_record = in_record
+        transfer_order.status = models.TransferOrderStatusEnum.COMPLETED
+        transfer_order.save(update_fields=['outgoing_record', 'incoming_record', 'status'])
+
+    return transfer_order
+
+
 def find_inventory(product_id: int, warehouse_id: int) -> models.Inventory | None:
     """根据产品ID和仓库ID查找库存记录"""