## 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"
    }
  ]
}
```