fix: docs

2025-11-14 09:01:48 +08:00
parent f071e5fff9
commit 107e65afc0
1 changed files with 499 additions and 0 deletions
--- a/docs/PlateOrder_API.md
+++ b/docs/PlateOrder_API.md
@@ -0,0 +1,499 @@
+# 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,
+      "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": "满意",
+  "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": "小批量"
+}
+```
+
+**必填字段**
+- `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`: 客户反馈
+
+**响应**
+- 状态码: `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`
+
+---
+
+## 数据模型
+
+### 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 | 跟单员（外键） |
+| 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"
+  }'
+```
+
+### 示例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"
+```
+
+---
+
+## 错误代码
+
+| 状态码 | 说明 |
+|--------|------|
+| 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 格式上传
+
+---
+
+## 更新日志
+
+### v1.0.0 (2025-11-13)
+- 初始版本
+- 支持完整的 CRUD 操作
+- 添加作废/恢复功能
+- 支持多维度过滤和搜索