feat: new api for plate order (get_plate_order_by_state_status)

docs/api_v2_plate_orders_by_state_status.md

@@ -0,0 +1,112 @@
+## 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`：该节点存在未撤销的 `StateFlowRecord`
+> - `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"
+    }
+  ]
+}
+```