erpnew/docs/api_v1_printing_order_api_2026-06-26.md

API v1 印染订单接口说明（printing-orders）

版本日期：2026-06-26

本文档仅汇总 /api/v1/printing-orders/ 相关接口，按当前代码实现整理，用于前端核对和更新字段。

基本信息

• 基础路径：/api/v1/printing-orders/
• 认证：需要登录认证。
• 权限：使用 DjangoModelPermissions，且用户必须关联印染工厂类型商户。
• 数据范围：默认按客户可见性过滤；拥有 printing.view_all_printingorders 权限可查看全部客户订单。
• 分页：列表接口使用 limit / offset，响应为 DRF LimitOffset 格式：count、next、previous、results。
• 列表缓存：列表接口有 20 秒缓存。
• 删除：不支持物理删除，请使用作废接口。

本版重点字段变更

以下字段是当前接口已返回/支持、前端需要重点核对的字段：

• merchant_id：列表和详情返回，当前订单所属商户 ID，可能为 null。
• external_order_id：外部订单编号；列表、详情返回；创建/更新也允许传入；支持过滤。
• external_customer_id：外部客户 ID；列表、详情返回。
• external_customer_name：外部客户名称；列表、详情返回。
• external_employee_name：外部员工名称；列表、详情返回。
• created_by：列表返回，创建人用户 ID。
• created_by_name：列表、详情返回，创建人关联员工姓名，可能为 null。
• order_number：新增查询参数，支持同时按 external_order_id 和内部订单号逻辑检索。
• jobs_status_summary：仅列表返回，订单下任务当前状态汇总。
• jobs_last_status_summary：仅列表返回，订单下任务最后完成状态汇总。

接口清单

方法	路径	说明
GET	/api/v1/printing-orders/	印染订单列表
POST	/api/v1/printing-orders/	创建印染订单
GET	/api/v1/printing-orders/{id}/	印染订单详情
PUT	/api/v1/printing-orders/{id}/	全量更新印染订单
PATCH	/api/v1/printing-orders/{id}/	部分更新印染订单
DELETE	/api/v1/printing-orders/{id}/	已禁用，返回 405
POST	/api/v1/printing-orders/{id}/invalidate/	作废订单
POST	/api/v1/printing-orders/{id}/activate/	恢复订单
POST	/api/v1/printing-orders/{id}/mark_fabric_received/	标记布料已收

列表接口

GET /api/v1/printing-orders/

查询参数

列表查询参数全部可选；不传任何过滤条件时，默认返回当前权限范围内的未作废订单。

参数	类型	必填	说明
limit	number	否	每页条数，默认 800，最大 1000
offset	number	否	偏移量
customer	number	否	客户 ID
external_order_id	string	否	外部订单编号，模糊匹配
order_number	string	否	订单号检索：模糊匹配 external_order_id，并尝试匹配内部 id / human_id 后 6 位
customer_name	string	否	客户名称，模糊匹配
customer_phone	string	否	客户电话，模糊匹配
fabric	string	否	面料，模糊匹配
is_urgent	boolean	否	是否紧急
is_fabric_received	boolean	否	布料是否已收
is_invalid	boolean	否	是否作废；未传时默认只返回未作废订单
area	string	否	地区，模糊匹配
outgoing_date_from	date/datetime	否	出货日期起始；支持 YYYY-MM-DD 或日期时间
outgoing_date_to	date/datetime	否	出货日期结束；传 YYYY-MM-DD 时包含整天
created_date_from	date	否	创建日期起始
created_date_to	date	否	创建日期结束；包含整天
search	string	否	搜索客户名称、面料、地区、工艺、描述
ordering	string	否	排序字段，支持 id、created_at、updated_at、outgoing_date、is_urgent、is_fabric_received、is_invalid，默认 -created_at

列表响应字段

results[] 每项字段：

列表响应字段均会返回；“可为空”表示字段值可能为 null、空字符串或空数组。

