# PlateOrder API 文档

## 概述

开版订单（PlateOrder）管理接口，提供开版订单的完整 CRUD 操作、作废/恢复功能。

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

**认证方式**: 需要用户认证和相应权限

---

## 接口列表

### 1. 获取开版订单列表

**请求**
```
GET /api/v1/plate-orders/
```

**查询参数**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| customer | integer | 否 | 客户ID（精确匹配） |
| customer_name | string | 否 | 客户名称（模糊查询） |
| customer_phone | string | 否 | 客户电话（模糊查询） |
| salesperson | integer | 否 | 业务员ID |
| merchandiser | integer | 否 | 跟单员ID |
| plate_type | string | 否 | 版型（模糊查询） |
| urgency_level | string | 否 | 紧急程度（模糊查询） |
| is_invalid | boolean | 否 | 是否作废（true/false） |
| is_ordered | boolean | 否 | 是否已下单（true/false） |
| is_mark_frame | boolean | 否 | 是否打样架（true/false） |
| fabric | string | 否 | 面料（模糊查询） |
| style_name | string | 否 | 款式名称（模糊查询） |
| plate_date_from | date | 否 | 开版日期起始（YYYY-MM-DD） |
| plate_date_to | date | 否 | 开版日期结束（YYYY-MM-DD） |
| required_completion_date_from | date | 否 | 要求完成日期起始 |
| required_completion_date_to | date | 否 | 要求完成日期结束 |
| created_date_from | date | 否 | 创建日期起始 |
| created_date_to | date | 否 | 创建日期结束 |
| search | string | 否 | 全文搜索（搜索设计编号、款式名称、客户名称、面料） |
| ordering | string | 否 | 排序字段，前加"-"表示倒序，如：`-created_at` |
| limit | integer | 否 | 每页条数 |
| offset | integer | 否 | 偏移量 |

**可排序字段**: `id`, `created_at`, `updated_at`, `plate_date`, `required_completion_date`, `completion_date`, `urgency_level`, `is_ordered`, `is_invalid`

**响应示例**
```json
{
  "count": 100,
  "next": "http://example.com/api/v1/plate-orders/?limit=20&offset=20",
  "previous": null,
  "results": [
    {
      "id": 1,
      "design_code": "DESIGN001",
      "plate_type": "圆网",
      "plate_date": "2025-11-10T10:00:00Z",
      "urgency_level": "加急",
      "is_invalid": false,
      "customer": 5,
      "customer_name": "测试客户",
      "area": "广州",
      "salesperson": 3,
      "salesperson_name": "张三",
      "merchandiser": 4,
      "merchandiser_name": "李四",
      "style_name": "花朵印染",
      "fabric": "棉布",
      "width": "150cm",
      "required_completion_date": "2025-11-20",
      "completion_date": null,
      "is_ordered": false,
      "process": 1,
      "process_name": "开版流程",
      "status": "进行中",
      "progress_percentage": 50,
      "created_at": "2025-11-10T09:00:00Z",
      "updated_at": "2025-11-10T10:00:00Z"
    }
  ]
}
```

---

### 2. 获取开版订单详情

**请求**
```
GET /api/v1/plate-orders/{id}/
```

**路径参数**

| 参数名 | 类型 | 说明 |
|--------|------|------|
| id | integer | 开版订单ID |

**响应示例**
```json
{
  "id": 1,
  "design_code": "DESIGN001",
  "plate_type": "圆网",
  "plate_date": "2025-11-10T10:00:00Z",
  "plate_method": "手工",
  "plate_image": "/media/plate_images/design001.jpg",
  "plate_image_url": "http://example.com/media/plate_images/design001.jpg",
  "plate_notes": "注意色彩还原",
  "reprint_reason": null,
  "urgency_level": "加急",
  "is_invalid": false,
  "customer": 5,
  "customer_name": "测试客户",
  "customer_phone": "13900139000",
  "area": "广州",
  "default_address": "广州市天河区XX路XX号",
  "salesperson": 3,
  "salesperson_name": "张三",
  "merchandiser": 4,
  "merchandiser_name": "李四",
  "style_name": "花朵印染",
  "fabric": "棉布",
  "width": "150cm",
  "production_method": "批量生产",
  "is_mark_frame": true,
  "drawing_rating": "优秀",
  "color_matching_rating": "良好",
  "sample_rating": "优秀",
  "difficulty_rating": "中等",
  "sample_meter": "5米",
  "required_sample_meters": 10.00,
  "required_completion_date": "2025-11-20",
  "completion_date": null,
  "approval_result": "通过",
  "is_ordered": false,
  "customer_feedback": "满意",
  "process": 1,
  "process_name": "开版流程",
  "status": "进行中",
  "status_id": 2,
  "is_completed": false,
  "has_started": true,
  "progress_percentage": 50,
  "business_object_id": 10,
  "created_at": "2025-11-10T09:00:00Z",
  "updated_at": "2025-11-10T10:00:00Z"
}
```

