# Printing API 文档

## 概述

本文档详细描述了 `printing` 模块下的所有 API 接口，包括印染订单 (`PrintingOrder`)、印染任务 (`PrintingJob`) 和开版订单 (`PlateOrder`) 的管理。

## 基础 URL

所有 `printing` 相关 API 都在以下基础路径下：

```
/api/v1/
```

## 认证与权限

- 所有接口都需要 JWT 认证。
- `PrintingOrder` 和 `PrintingJob` 接口需要用户是**印染工厂**类型商户 (`MerchantTypeEnum.FACTORY`)。
- `PlateOrder` 接口无此限制，但作废/恢复等操作需要特定权限。

---

## 1. Printing Orders API (印染订单)

**基础路径**: `/api/v1/printing-orders/`

管理印染生产的主订单。

### 1.1. 标准操作 (CRUD)

- **GET** `/api/v1/printing-orders/`
  - **描述**: 获取印染订单列表。
  - **查询参数**:
    - `customer`: 客户ID
    - `customer_name`: 客户名称 (模糊查询)
    - `customer_phone`: 客户电话 (模糊查询)
    - `fabric`: 面料 (模糊查询)
    - `is_urgent`: 是否紧急 (`true`/`false`)
    - `is_fabric_received`: 布料是否已收 (`true`/`false`)
    - `is_invalid`: 是否作废 (`true`/`false`)
    - `area`: 地区 (模糊查询)
    - `outgoing_date_from`/`to`: 出货日期范围
    - `created_date_from`/`to`: 创建日期范围
    - `search`: 全文搜索 (客户名称, 面料, 地区, 工艺)
    - `ordering`: 排序字段 (e.g., `-created_at`)
  - **响应**: `PrintingOrderListSerializer` 列表。

- **GET** `/api/v1/printing-orders/{id}/`
  - **描述**: 获取单个印染订单详情。
  - **响应**: `PrintingOrderDetailSerializer`。

- **POST** `/api/v1/printing-orders/`
  - **描述**: 创建一个新的印染订单。
  - **请求体**: `PrintingOrderCreateUpdateSerializer`。

- **PUT/PATCH** `/api/v1/printing-orders/{id}/`
  - **描述**: 完全或部分更新一个印染订单。
  - **请求体**: `PrintingOrderCreateUpdateSerializer`。
  - **注意**: 如果订单下已有开始的 `PrintingJob`，则无法修改 `process` 字段。

- **DELETE** `/api/v1/printing-orders/{id}/`
  - **描述**: **已禁用**。请使用 `invalidate` 接口作废订单。

### 1.2. 自定义操作 (Custom Actions)

- **POST** `/api/v1/printing-orders/{id}/invalidate/`
  - **描述**: 作废订单。需要 `printing.can_invalidate_printingorder` 权限。

- **POST** `/api/v1/printing-orders/{id}/activate/`
  - **描述**: 恢复已作废的订单。需要 `printing.can_activate_printingorder` 权限。

- **POST** `/api/v1/printing-orders/{id}/mark_fabric_received/`
  - **描述**: 标记订单的布料已收到。

---

## 2. Printing Jobs API (印染任务)

**基础路径**: `/api/v1/printing-jobs/`

管理印染订单下的具体生产任务（款式明细）。

### 2.1. 标准操作 (CRUD)

- **GET** `/api/v1/printing-jobs/`
  - **描述**: 获取印染任务列表。
  - **查询参数**:
    - `printing_order`: 印染订单ID
    - `product`: 产品ID
    - `product_name`: 产品名称 (模糊查询)
    - `unit`: 单位 (模糊查询)
    - `quantity_min`/`max`: 数量范围
    - `pieces_min`/`max`: 件数范围
    - `search`: 全文搜索 (产品名称, 单位, 尺寸, 备注)
    - `ordering`: 排序字段。
  - **响应**: `PrintingJobListSerializer` 列表。
    - **重要变更**: 列表中已**包含** `business_object_id` 字段。

- **GET** `/api/v1/printing-jobs/{id}/`
  - **描述**: 获取单个印染任务详情。
  - **响应**: `PrintingJobDetailSerializer`。
    - **重要变更**: `business_object_id` 字段现在会安全地返回 `null` 而不是报错（当 `business_object` 不存在时）。

- **POST** `/api/v1/printing-jobs/`
  - **描述**: 创建一个新的印染任务。
  - **请求体**: `PrintingJobCreateUpdateSerializer`。

- **PUT/PATCH** `/api/v1/printing-jobs/{id}/`
  - **描述**: 完全或部分更新一个印染任务。
  - **请求体**: `PrintingJobCreateUpdateSerializer`。

- **DELETE** `/api/v1/printing-jobs/{id}/`
  - **描述**: **已禁用**。

### 2.2. 状态流转操作 (便捷包装)

这些接口是对 `stateflow` 模块的包装，前端只需提供 `printing_job` 的 ID。

