fix: added merchant_id in models of shipment module

docs/2026-01-14_summary.md

@@ -156,6 +156,39 @@ python manage.py backfill_merchant <merchant_id>
 
 ---
 
+### 9. Shipment 创建 API：普通版 & External 版
+
+新增并完善了两个创建出货单接口：
+
+#### 普通版（绑定销售品）
+- **接口**：`POST /api/v1/shipment/shipments/`
+- **参数**：`sales_items: [销售品ID...]`
+- **行为**：创建出货单并把销售品关联到该出货单
+
+#### External 版（不绑定销售品 + 外部成品表批量写入）
+- **接口**：`POST /api/v1/shipment/shipments/external/`
+- **参数**：
+  - `external_id` 必填
+  - `external_finished_products`（数组）必填，用于写入 `ExternalFinishedProduct` 并关联到 Shipment
+- **行为**：创建出货单 + 批量创建外部成品表记录（不关联任何销售品）
+
+#### 代码位置
+- `shipment/services.py`: 新增 `create_external_shipment()`
+- `api_v1/views/shipment/views.py`: 新增 `ShipmentExternalCreateView`
+- `api_v1/views/shipment/serializers.py`: 新增 external 创建序列化器与响应字段扩展
+- `api_v1/urls.py`: 注册 external 创建路由
+- `api_v1/views/shipment/test_api.py`: 新增 external create 测试
+
+#### merchant 强制归属（非空）
+- 为 `Shipment` 与 `SalesItem` 增加 `merchant` 外键且不允许为空
+- 创建时从 `request.user.employee.merchant` 自动绑定，并校验 customer 同商户
+- 普通版在关联销售品时校验销售品同商户，避免跨商户关联
+
+#### 文档
+- `docs/shipment_api.md`: 补充 external create API 文档
+
+---
+
 ## 待办
 
 ---

docs/shipment_api.md

@@ -44,6 +44,8 @@
 ```json
 {
     "id": 1,
+    "merchant_id": 1,
+    "merchant_name": "测试印花厂",
     "customer": 1,
     "customer_name": "客户A",
     "shipment_date": "2026-01-14",
@@ -61,6 +63,8 @@
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | id | int | 出货单ID |
+| merchant_id | int | 所属商户ID（从当前登录用户推导） |
+| merchant_name | string | 所属商户名称（从当前登录用户推导） |
 | customer | int | 客户ID |
 | customer_name | string | 客户名称 |
 | shipment_date | string | 出货日期 |
@@ -99,6 +103,94 @@
 
 ---
 
+## 创建出货单（external 版）
+
+创建出货单但**不绑定任何销售品**，同时写入并关联“外部成品表”（用于兼容外部遗留系统）。
+
+### 接口信息
+
+- **URL**: `/api/v1/shipment/shipments/external/`
+- **Method**: `POST`
+- **认证**: 需要登录（JWT Token）
+
+### 请求参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| customer | int | 是 | 客户ID |
+| shipment_date | string | 是 | 出货日期（YYYY-MM-DD） |
+| remark | string | 否 | 备注 |
+| external_id | string | 是 | 外部订单号（长度<=120） |
+| external_finished_products | array[object] | 是 | 外部成品表结构数组（至少 1 条） |
+
+`external_finished_products` 每项结构：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| style_name | string | 是 | 款式名称 |
+| num_of_rolls | int | 是 | 卷数 |
+
+### 请求示例
+
+```json
+{
+  "customer": 1,
+  "shipment_date": "2026-01-14",
+  "remark": "external 备注（可选）",
+  "external_id": "EXT-ORDER-001",
+  "external_finished_products": [
+    {"style_name": "款式A", "num_of_rolls": 2},
+    {"style_name": "款式B", "num_of_rolls": 5}
+  ]
+}
+```
+
+### 响应示例
+
+```json
+{
+  "id": 1,
+  "merchant_id": 1,
+  "merchant_name": "测试印花厂",
+  "customer": 1,
+  "customer_name": "客户A",
+  "shipment_date": "2026-01-14",
+  "remark": "external 备注（可选）",
+  "status": 1,
+  "status_display": "待送货",
+  "external_id": "EXT-ORDER-001",
+  "cancelled_at": null,
+  "cancelled_by_id": null,
+  "cancelled_by_name": null,
+  "items_count": 0,
+  "external_finished_products_count": 2,
+  "created_by_id": 1,
+  "created_by_name": "张三",
+  "created_at": "2026-01-14T10:00:00Z",
+  "updated_at": "2026-01-14T10:00:00Z"
+}
+```
+
+### 错误响应
+
+#### 400 Bad Request - external_id 为空
+
+```json
+{
+  "external_id": ["external_id 不能为空"]
+}
+```
+
+#### 400 Bad Request - external_finished_products 为空
+
+```json
+{
+  "external_finished_products": ["external_finished_products 不能为空"]
+}
+```
+
+---
+
 ## 通过生产订单查询销售品
 
 查询与指定生产订单（PrintingOrder）关联的所有销售品（SalesItem）。