zuowei/erpnew
1
0
Fork 0
forked from erp-dev/erp
Code Pull Requests Activity
Files
36e4bb6de637d155562ebc693366343cc4c37818
erpnew/docs/shipment_delivery.md

7.7 KiB
Raw Blame History

Shipment Delivery API

本文档说明 shipment 模块中的“送货单”模型及相关 API。

业务说明

送货单用于表示一次具体的送货行为。

特点：

  • 一个送货单可关联多个出货单
  • 一个出货单最多属于一个送货单
  • 送货单与出货单关系为一对多
  • 送货单使用独立状态流转，不复用出货单状态

状态枚举

送货单状态定义如下：

  • 1 = 待送货
  • 2 = 送货中
  • 3 = 已送达
  • 4 = 已取消

状态机规则：

  • 待送货 -> 送货中
  • 送货中 -> 已送达
  • 不允许回退
  • 重复设置同一状态时保持幂等，直接返回当前对象
  • 已取消 为终态

时间字段规则：

  • 进入 送货中 时写入 started_at
  • 进入 已送达 时写入 delivered_at

模型字段

送货单模型包含以下核心字段：

  • id
  • merchant
  • driver_name
  • vehicle_trip
  • contact_phone
  • vehicle_capacity
  • remark
  • internal_remark
  • shipment_order_ids
  • status
  • started_at
  • delivered_at
  • created_by
  • operator
  • cancelled_at
  • cancelled_by
  • created_at
  • updated_at

说明：

  • driver_name 已加索引
  • vehicle_trip 已加索引
  • status 已加索引
  • created_by 为系统用户 User
  • operator 为业务员工 Employee
  • merchant 用于多商户隔离
  • 创建、修改、状态流转时，会根据 request.user.employee 自动写入 operator
  • 取消送货单时会写入 cancelled_at 与 cancelled_by
  • shipment_order_ids 是前端自管的出货单顺序 JSON 字段；后端只保存和返回，不据此自动排序 shipments

API 列表

1. 查询送货单列表

  • GET /api/v1/shipment/deliveries/

支持查询参数：

  • status
  • driver_name
  • vehicle_trip
  • limit
  • offset

查询说明：

  • status 为精确匹配
  • driver_name 为包含匹配
  • vehicle_trip 为包含匹配

示例：

GET /api/v1/shipment/deliveries/?status=2&driver_name=张&vehicle_trip=001&limit=20&offset=0

返回示例：

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "merchant_id": 1,
      "merchant_name": "测试印花厂",
      "driver_name": "张司机",
      "vehicle_trip": "KD-001",
      "contact_phone": "13800138000",
      "vehicle_capacity": "9.6米厢车",
      "remark": "先装车",
      "internal_remark": "注意对账",
      "shipment_order_ids": [11, 10],
      "status": 1,
      "status_display": "待送货",
      "started_at": null,
      "delivered_at": null,
      "cancelled_at": null,
      "shipments_count": 2,
      "shipments": [
        {
          "id": 10,
          "customer": 5,
          "customer_name": "客户A",
          "order_description": null,
          "shipment_date": "2026-04-03",
          "status": 2,
          "status_display": "已发布",
          "external_id": null
        }
      ],
      "created_by_id": 8,
      "created_by_name": "测试员工",
      "operator_id": 3,
      "operator_name": "测试员工",
      "cancelled_by_id": null,
      "cancelled_by_name": null,
      "created_at": "2026-04-03T10:00:00+08:00",
      "updated_at": "2026-04-03T10:00:00+08:00"
    }
  ]
}

2. 创建送货单

  • POST /api/v1/shipment/deliveries/

请求体：

{
  "driver_name": "张司机",
  "vehicle_trip": "KD-001",
  "contact_phone": "13800138000",
  "vehicle_capacity": "9.6米厢车",
  "remark": "先装车",
  "internal_remark": "注意对账",
  "shipment_order_ids": [11, 10],
  "shipments": [10, 11]
}

字段说明：

  • driver_name: 必填，司机名
  • vehicle_trip: 必填，车次
  • contact_phone: 可选，联系电话
  • vehicle_capacity: 可选，车辆容量
  • remark: 可选，备注
  • internal_remark: 可选，内部备注
  • shipment_order_ids: 可选，前端自管的出货单顺序 JSON 数组；可传 null；未传时默认 []
  • shipments: 可选，出货单 ID 列表