---

### 3. 创建开版订单

**请求**
```
POST /api/v1/plate-orders/
Content-Type: application/json
```

**请求体**
```json
{
  "customer": 5,
  "design_code": "DESIGN002",
  "plate_type": "平网",
  "style_name": "条纹印染",
  "fabric": "涤纶",
  "width": "160cm",
  "urgency_level": "正常",
  "salesperson": 3,
  "merchandiser": 4,
  "required_completion_date": "2025-11-25",
  "is_mark_frame": false,
  "plate_method": "机器",
  "production_method": "小批量",
  "process": 1
}
```

**必填字段**
- `customer`: 客户ID

**可选字段**
- `design_code`: 设计编号
- `plate_type`: 版型
- `plate_date`: 开版日期
- `plate_method`: 开版方式
- `plate_image`: 开版图片（文件上传）
- `plate_notes`: 打版注意事项
- `reprint_reason`: 复版原因
- `urgency_level`: 紧急程度
- `area`: 区域
- `default_address`: 默认地址
- `salesperson`: 业务员ID
- `merchandiser`: 跟单员ID
- `style_name`: 款式名称
- `fabric`: 面料
- `width`: 幅宽
- `production_method`: 做货方式
- `is_mark_frame`: 是否套唛架
- `drawing_rating`: 画图评级
- `color_matching_rating`: 调色评级
- `sample_rating`: 套样评级
- `difficulty_rating`: 难度评级
- `sample_meter`: 米样
- `required_sample_meters`: 所需样品米数
- `required_completion_date`: 要求完成时间
- `completion_date`: 完成时间
- `approval_result`: 审批结果
- `is_ordered`: 是否已下单
- `customer_feedback`: 客户反馈
- `process`: 流程ID（如果不传递则使用默认流程）

**响应**
- 状态码: `201 Created`
- 响应体: 创建的开版订单详情（同详情接口）

**错误响应**
```json
{
  "customer": ["客户不能为空"]
}
```

---

### 4. 更新开版订单（完整更新）

**请求**
```
PUT /api/v1/plate-orders/{id}/
Content-Type: application/json
```

**请求体**: 同创建接口，需提供所有字段

**响应**
- 状态码: `200 OK`
- 响应体: 更新后的开版订单详情

---

### 5. 更新开版订单（部分更新）

**请求**
```
PATCH /api/v1/plate-orders/{id}/
Content-Type: application/json
```

**请求体示例**
```json
{
  "urgency_level": "特急",
  "is_mark_frame": true,
  "completion_date": "2025-11-15"
}
```

**说明**: 只需提供要更新的字段

**响应**
- 状态码: `200 OK`
- 响应体: 更新后的开版订单详情

---

### 6. 删除开版订单（不支持）

**请求**
```
DELETE /api/v1/plate-orders/{id}/
```

**响应**
```json
{
  "detail": "开版订单不支持删除操作，请使用作废功能"
}
```
- 状态码: `405 Method Not Allowed`

**说明**: 开版订单不支持物理删除，请使用作废功能进行软删除。

---

### 7. 作废开版订单

**请求**
```
POST /api/v1/plate-orders/{id}/invalidate/
```

**权限要求**: `printing.can_invalidate_plateorder`

**响应示例**
```json
{
  "detail": "开版订单已作废",
  "data": {
    "id": 1,
    "is_invalid": true,
    // ... 其他字段
  }
}
```

**错误响应**

1. 无权限
```json
{
  "detail": "您没有权限作废开版订单"
}
```
- 状态码: `403 Forbidden`

2. 订单已作废
```json
{
  "detail": "该开版订单已经作废"
}
```
- 状态码: `400 Bad Request`

---

### 8. 恢复开版订单

**请求**
```
POST /api/v1/plate-orders/{id}/activate/
```

**权限要求**: `printing.can_activate_plateorder`

**响应示例**
```json
{
  "detail": "开版订单已恢复",
  "data": {
    "id": 1,
    "is_invalid": false,
    // ... 其他字段
  }
}
```

**错误响应**

1. 无权限
```json
{
  "detail": "您没有权限恢复开版订单"
}
```
- 状态码: `403 Forbidden`

2. 订单未作废
```json
{
  "detail": "该开版订单未作废，无需恢复"
}
```
- 状态码: `400 Bad Request`

