feat: added fields into shipment and support external order system

docs/2026-01-14_summary.md

@@ -132,6 +132,30 @@ python manage.py backfill_merchant <merchant_id>
 
 ---
 
+### 8. Shipment 模型兼容外部遗留系统字段
+
+为出货单与外部系统对接预留字段与模型（暂未接入业务逻辑/API）。
+
+#### Shipment 新增字段/方法
+- `status`：状态（待送货 / 已交付 / 已取消），默认「待送货」
+- `cancelled_at`：取消时间（可空）
+- `cancelled_by`：取消人（可空，绑定用户）
+- `external_id`：外部订单号（可空，长度 120）
+- `external_finished_products`：关联多个“外部成品表”（一对多，外键在外部成品表侧）
+- `cancel(operator)`：取消出货单时自动记录取消时间与操作者
+
+#### 新增模型：ExternalFinishedProduct（外部成品表）
+- 字段：`style_name`、`num_of_rolls`、`created_at`（来自 ModelBase）、`created_by`
+
+#### Migration
+- `shipment/migrations/0004_add_external_finished_product_and_shipment_status.py`
+- `shipment/migrations/0005_fix_shipment_external_finished_product_relation.py`（修正关系方向：Shipment 1→N ExternalFinishedProduct）
+
+#### 测试
+- 运行 `api_v1.views.shipment.test_api`：13 个测试通过
+
+---
+
 ## 待办
 
 ---

docs/shipment_api.md

@@ -246,3 +246,14 @@ curl -X GET \
 - `shipment/services.py`: 业务逻辑层
 - `api_v1/views/shipment/`: API 视图层
 - `shipment/models.py`: 数据模型（SalesItem, Shipment）
+
+---
+
+## 外部系统兼容（数据模型说明）
+
+为兼容外部遗留系统，Shipment 模块新增了“外部成品表”模型：
+
+- **关系**：`Shipment` 1 → N `ExternalFinishedProduct`
+  - 外键在 `ExternalFinishedProduct.shipment`（可空）
+- **Shipment 外部字段**：
+  - `external_id`：外部订单号（可空）

shipment/migrations/0004_add_external_finished_product_and_shipment_status.py

@@ -0,0 +1,58 @@
+# Generated by Django 5.2.8 on 2026-01-14 10:59
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('shipment', '0003_salesitem_position_remark'),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='shipment',
+            name='cancelled_at',
+            field=models.DateTimeField(blank=True, null=True, verbose_name='取消时间'),
+        ),
+        migrations.AddField(
+            model_name='shipment',
+            name='cancelled_by',
+            field=models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='cancelled_shipments', to=settings.AUTH_USER_MODEL, verbose_name='取消人'),
+        ),
+        migrations.AddField(
+            model_name='shipment',
+            name='external_id',
+            field=models.CharField(blank=True, help_text='用于兼容外部遗留系统的订单号（可空）', max_length=120, null=True, verbose_name='外部订单号'),
+        ),
+        migrations.AddField(
+            model_name='shipment',
+            name='status',
+            field=models.IntegerField(choices=[(1, '待送货'), (2, '已交付'), (3, '已取消')], default=1, verbose_name='状态'),
+        ),
+        migrations.CreateModel(
+            name='ExternalFinishedProduct',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created_at', models.DateTimeField(auto_now_add=True, verbose_name='创建时间')),
+                ('updated_at', models.DateTimeField(auto_now=True, verbose_name='更新时间')),
+                ('style_name', models.CharField(max_length=200, verbose_name='款式名称')),
+                ('num_of_rolls', models.PositiveIntegerField(verbose_name='卷数')),
+                ('created_by', models.ForeignKey(null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='created_external_finished_products', to=settings.AUTH_USER_MODEL, verbose_name='创建人')),
+            ],
+            options={
+                'verbose_name': '外部成品表',
+                'verbose_name_plural': '外部成品表',
+                'db_table': 'external_finished_product',
+                'ordering': ['-created_at'],
+            },
+        ),
+        migrations.AddField(
+            model_name='shipment',
+            name='external_finished_product',
+            field=models.ForeignKey(blank=True, help_text='用于兼容外部遗留系统（可空）', null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='shipments', to='shipment.externalfinishedproduct', verbose_name='外部成品表'),
+        ),
+    ]

