erpnew/docs/sales_item_merge_remark_api.md

销售品合卷备注（merge_remark）API 变更说明

变更日期：2026-04-06

---

概述

SalesItem（销售品）模型新增可空 JSON 字段 merge_remark，用于记录该销售品由多个生产子单合卷产生时的合卷信息。

本次变更涉及：

• 创建销售品（POST）：新增可选入参 merge_remark，传入时进行结构校验
• 所有返回销售品对象的接口：响应体中新增 merge_remark 字段
• 更新销售品（PATCH）：不支持传入 merge_remark，不受影响

---

一、受影响的 API

1. 创建销售品（新增入参）

POST /api/v1/shipment/sales-items/

请求体新增可选字段 merge_remark，不传或传 null 均视为无合卷信息。

完整请求参数

字段	类型	必填	说明
printing_job_id	integer	是	生产任务ID
name	string	是	销售品名称
quantity	string	是	数量（支持小数）
unit	integer	是	单位：1=米, 2=件, 3=码, 4=个
customer_id	integer	否	客户ID
remark	string	否	备注
position	string	否	货位
merge_remark	object | null	否	合卷备注（见下方结构说明）

merge_remark 结构

传入时必须严格符合以下结构，字段不可多、不可少：

字段	类型	说明
merge_type	string	合卷类型标识，固定传 "combined_jobs"
jobs	integer[]	参与本次合卷的所有子单ID（printing_job_id）列表，至少 2 个元素
main_job	integer	主子单ID，必须是 jobs 列表中的成员
quantity	string	本次合卷销售品的最终数量，字符串形式
unit	string	数量单位，如 "meter"
job_count	integer	参与合卷的子单数量，必须等于 jobs 列表的长度

请求示例（含 merge_remark）

{
  "printing_job_id": 9777,
  "name": "某款合卷布料",
  "quantity": "647",
  "unit": 1,
  "merge_remark": {
    "merge_type": "combined_jobs",
    "jobs": [9777, 9776],
    "main_job": 9777,
    "quantity": "647",
    "unit": "meter",
    "job_count": 2
  }
}

响应示例（201 Created）

{
  "id": 101,
  "name": "某款合卷布料",
  "quantity": "647.00",
  "unit": 1,
  "unit_display": "米",
  "position": "",
  "remark": "",
  "printing_job_id": 9777,
  "printing_order_id": 55,
  "external_order_id": null,
  "customer_id": 12,
  "customer_name": "某客户",
  "shipment_id": null,
  "shipment_date": null,
  "merge_remark": {
    "merge_type": "combined_jobs",
    "jobs": [9777, 9776],
    "main_job": 9777,
    "quantity": "647",
    "unit": "meter",
    "job_count": 2
  },
  "created_at": "2026-04-06T10:00:00Z",
  "created_by_id": 1,
  "created_by_name": "张三"
}

merge_remark 校验错误响应（400 Bad Request）

缺少必填字段：

{
  "merge_remark": ["缺少必填字段: ['job_count', 'main_job']"]
}

包含未知字段：

{
  "merge_remark": ["包含未知字段: ['extra_field']"]
}

字段类型错误（如 main_job 传了字符串）：

{
  "merge_remark": ["字段 'main_job' 类型错误，期望 int，实际 str"]
}

jobs 列表元素不是整数：

{
  "merge_remark": ["jobs 列表中的元素必须为整数"]
}

jobs 少于 2 个元素：

{
  "merge_remark": ["jobs 列表至少需要包含 2 个子单ID"]
}

main_job 不在 jobs 中：

{
  "merge_remark": ["main_job 必须是 jobs 列表中的一个成员"]
}

job_count 与 jobs 长度不一致：

{
  "merge_remark": ["job_count (3) 与 jobs 长度 (2) 不一致"]
}

---

2. 获取销售品详情（新增返回字段）

GET /api/v1/shipment/sales-items/<id>/

响应体新增 merge_remark 字段。无合卷信息时值为 null。

---

3. 按客户查询销售品列表（新增返回字段）

GET /api/v1/shipment/sales-items/by-customer/<customer_id>/

列表中每条销售品对象新增 merge_remark 字段。

---

4. 按生产订单查询销售品列表（新增返回字段）

GET /api/v1/shipment/sales-items/by-printing-order/<printing_order_id>/

列表中每条销售品对象新增 merge_remark 字段。

---

5. 出货单详情中的嵌套销售品列表（新增返回字段）

GET /api/v1/shipment/shipments/<id>/

响应体 sales_items 数组中每条销售品对象新增 merge_remark 字段。

---

二、不受影响的 API

端点	说明
PATCH /api/v1/shipment/sales-items/<id>/	更新销售品，不接受 merge_remark 参数，传入会被忽略
POST /api/v1/shipment/sales-items/<id>/rebuild/	重建销售品，不涉及 merge_remark
POST /api/v1/shipment/shipments/	创建出货单，不涉及 merge_remark

---

三、merge_remark 为 null 的情况

普通销售品（非合卷）创建时不传 merge_remark，返回值中该字段为 null：

{
  "id": 102,
  "name": "普通布料",
  "quantity": "200.00",
  ...
  "merge_remark": null
}

前端展示时直接判断 merge_remark !== null 即可区分是否为合卷销售品。