---

### 9. 推进到下一个状态

**请求**
```
POST /api/v1/plate-orders/{id}/advance-to-next-state/
```

**权限要求**: 需要登录和相应权限

**响应示例**
```json
{
  "detail": "已推进到下一个状态",
  "data": {
    "id": 1,
    "status": "调色",
    "status_id": 2,
    "progress_percentage": 33,
    // ... 其他字段
  }
}
```

**错误响应**

1. 没有流程实例
```json
{
  "detail": "该开版订单没有关联的流程实例"
}
```
- 状态码: `400 Bad Request`

2. 流程已完成或其他错误
```json
{
  "detail": "流程已完成，无法继续推进"
}
```
- 状态码: `400 Bad Request`

---

### 10. 回退一步

**请求**
```
POST /api/v1/plate-orders/{id}/step-back-one-state/
```

**权限要求**: 需要登录和相应权限

**响应示例**
```json
{
  "detail": "已回退到上一个状态",
  "data": {
    "id": 1,
    "status": "画图",
    "status_id": 1,
    "progress_percentage": 0,
    // ... 其他字段
  }
}
```

**错误响应**

1. 没有流程实例
```json
{
  "detail": "该开版订单没有关联的流程实例"
}
```
- 状态码: `400 Bad Request`

2. 没有可回退的状态
```json
{
  "detail": "没有可回退的状态"
}
```
- 状态码: `400 Bad Request`

---

### 11. 查询已完成的流程列表

**请求**
```
GET /api/v1/plate-orders/{id}/completed-states/
```

**查询参数**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| include_cancelled | boolean | 否 | 是否包含已撤销的流程（true/false），默认 false |

**响应示例**
```json
{
  "count": 2,
  "results": [
    {
      "id": 1,
      "state_id": 1,
      "state_name": "画图",
      "completed_at": "2025-11-11T10:00:00Z",
      "completed_by": "user123",
      "completed_by_name": "张三",
      "is_cancelled": false,
      "cancelled_at": null
    },
    {
      "id": 2,
      "state_id": 2,
      "state_name": "调色",
      "completed_at": "2025-11-12T15:30:00Z",
      "completed_by": "user456",
      "completed_by_name": "李四",
      "is_cancelled": false,
      "cancelled_at": null
    }
  ]
}
```

---

### 12. 获取流程时间线

**请求**
```
GET /api/v1/plate-orders/{id}/timeline/
```

**说明**: 返回完整的流程时间线，包括未开始、进行中和已完成的状态，不包含已撤销的记录

**响应示例**
```json
{
  "count": 3,
  "results": [
    {
      "state_id": 1,
      "state_name": "画图",
      "state_description": "设计图纸绘制",
      "order": 0,
      "status": "completed",
      "completed_at": "2025-11-11T10:00:00Z",
      "completed_by": "user123",
      "completed_by_name": "张三"
    },
    {
      "state_id": 2,
      "state_name": "调色",
      "state_description": "颜色调配",
      "order": 1,
      "status": "in_progress",
      "completed_at": null,
      "completed_by": null,
      "completed_by_name": null
    },
    {
      "state_id": 3,
      "state_name": "套样",
      "state_description": "样品套制",
      "order": 2,
      "status": "not_started",
      "completed_at": null,
      "completed_by": null,
      "completed_by_name": null
    }
  ]
}
```

**状态说明**
- `not_started`: 未开始
- `in_progress`: 进行中
- `completed`: 已完成

---

## 数据模型

### PlateOrder（开版订单）

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | integer | 主键ID |
| design_code | string | 设计编号 |
| plate_type | string | 版型（首版/复版等） |
| plate_date | datetime | 开版时间 |
| plate_method | string | 开版方式 |
| plate_image | file | 开版图片 |
| plate_notes | text | 打版注意事项 |
| reprint_reason | text | 复版原因 |
| urgency_level | string | 紧急程度 |
| is_invalid | boolean | 是否作废 |
| customer | FK | 客户（外键） |
| area | string | 区域 |
| default_address | string | 默认地址 |
| salesperson | FK | 业务员（外键） |
| merchandiser | FK | 跟单员（外键） |
| process | integer | 流程ID（无外键约束） |
| style_name | string | 款式名称 |
| fabric | string | 面料 |
| width | string | 幅宽 |
| production_method | string | 做货方式 |
| is_mark_frame | boolean | 是否套唛架 |
| drawing_rating | string | 画图评级 |
| color_matching_rating | string | 调色评级 |
| sample_rating | string | 套样评级 |
| difficulty_rating | string | 难度评级 |
| sample_meter | string | 米样 |
| required_sample_meters | decimal | 所需样品米数 |
| required_completion_date | date | 要求完成时间 |
| completion_date | datetime | 完成时间 |
| approval_result | string | 审批结果 |
| is_ordered | boolean | 是否已下单 |
| customer_feedback | text | 客户反馈 |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

