From 107e65afc0c1fbc24a1865880f519cf62e103f2f Mon Sep 17 00:00:00 2001 From: colaftc Date: Fri, 14 Nov 2025 09:01:48 +0800 Subject: [PATCH] fix: docs --- docs/PlateOrder_API.md | 499 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 499 insertions(+) create mode 100644 docs/PlateOrder_API.md diff --git a/docs/PlateOrder_API.md b/docs/PlateOrder_API.md new file mode 100644 index 0000000..af24eed --- /dev/null +++ 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 操作 +- 添加作废/恢复功能 +- 支持多维度过滤和搜索