创建规则：

  • 只能绑定当前用户所属商户的出货单
  • 只能绑定状态为 已审核 的出货单
  • 已绑定到其他送货单的出货单不能重复绑定
  • 创建接口不支持直接传入 status

3. 查询送货单详情

  • GET /api/v1/shipment/deliveries/{id}/

返回字段与列表单项一致，但会返回完整 shipments 摘要数组。

4. 修改送货单

  • PATCH /api/v1/shipment/deliveries/{id}/
  • PUT /api/v1/shipment/deliveries/{id}/

请求体示例：

{
  "driver_name": "李司机",
  "vehicle_trip": "KD-001-B",
  "contact_phone": "13700137000",
  "vehicle_capacity": "13米高栏",
  "remark": "改派车辆",
  "internal_remark": "已电话确认",
  "shipment_order_ids": [11, 12],
  "shipments": [11, 12]
}

修改规则：

  • driver_name、vehicle_trip、contact_phone、vehicle_capacity、remark、internal_remark 可单独修改
  • shipment_order_ids 按普通字段处理，后端仅保存与返回；值必须是数组或 null
  • shipments 如果传入，则视为“整体替换当前绑定的出货单集合”
  • 替换绑定时，出货单仍然必须满足“当前商户、已审核、未绑定到其他送货单”
  • 更新接口不支持直接修改 status

5. 删除送货单

  • DELETE /api/v1/shipment/deliveries/{id}/

行为说明：

  • 删除送货单时，会先解除与其关联的出货单绑定
  • 删除成功返回 204 No Content

6. 修改送货单状态

  • POST /api/v1/shipment/deliveries/{id}/status/

请求体：

{
  "status": 2
}

状态取值：

  • 1 = 待送货
  • 2 = 送货中
  • 3 = 已送达

规则说明：

  • 只允许按状态机顺序流转
  • 不允许回退
  • 相同状态重复提交保持幂等
  • 成功改到 送货中 时写入 started_at
  • 成功改到 已送达 时写入 delivered_at
  • 该接口不用于取消送货单

7. 取消送货单

  • POST /api/v1/shipment/deliveries/{id}/cancel/

权限要求：

  • 需要 Django 权限：shipment.cancel_shipmentdelivery

请求体：

{}

行为说明：

  • 将送货单状态改为 已取消
  • 写入 cancelled_at
  • 写入 cancelled_by
  • 同时会根据 request.user.employee 更新 operator
  • 取消不会释放或解绑当前已关联的出货单；如需解绑，需显式删除送货单或通过修改接口改绑
  • 已取消的送货单再次取消保持幂等

8. 追加绑定出货单到已有送货单

  • POST /api/v1/shipment/deliveries/{id}/bind-shipments/

请求体：

{
  "shipments": [12, 13]
}

规则说明：

  • 该接口是“追加绑定”，不会替换当前已有绑定
  • 只允许绑定当前用户所属商户的出货单
  • 出货单必须处于 已审核 状态
  • 已绑定到其他送货单的出货单不能再次绑定
  • 成功后会根据 request.user.employee 更新 operator

Service 设计

送货单的业务写入逻辑统一放在 shipment/services.py 中：

  • create_shipment_delivery(...)
  • update_shipment_delivery(...)
  • modify_shipment_delivery_status(...)
  • cancel_shipment_delivery(...)
  • delete_shipment_delivery(...)

说明：

  • list / detail 属于简单只读查询，直接由 API 查询集处理
  • create / update / delete / status modify 均通过 service 完成

测试覆盖

已补充以下测试方向：

  • 创建送货单并绑定多个出货单
  • 绑定已属于其他送货单的出货单时报错
  • 绑定非当前商户出货单时报错
  • 列表支持 status / driver_name / vehicle_trip 查询
  • 详情返回关联出货单摘要
  • 更新送货单并替换绑定出货单
  • 创建、修改、状态流转会写入 operator
  • 取消送货单需要权限校验，并写入 cancelled_at / cancelled_by
  • 状态流转写入 started_at / delivered_at
  • 非法状态流转报错
  • 删除送货单后解除出货单绑定
View Git Blame Copy Permalink