字段	类型	是否返回	可为空	说明
id	number	是	否	内部订单 ID
human_id	string	是	否	人类可读订单号，格式为 YYYYMMDD + 6 位 ID
merchant_id	number/null	是	是	所属商户 ID
customer	number	是	否	客户 ID
customer_name	string	是	否	客户名称
customer_phone	string/null	是	是	客户手机号
fabric	string	是	否	面料
width	string	是	否	幅宽
is_urgent	boolean	是	否	是否紧急
area	string/null	是	是	地区
address	string/null	是	是	地址
curve	string/null	是	是	曲线
is_fabric_received	boolean	是	否	布料是否已收
outgoing_date	datetime/null	是	是	出货日期时间
is_invalid	boolean	是	否	是否作废
new_curve	string/null	是	是	新加曲线
process	number/null	是	是	印染流程 ID
process_name	string/null	是	是	印染流程名称
progress	number	是	否	订单进度百分比；无任务时为 0
position	string/null	是	是	位置
print_count	number	是	否	打印次数
jobs_status_summary	array	是	是	订单下任务按当前状态汇总；无任务时为空数组
jobs_last_status_summary	array	是	是	订单下任务按最后完成状态汇总；无已完成状态时为空数组
external_order_id	string/null	是	是	外部订单编号
external_customer_id	string/null	是	是	外部客户 ID
external_customer_name	string/null	是	是	外部客户名称
external_employee_name	string/null	是	是	外部员工名称
created_by	number/null	是	是	创建人用户 ID
created_by_name	string/null	是	是	创建人关联员工姓名
created_at	datetime	是	否	创建时间
updated_at	datetime	是	否	更新时间

jobs_status_summary 格式：

[
  {
    "state_name": "待印染",
    "state_id": 1,
    "count": 3
  }
]

jobs_last_status_summary 格式：

[
  {
    "state_name": "印染中",
    "count": 2
  }
]

详情接口

GET /api/v1/printing-orders/{id}/

详情响应字段

详情响应字段均会返回；“可为空”表示字段值可能为 null 或空字符串。

字段	类型	是否返回	可为空	说明
id	number	是	否	内部订单 ID
human_id	string	是	否	人类可读订单号
merchant_id	number/null	是	是	所属商户 ID
customer	number	是	否	客户 ID
customer_name	string	是	否	客户名称
customer_phone	string/null	是	是	客户手机号
customer_area	string/null	是	是	客户区域
fabric	string	是	否	面料
width	string	是	否	幅宽
is_urgent	boolean	是	否	是否紧急
area	string/null	是	是	地区
address	string/null	是	是	地址
fabric_source	string/null	是	是	布料来源
is_fabric_received	boolean	是	否	布料是否已收
craft	string/null	是	是	工艺
description	string/null	是	是	订单描述
outgoing_date	datetime/null	是	是	出货日期时间
curve	string/null	是	是	曲线
new_curve	string/null	是	是	新加曲线
position	string/null	是	是	位置
created_by_name	string/null	是	是	创建人关联员工姓名
printing_warn	string/null	是	是	打印注意事项
rolling_warn	string/null	是	是	滚筒注意事项
production_warn	string/null	是	是	生产注意事项
external_order_id	string/null	是	是	外部订单编号
external_customer_id	string/null	是	是	外部客户 ID
external_customer_name	string/null	是	是	外部客户名称
external_employee_name	string/null	是	是	外部员工名称
is_invalid	boolean	是	否	是否作废
process	number/null	是	是	印染流程 ID
process_name	string/null	是	是	印染流程名称
progress	number	是	否	订单进度百分比
print_count	number	是	否	打印次数
created_at	datetime	是	否	创建时间
updated_at	datetime	是	否	更新时间

注意：详情接口不返回 jobs_status_summary 和 jobs_last_status_summary，这两个字段是列表专用字段。

创建接口

POST /api/v1/printing-orders/

请求字段

字段	类型	必填	可传空	默认/说明
customer	number	是	否	客户 ID
fabric	string	是	否	面料
width	string	是	否	幅宽
is_urgent	boolean	否	否	默认 false，是否紧急
area	string/null	否	是	地区
address	string/null	否	是	地址
fabric_source	string/null	否	是	布料来源
is_fabric_received	boolean	否	否	默认 false，布料是否已收
craft	string/null	否	是	工艺
description	string/null	否	是	订单描述
outgoing_date	date/datetime/null	否	是	出货日期时间；支持 YYYY-MM-DD、YYYY-MM-DD HH:mm、YYYY-MM-DD HH:mm:ss、ISO8601；仅传日期时按当天 00:00:00 处理
curve	string/null	否	是	曲线
new_curve	string/null	否	是	新加曲线
position	string/null	否	是	位置
printing_warn	string/null	否	是	打印注意事项
rolling_warn	string/null	否	是	滚筒注意事项
production_warn	string/null	否	是	生产注意事项
is_invalid	boolean	否	否	默认 false，是否作废
process	number/null	否	创建可空，更新不可改为空	印染流程 ID；创建不传或传空时使用系统默认流程；更新时不能改为空
external_order_id	string/null	否	是	外部订单编号