shipment/migrations/0005_fix_shipment_external_finished_product_relation.py

@@ -0,0 +1,23 @@
+# Generated by Django 5.2.8 on 2026-01-14 11:05
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('shipment', '0004_add_external_finished_product_and_shipment_status'),
+    ]
+
+    operations = [
+        migrations.RemoveField(
+            model_name='shipment',
+            name='external_finished_product',
+        ),
+        migrations.AddField(
+            model_name='externalfinishedproduct',
+            name='shipment',
+            field=models.ForeignKey(blank=True, help_text='关联的出货单（可空，兼容历史数据/逐步迁移）', null=True, on_delete=django.db.models.deletion.CASCADE, related_name='external_finished_products', to='shipment.shipment', verbose_name='出货单'),
+        ),
+    ]

shipment/models.py

@@ -3,6 +3,7 @@ from typing import TYPE_CHECKING
 
 from django.db import models
 from django.contrib.auth import get_user_model
+from django.utils import timezone
 from flower.common import ModelBase
 from basic_info import models as basic_models
 
@@ -20,12 +21,88 @@ class UnitChoices(models.IntegerChoices):
     UNIT = 4, '个'
 
 
+class ShipmentStatus(models.IntegerChoices):
+    """出货单状态"""
+    PENDING_DELIVERY = 1, '待送货'
+    DELIVERED = 2, '已交付'
+    CANCELLED = 3, '已取消'
+
+
+class ExternalFinishedProduct(ModelBase):
+    """
+    外部成品表
+    
+    用于兼容外部遗留系统的数据映射（可被多个出货单引用）。
+    """
+    style_name = models.CharField(
+        max_length=200,
+        verbose_name='款式名称',
+    )
+    num_of_rolls = models.PositiveIntegerField(
+        verbose_name='卷数',
+    )
+    created_by = models.ForeignKey(
+        User,
+        on_delete=models.SET_NULL,
+        null=True,
+        related_name='created_external_finished_products',
+        verbose_name='创建人',
+    )
+    shipment = models.ForeignKey(
+        'Shipment',
+        on_delete=models.CASCADE,
+        null=True,
+        blank=True,
+        related_name='external_finished_products',
+        verbose_name='出货单',
+        help_text='关联的出货单（可空，兼容历史数据/逐步迁移）',
+    )
+
+    class Meta:
+        db_table = 'external_finished_product'
+        verbose_name = '外部成品表'
+        verbose_name_plural = '外部成品表'
+        ordering = ['-created_at']
+
+    def __str__(self) -> str:
+        return f'{self.style_name} ({self.num_of_rolls}卷)'
+
+
 class Shipment(ModelBase):
     """
     出货单
     
     记录一次出货操作，包含多个销售品。
     """
+    status = models.IntegerField(
+        choices=ShipmentStatus.choices,
+        default=ShipmentStatus.PENDING_DELIVERY,
+        verbose_name='状态',
+    )
+
+    cancelled_at = models.DateTimeField(
+        null=True,
+        blank=True,
+        verbose_name='取消时间',
+    )
+
+    cancelled_by = models.ForeignKey(
+        User,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name='cancelled_shipments',
+        verbose_name='取消人',
+    )
+
+    external_id = models.CharField(
+        max_length=120,
+        null=True,
+        blank=True,
+        verbose_name='外部订单号',
+        help_text='用于兼容外部遗留系统的订单号（可空）',
+    )
+
     customer = models.ForeignKey(
         basic_models.Customer,
         on_delete=models.PROTECT,
@@ -61,6 +138,18 @@ class Shipment(ModelBase):
     def __str__(self):
         return f'出货单 #{self.id} - {self.customer.name}'
 
+    def cancel(self, operator: User | None) -> None:
+        """
+        取消出货单（记录取消时间与操作者）
+        
+        Args:
+            operator: 操作者（通常为 request.user，可为空）
+        """
+        self.status = ShipmentStatus.CANCELLED
+        self.cancelled_at = timezone.now()
+        self.cancelled_by = operator
+        self.save(update_fields=['status', 'cancelled_at', 'cancelled_by', 'updated_at'])
+
 
 class SalesItem(ModelBase):
     """