**重要变更 (v2)**: 现在支持传递状态参数！

- **POST** `/api/v1/printing-jobs/{id}/advance-to-next-state/`
  - **描述**: 将任务推进到下一个流程状态。
  - **请求体**: (可选，但如果下一个状态有必填参数，则必须提供)
    ```json
    {
      "parameters": {
        "temperature": "25.5",
        "operator": "张三",
        "humidity": "60%"
      }
    }
    ```
  - **参数说明**:
    - `parameters`: 可选的字典，包含状态参数的键值对
    - 如果流程节点定义了必填参数（`is_required=True`），则必须在 `parameters` 中提供
    - 参数值统一为字符串类型
  - **成功响应**: `200 OK`
    ```json
    {
      "detail": "已完成状态: 待印染",
      "data": {
        "id": 1,
        "status": "印染中",
        "business_object_id": 10,
        ...
      }
    }
    ```
  - **失败响应**: 
    - `400 Bad Request` - 缺少必填参数
      ```json
      {
        "detail": "缺失必填参数: temperature, operator"
      }
      ```
    - `400 Bad Request` - 流程已完成
      ```json
      {
        "detail": "流程已完成，无法继续推进"
      }
      ```
    - `400 Bad Request` - 没有关联的流程实例
      ```json
      {
        "detail": "该任务没有关联的流程实例"
      }
      ```

- **POST** `/api/v1/printing-jobs/{id}/step-back-one-state/`
  - **描述**: 将任务回退到上一个流程状态。
  - **响应**: 成功时返回 `200 OK`，包含 `detail` 和 `data`。失败时返回 `400 Bad Request`。

### 2.3. 状态查询操作

- **GET** `/api/v1/printing-jobs/{id}/completed-states/`
  - **描述**: 查询已完成的流程节点列表。
  - **查询参数**:
    - `include_cancelled`: 是否包含已撤销的记录 (`true`/`false`)。
  - **响应**: 包含状态日志列表。

- **GET** `/api/v1/printing-jobs/{id}/timeline/`
  - **描述**: 获取完整的流程时间线，包含所有节点及其状态 (`not_started`, `in_progress`, `completed`)。

---

## 3. Plate Orders API (开版订单)

**基础路径**: `/api/v1/plate-orders/`

管理设计、打样、开版的订单。

### 3.1. 标准操作 (CRUD)

- **GET** `/api/v1/plate-orders/`
  - **描述**: 获取开版订单列表。
  - **查询参数**:
    - `customer_name`/`phone`: 客户名称/电话 (模糊查询)
    - `salesperson`/`merchandiser`: 业务员/跟单员 ID
    - `plate_type`, `urgency_level`, `fabric`, `style_name`: 模糊查询
    - `is_invalid`, `is_ordered`, `is_mark_frame`: 布尔过滤
    - `plate_date_from`/`to`: 开版日期范围
    - `required_completion_date_from`/`to`: 要求完成时间范围（ISO8601，含具体时间）
    - `created_date_from`/`to`: 创建日期范围
    - `search`: 全文搜索 (设计编号, 款式名称, 客户名称, 面料)
    - `ordering`: 排序字段。
  - **响应**: `PlateOrderListSerializer` 列表。

- **GET** `/api/v1/plate-orders/{id}/`
  - **描述**: 获取单个开版订单详情。
  - **响应**: `PlateOrderDetailSerializer`。
    - **重要变更**: `business_object_id` 字段现在会安全地返回 `null` 而不是报错。

- **POST** `/api/v1/plate-orders/`
  - **描述**: 创建一个新的开版订单。
  - **请求体**: `PlateOrderCreateUpdateSerializer`。
  - **字段补充**: `image_name`（可空字符串）用于记录上传的开版图片名称，即使未上传文件也可单独填写。

- **PUT/PATCH** `/api/v1/plate-orders/{id}/`
  - **描述**: 完全或部分更新一个开版订单。
  - **请求体**: `PlateOrderCreateUpdateSerializer`。
  - **字段补充**: 支持更新 `image_name`，便于修正或补录图片名称。

- **DELETE** `/api/v1/plate-orders/{id}/`
  - **描述**: **已禁用**。

### 3.2. 自定义操作

- **POST** `/api/v1/plate-orders/{id}/invalidate/`
  - **描述**: 作废开版订单。需要 `printing.can_invalidate_plateorder` 权限。

- **POST** `/api/v1/plate-orders/{id}/activate/`
  - **描述**: 恢复已作废的开版订单。需要 `printing.can_activate_plateorder` 权限。

### 3.3. 状态流转与查询操作

与 `PrintingJob` 的接口类似，提供对 `stateflow` 的便捷包装。

**重要变更 (v2)**: 现在支持传递状态参数！