创建时后端会自动写入：

• merchant：从当前用户关联员工的商户取得。
• created_by：当前登录用户。
• process：未传时尝试使用系统默认印染流程。

创建请求示例

{
  "customer": 12,
  "fabric": "纯棉布料",
  "width": "150cm",
  "is_urgent": true,
  "area": "白云区",
  "address": "白云区xxx",
  "fabric_source": "客户提供",
  "is_fabric_received": false,
  "craft": "活性印花",
  "description": "测试订单描述",
  "outgoing_date": "2026-06-26",
  "printing_warn": "注意颜色",
  "rolling_warn": "注意温度",
  "production_warn": "质量检查",
  "external_order_id": "KD20410611"
}

成功响应使用创建/更新序列化器字段，通常包含请求字段及 id。

更新接口

PUT /api/v1/printing-orders/{id}/

PATCH /api/v1/printing-orders/{id}/

更新请求字段与创建接口一致。

必填规则：

• PUT 是全量更新，建议至少传 customer、fabric、width；未传的可写字段可能按 DRF 全量更新规则校验。
• PATCH 是部分更新，只需要传要修改的字段。
• id、human_id、merchant_id、created_by、created_by_name、external_customer_id、external_customer_name、external_employee_name、created_at、updated_at 等不作为请求字段提交。

流程修改限制

• 当订单下没有任务，或所有任务都未开始时，可以修改 process。
• 修改 process 时，后端会重建/重新绑定订单下未开始任务的流程实例。
• 如果存在任何已开始的 PrintingJob，修改 process 会返回 400。
• process 不能更新为空，否则返回错误。

错误示例：

{
  "process": ["存在已开始的印染任务，无法修改流程"]
}

或：

"存在已开始的印染任务，无法修改流程"

作废订单

POST /api/v1/printing-orders/{id}/invalidate/

权限：需要 printing.can_invalidate_printingorder。

成功响应：

{
  "detail": "订单已作废",
  "data": {
    "id": 1
  }
}

失败情况：

• 无权限：403，{"detail": "您没有权限作废订单"}
• 已作废：400，{"detail": "该订单已经作废"}

恢复订单

POST /api/v1/printing-orders/{id}/activate/

权限：需要 printing.can_activate_printingorder。

成功响应：

{
  "detail": "订单已恢复",
  "data": {
    "id": 1
  }
}

失败情况：

• 无权限：403，{"detail": "您没有权限恢复订单"}
• 未作废：400，{"detail": "该订单未作废，无需恢复"}

标记布料已收

POST /api/v1/printing-orders/{id}/mark_fabric_received/

成功后将 is_fabric_received 置为 true。

成功响应：

{
  "detail": "已标记布料已收",
  "data": {
    "id": 1,
    "is_fabric_received": true
  }
}

失败情况：

• 已经标记为已收：400，{"detail": "布料已经标记为已收"}

删除接口

DELETE /api/v1/printing-orders/{id}/

该接口已禁用，固定返回 405：

{
  "detail": "印染订单不支持删除操作，请使用作废功能"
}

前端核对建议

• 列表页应优先使用 human_id 展示内部订单号，外部来源订单可同时展示 external_order_id。
• 默认列表不包含作废订单；作废订单列表需要显式传 is_invalid=true。
• 若前端有“订单号搜索”输入框，建议接入 order_number，不用同时拼多个参数。
• outgoing_date_to=YYYY-MM-DD 会包含当天整天，前端无需手动补 23:59:59。
• 外部字段 external_customer_id、external_customer_name、external_employee_name 当前只读返回，创建/更新接口只暴露 external_order_id。