feat: shipment patch

docs/shipment_api.md

@@ -28,7 +28,7 @@
 | limit | int | 分页大小（LimitOffsetPagination） |
 | offset | int | 偏移量 |
 | customer | int | 客户ID |
-| status | int | 状态（1=待送货, 2=已交付, 3=已取消） |
+| status | int | 状态（1=草稿(未发布), 2=已发布, 3=已取消, 4=已驳回, 5=已审核） |
 | external_id | string | 外部订单号（精确匹配） |
 | shipment_date_from | string | 出货日期起始（YYYY-MM-DD） |
 | shipment_date_to | string | 出货日期结束（YYYY-MM-DD） |
@@ -50,6 +50,13 @@
       "customer": 1,
       "customer_name": "客户A",
       "shipment_date": "2026-01-14",
+      "status": 1,
+      "status_display": "草稿(未发布)",
+      "status_modified_at": null,
+      "cancelled_by_id": null,
+      "cancelled_by_name": null,
+      "approved_by_id": null,
+      "approved_by_name": null,
       "remark": "备注信息",
       "items_count": 3,
       "sales_items": [],
@@ -69,12 +76,25 @@
 - **Method**: `GET`
 - **认证**: 需要登录（JWT Token）
 
+#### 查询参数（可选）
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| status | int | 可选状态过滤；取值为 1=草稿(未发布), 2=已发布, 3=已取消, 4=已驳回, 5=已审核。传入后仅当该出货单状态匹配时才返回详情 |
+
 ---
 
 ## 创建出货单
 
 创建出货单并关联销售品。
 
+业务规则补充：
+
+- 当 `sales_items` 非空时，所有销售品都必须关联有效的 `printing_job`
+- 并且这些销售品必须全部来自同一个 `printing_order`
+- 如果存在缺少生产任务、生产任务不存在、或跨生产订单混装，接口会拒绝创建
+- 新创建的出货单默认状态为 `草稿(未发布)`
+
 ### 接口信息
 
 - **URL**: `/api/v1/shipment/shipments/`
@@ -115,6 +135,13 @@
     "shipment_date": "2026-01-14",
     "area": "华东",
     "remark": "备注信息",
+    "status": 1,
+    "status_display": "草稿(未发布)",
+    "status_modified_at": null,
+    "cancelled_by_id": null,
+    "cancelled_by_name": null,
+    "approved_by_id": null,
+    "approved_by_name": null,
     "items_count": 3,
     "sales_items": [],
     "external_finished_products": [],
@@ -137,12 +164,29 @@
 | shipment_date | string | 出货日期 |
 | area | string | 出货地区 |
 | remark | string | 备注 |
+| status | int | 状态枚举（1=草稿(未发布), 2=已发布, 3=已取消, 4=已驳回, 5=已审核） |
+| status_display | string | 状态显示名称 |
+| status_modified_at | string/null | 最后一次状态修改时间 |
+| cancelled_by_id | int/null | 取消人 ID，仅当进入已取消时可能有值 |
+| cancelled_by_name | string/null | 取消人名称，仅当进入已取消时可能有值 |
+| approved_by_id | int/null | 审核人 ID，仅当进入已审核时可能有值 |
+| approved_by_name | string/null | 审核人名称，仅当进入已审核时可能有值 |
 | items_count | int | 关联的销售品数量 |
 | created_by_id | int | 创建人ID |
 | created_by_name | string | 创建人名称 |
 | created_at | string | 创建时间 |
 | updated_at | string | 更新时间 |
 
+### 状态流转规则
+
+- `草稿(未发布)` 只能流转到 `已发布`
+- `已发布` 可以流转到 `已审核` / `已驳回` / `已取消`
+- `已驳回` 可以流转到 `已审核` / `已取消`
+- `已审核` 可以流转到 `已取消`
+- `已取消` 不可再流转到其他状态
+- 重复设置同一状态保持幂等，不报错
+- 进入 `已审核` 时必须提供审核人
+
 ### 错误响应
 
 #### 400 Bad Request - 客户不存在
@@ -169,6 +213,30 @@
 }
 ```
 
+#### 400 Bad Request - 销售品缺少关联生产任务
+
+```json
+{
+    "detail": "以下销售品缺少关联生产任务，无法创建出货单: [1]"
+}
+```
+
+#### 400 Bad Request - 销售品关联的生产任务不存在
+
+```json
+{
+    "detail": "以下销售品关联的生产任务不存在，无法创建出货单: [1]"
+}
+```
+
+#### 400 Bad Request - 销售品来自不同生产订单
+
+```json
+{
+    "detail": "出货单中的销售品必须来自同一个生产订单"
+}
+```
+
 ---
 
 ## 创建出货单（external 版）
@@ -229,11 +297,13 @@
   "area": "华南",
   "remark": "external 备注（可选）",
   "status": 1,
-  "status_display": "待送货",
+  "status_display": "草稿(未发布)",
   "external_id": "EXT-ORDER-001",
-  "cancelled_at": null,
+  "status_modified_at": null,
   "cancelled_by_id": null,
   "cancelled_by_name": null,
+  "approved_by_id": null,
+  "approved_by_name": null,
   "items_count": 0,
   "external_finished_products_count": 2,
   "created_by_id": 1,