- **POST** `/api/v1/plate-orders/{id}/advance-to-next-state/`
  - **描述**: 推进到下一个流程状态。
  - **请求体**: (可选，但如果下一个状态有必填参数，则必须提供)
    ```json
    {
      "parameters": {
        "inspector": "李四",
        "quality_score": "95",
        "notes": "质量良好"
      }
    }
    ```
  - **参数说明**:
    - `parameters`: 可选的字典，包含状态参数的键值对
    - 如果流程节点定义了必填参数（`is_required=True`），则必须在 `parameters` 中提供
    - 参数值统一为字符串类型
  - **成功响应**: `200 OK`
    ```json
    {
      "detail": "已完成状态: 待画图",
      "data": {
        "id": 1,
        "status": "画图完成",
        "business_object_id": 20,
        ...
      }
    }
    ```
  - **失败响应**: 
    - `400 Bad Request` - 缺少必填参数
      ```json
      {
        "detail": "缺失必填参数: inspector"
      }
      ```
    - `400 Bad Request` - 流程已完成或没有关联的流程实例

- **POST** `/api/v1/plate-orders/{id}/step-back-one-state/`
  - **描述**: 回退到上一个流程状态。

- **GET** `/api/v1/plate-orders/{id}/completed-states/`
  - **描述**: 查询已完成的流程节点列表。

- **GET** `/api/v1/plate-orders/{id}/timeline/`
  - **描述**: 获取完整的流程时间线。

---

## 4. 重要变更说明 (v2)

### 4.1. 新增功能

#### 4.1.1. 状态推进接口支持参数传递

**影响接口**:
- `POST /api/v1/printing-jobs/{id}/advance-to-next-state/`
- `POST /api/v1/plate-orders/{id}/advance-to-next-state/`

**变更内容**:
- 这两个接口现在支持在请求体中传递 `parameters` 字典
- `parameters` 是可选的，但如果流程节点定义了必填参数，则必须提供
- 参数格式与 `stateflow` 模块的原始接口保持一致

**迁移指南**:
- 旧代码（无参数）:
  ```javascript
  POST /api/v1/printing-jobs/123/advance-to-next-state/
  // 空请求体
  ```
  
- 新代码（带参数）:
  ```javascript
  POST /api/v1/printing-jobs/123/advance-to-next-state/
  {
    "parameters": {
      "temperature": "25.5",
      "operator": "张三"
    }
  }
  ```

- **向后兼容**: 如果流程节点没有必填参数，可以不传 `parameters`，保持原有调用方式。

#### 4.1.2. business_object_id 字段增强

**影响接口**:
- `GET /api/v1/printing-jobs/` (列表)
- `GET /api/v1/printing-jobs/{id}/` (详情)
- `GET /api/v1/plate-orders/{id}/` (详情)

**变更内容**:
- `PrintingJobListSerializer` 现在**包含** `business_object_id` 字段（之前缺失）
- `PrintingJobDetailSerializer` 和 `PlateOrderDetailSerializer` 的 `business_object_id` 字段已修复
- 当 `business_object` 不存在时，返回 `null` 而不是报错

**迁移指南**:
- 旧代码可能需要处理字段缺失或错误
- 新代码可以安全地访问 `business_object_id`，值可能为 `null` 或整数

### 4.2. Bug 修复

1. **修复了 `business_object_id` 字段在关联对象不存在时抛出异常的问题**
   - 之前: 使用 `source='business_object.id'` 导致 `AttributeError`
   - 现在: 使用 `SerializerMethodField` 安全返回 `null`

2. **修复了状态推进接口无法传递参数的问题**
   - 之前: 参数被忽略，导致有必填参数的流程无法推进
   - 现在: 参数正确传递到底层 `stateflow` 服务

### 4.3. 测试覆盖

新增测试用例:
- `test_advance_with_parameters`: 测试带参数推进
- `test_advance_with_required_parameters_missing`: 测试缺少必填参数的错误处理
- `test_advance_with_partial_required_parameters`: 测试部分提供必填参数的错误处理

### 4.4. 对前端的影响

**必须更新的地方**:
1. 如果前端代码访问 `PrintingJob` 列表的 `business_object_id`，现在会正常返回（之前可能报错或不存在）。
2. 如果前端需要在推进状态时传递参数，现在可以在请求体中添加 `parameters` 字段。

**可选更新的地方**:
1. 建议添加错误处理逻辑，当推进失败时显示具体的缺失参数信息。
2. 建议在推进前查询节点的参数要求（通过 `stateflow` 的 `next_pending_state` 接口）。

**示例代码**:
```javascript
// 推进前查询下一个节点的参数要求
const response = await fetch(`/api/v1/stateflow/business-objects/${businessObjectId}/next_pending_state/`);
const nextState = await response.json();

if (nextState.parameters && nextState.parameters.length > 0) {
  // 显示参数输入表单
  const requiredParams = nextState.parameters.filter(p => p.is_required);
  // ... 收集用户输入
}

// 推进状态（带参数）
const advanceResponse = await fetch(`/api/v1/printing-jobs/${jobId}/advance-to-next-state/`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    parameters: collectedParameters
  })
});
```