erpnew/docs/api_v2_plate_orders_by_state_status.md

api_v2：按流程节点状态查询 PlateOrder 列表（process_id + state_id + status）

常见配套接口：

• GET /api/v1/stateflow/processes/{process_id}/nodes/（或等价的 business-objects/{bo_id}/process-nodes/）：用于获取指定流程的全部 ProcessNode/State 列表（含 order、state_id、参数模板等）。
• 请求 by-state-status 前通常先调用此接口拿到前端可选的节点，再结合节点信息发起状态过滤查询。

背景

• 同一个 state 可能复用在多个 process 中，因此查询必须同时提供 process_id 与 state_id
• 需要按节点状态（status）过滤 PlateOrder，并支持分页/排序
• 同时返回节点参数模板与订单在该节点的最新参数值

接口信息

• Method：GET
• Path：/api/v2/plate-orders/by-state-status/
• 认证：JWT（IsAuthenticated）
• 权限：仅允许印染/工厂侧用户（IsPrintingFactory）

Query 参数

参数	必填	类型	默认值	说明
process_id	是	int	-	stateflow.Process.id
state_id	否	int	-	stateflow.State.id。与 process_id 至少存在一条 ProcessNode 关联；为空时表示“查询整个流程尚未产生任何流转记录的订单”
status	否	string	completed	节点状态过滤，支持：completed / not_started / cancelled / in_progress
ordering	否	string	-created_at	排序字段，支持：id / created_at / updated_at / design_code（design_code 空值按主键字符串兜底）
limit	否	int	20	LimitOffsetPagination 的 limit
offset	否	int	0	LimitOffsetPagination 的 offset

status 说明：

• completed：该节点是订单最近一次未撤销完成的节点（同一订单不会因历史记录出现在多个节点）
• not_started：从未对该节点留下任何 StateFlowRecord
• cancelled：最近一次执行已被撤销（存在 is_cancelled=True 的记录，且无未撤销记录）
• in_progress：为后续扩展保留（当前流程模型中不会命中）
• state_id 为空时仅支持 not_started（忽略或填写其它值会报错）
• state_id 不为空时仅支持 completed / cancelled / in_progress

返回结构（200）

分页结构 + 节点/流程附加信息。

字段	类型	说明
process	object	流程信息 {id, name}
state	object|null	节点信息 {id, name, order, process_node_ids[]}；当 state_id 为空时为 null
status	string	本次查询的状态值
state_parameters	array	节点参数模板（[{key, value}]）
count / next / previous	同分页接口	-
results	array	PlateOrder 列表（见下）

results[*] 字段

字段	类型	说明
id	int	PlateOrder 主键
design_code	string|null	设计编号；为空时返回主键字符串
customer / customer_name	int / string	客户信息
style_name	string|null	款式名称
urgency_level	string	紧急程度
is_invalid	bool	是否作废
business_object_id	int|null	关联流程实例
created_by	int|null	创建人 ID
state_status	string	与查询参数一致（方便前端直接展示）
state_parameters	array	订单在该节点的最新参数值，key 顺序与模板一致，形如 [{"key": "temperature", "value": "30"}]，若从未提交过则 value=null；state_id 为空时恒为 []
state_log	object|null	该节点最新一次执行日志 {id, state_id, completed_at, completed_by, completed_by_username, is_cancelled}；status=not_started 时为 null
created_at / updated_at	string	ISO8601 时间戳

错误码

HTTP 状态	场景	detail
400	缺少/非法参数、state 不属于 process、不支持的 ordering/status	具体原因文本
401	未认证	DRF 默认
403	非工厂用户访问	您没有访问印染订单的权限
404	process 或 state 不存在	process 不存在 / state 不存在

示例

GET /api/v2/plate-orders/by-state-status/?process_id=10&state_id=25&status=completed&limit=20&offset=0

返回：

{
  "process": {"id": 10, "name": "开版流程"},
  "state": {"id": 25, "name": "调色", "order": 1, "process_node_ids": [42]},
  "status": "completed",
  "state_parameters": [{"key": "temperature", "value": "25"}],
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1001,
      "design_code": "PO-001",
      "customer": 5,
      "customer_name": "客户A",
      "style_name": "款式X",
      "urgency_level": "加急",
      "is_invalid": false,
      "business_object_id": 3001,
      "created_by": 12,
      "state_status": "completed",
      "state_parameters": [{"key": "temperature", "value": "30"}],
      "state_log": {
        "id": 888,
        "state_id": 25,
        "completed_at": "2025-12-20T08:00:00+08:00",
        "completed_by": 12,
        "completed_by_username": "factory_user",
        "is_cancelled": false
      },
      "created_at": "2025-12-18T09:00:00+08:00",
      "updated_at": "2025-12-18T10:00:00+08:00"
    }
  ]
}