---

## 权限说明

### 基础权限（DjangoModelPermissions）

- `printing.view_plateorder` - 查看开版订单
- `printing.add_plateorder` - 添加开版订单
- `printing.change_plateorder` - 修改开版订单
- `printing.delete_plateorder` - 删除权限（但实际不允许删除）

### 自定义权限

- `printing.can_invalidate_plateorder` - 作废开版订单
- `printing.can_activate_plateorder` - 恢复开版订单

---

## 使用示例

### 示例1: 搜索特定客户的加急订单

```bash
curl -X GET "http://api.example.com/api/v1/plate-orders/?customer_name=测试&urgency_level=加急" \
  -H "Authorization: Token your-auth-token"
```

### 示例2: 创建开版订单

```bash
curl -X POST "http://api.example.com/api/v1/plate-orders/" \
  -H "Authorization: Token your-auth-token" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": 5,
    "design_code": "DESIGN003",
    "plate_type": "圆网",
    "style_name": "新款印染",
    "fabric": "纯棉",
    "urgency_level": "加急",
    "required_completion_date": "2025-11-20",
    "process": 1
  }'
```

### 示例3: 作废订单

```bash
curl -X POST "http://api.example.com/api/v1/plate-orders/1/invalidate/" \
  -H "Authorization: Token your-auth-token"
```

### 示例4: 按日期范围查询

```bash
curl -X GET "http://api.example.com/api/v1/plate-orders/?plate_date_from=2025-11-01&plate_date_to=2025-11-30&ordering=-plate_date" \
  -H "Authorization: Token your-auth-token"
```

### 示例5: 推进流程状态

```bash
curl -X POST "http://api.example.com/api/v1/plate-orders/1/advance-to-next-state/" \
  -H "Authorization: Token your-auth-token"
```

### 示例6: 回退流程状态

```bash
curl -X POST "http://api.example.com/api/v1/plate-orders/1/step-back-one-state/" \
  -H "Authorization: Token your-auth-token"
```

### 示例7: 获取流程时间线

```bash
curl -X GET "http://api.example.com/api/v1/plate-orders/1/timeline/" \
  -H "Authorization: Token your-auth-token"
```

---

## 错误代码

| 状态码 | 说明 |
|--------|------|
| 200 | 请求成功 |
| 201 | 创建成功 |
| 400 | 请求参数错误 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 405 | 方法不允许 |
| 500 | 服务器内部错误 |

---

## 注意事项

1. **软删除机制**: 开版订单不支持物理删除，使用 `is_invalid` 字段进行软删除
2. **权限控制**: 作废和恢复操作需要特定权限
3. **日期格式**: 所有日期字段使用 ISO 8601 格式（YYYY-MM-DD 或 YYYY-MM-DDTHH:MM:SSZ）
4. **分页**: 列表接口默认支持分页，使用 `limit` 和 `offset` 参数控制
5. **文件上传**: `plate_image` 字段需要使用 multipart/form-data 格式上传
6. **自动创建流程实例**: 创建开版订单时，如果提供了 `process` 字段，系统会自动创建对应的 BusinessObject 流程实例。如果不提供则使用默认流程
7. **流程验证**: 提供的 `process` ID 必须在系统中存在，否则会返回验证错误
8. **流程操作**: 
   - 推进/回退操作需要订单已关联 BusinessObject
   - timeline 接口不包含已撤销的流程记录
   - completed-states 接口默认不包含已撤销记录，可通过 `include_cancelled=true` 参数包含

---

## 更新日志

### v1.2.0 (2025-11-14)
- 添加流程控制接口：
  - `advance-to-next-state`: 推进到下一个状态
  - `step-back-one-state`: 回退一步
  - `completed-states`: 查询已完成的流程列表
  - `timeline`: 获取流程时间线

### v1.1.0 (2025-11-14)
- 添加 `process` 字段：支持指定流程ID
- 添加 `process_name` 只读字段：自动返回流程名称
- 自动创建 BusinessObject：创建订单时根据 process 自动创建流程实例
- 流程验证：确保提供的流程ID有效

### v1.0.0 (2025-11-13)
- 初始版本
- 支持完整的 CRUD 操作
- 添加作废/恢复功能
- 支持多维度过滤和搜索