erpnew/docs/shipment_status_api.md

Shipment Status API 文档

本文档仅说明 Shipment 出货单状态流转接口。

接口信息

• URL: /api/v1/shipment/shipments/{id}/status/
• Method: PATCH / PUT
• 认证: 需要登录（JWT Token）

说明：

• 该接口只负责修改 Shipment.status
• 业务字段修改仍然使用 /api/v1/shipment/shipments/{id}/
• PATCH 与 PUT 当前行为一致，都是按请求体中的 status 执行状态流转

请求体

{
  "status": 2
}

字段说明：

• status: 目标状态
  • 1 = 草稿(未发布)
  • 2 = 已发布
  • 3 = 已取消
  • 4 = 已驳回
  • 5 = 已审核

状态机规则

• 草稿(未发布) 只能流转到 已发布
• 已发布 可以流转到 已审核 / 已驳回 / 已取消
• 已驳回 可以流转到 已审核 / 已取消
• 已审核 可以流转到 已取消
• 已取消 不可再流转
• 重复设置同一状态时保持幂等

附加规则：

• 进入 已审核 时，接口会自动将当前 request.user 写入 approved_by
• 进入 已取消 时，接口会自动将当前 request.user 写入 cancelled_by
• 每次成功状态流转都会更新 status_modified_at

请求示例

1. 草稿发布

PATCH /api/v1/shipment/shipments/12/status/
Content-Type: application/json

{
  "status": 2
}

2. 已发布审核

PUT /api/v1/shipment/shipments/12/status/
Content-Type: application/json

{
  "status": 5
}

成功响应示例

{
  "id": 12,
  "merchant_id": 1,
  "merchant_name": "测试印花厂",
  "customer": 8,
  "customer_name": "客户A",
  "shipment_date": "2026-04-06",
  "address": "",
  "contact_name": "",
  "contact_phone": "",
  "area": "",
  "remark": "",
  "status": 5,
  "status_display": "已审核",
  "external_id": null,
  "status_modified_at": "2026-04-06T14:30:00+08:00",
  "cancelled_by_id": null,
  "cancelled_by_name": null,
  "approved_by_id": 3,
  "approved_by_name": "测试员工",
  "items_count": 2,
  "sales_items": [],
  "external_finished_products": [],
  "created_by_id": 3,
  "created_by_name": "测试员工",
  "created_at": "2026-04-06T10:00:00+08:00",
  "updated_at": "2026-04-06T14:30:00+08:00"
}

错误响应示例

1. 非法流转

{
  "detail": "不允许将出货单状态从 草稿(未发布) 修改为 已审核"
}

2. 越权或对象不存在

{
  "detail": "Not found."
}

3. 请求体不合法

{
  "status": [
    "\"99\" is not a valid choice."
  ]
}