feat: big

2026-07-01 11:51:13 +08:00
parent 7c9b77afb0
commit 5170700234
28 changed files with 933 additions and 37 deletions
--- a/docs/api_v1_plate_order_detail_2026-06-30.md
+++ b/docs/api_v1_plate_order_detail_2026-06-30.md
@@ -0,0 +1,170 @@
+# API v1 Plate Order Detail 字段文档
+
+日期：2026-06-30
+
+## 接口
+
+`GET /api/v1/plate-orders/{id}/`
+
+获取单个开版订单详情。
+
+## 权限与隔离
+
+- 需要登录。
+- 使用 Django model permission：需要具备查看 `PlateOrder` 的权限。
+- 非 superuser 默认受 merchant 隔离限制，只能访问当前用户员工所属 merchant 下的数据。
+- 默认还受客户可见性限制；拥有 `printing.view_all_plateorders` 权限可突破客户可见性限制。
+- 订单不存在或无权限访问时返回 `404`。
+
+## 响应字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `id` | integer | 开版订单 ID |
+| `original_id` | integer \| null | 克隆来源订单 ID |
+| `merchant_id` | integer \| null | 所属商户 ID |
+| `design_code` | string \| null | 设计编号 |
+| `plate_type` | string \| null | 起版情况，例如首版、复版 |
+| `plate_date` | datetime \| null | 下版时间 |
+| `plate_method` | string \| null | 开版方式 |
+| `plate_image` | array | 开版图原始数据列表 |
+| `plate_image_url` | string[] | 开版图 URL 列表，从 `plate_image` 中提取并转换为可访问 URL |
+| `image_name` | string \| null | 图片名称 |
+| `plate_notes` | string \| null | 打版注意事项 |
+| `reprint_reason` | string \| null | 复版原因 |
+| `urgency_level` | string | 紧急程度 |
+| `is_invalid` | boolean | 是否作废 |
+| `customer` | integer | 客户 ID |
+| `customer_name` | string | 客户名称 |
+| `customer_phone` | string \| null | 客户手机号 |
+| `area` | string \| null | 区域 |
+| `default_address` | string \| null | 默认地址 |
+| `salesperson` | integer \| null | 销售员员工 ID |
+| `salesperson_name` | string \| null | 销售员姓名 |
+| `merchandiser` | integer \| null | 跟单员员工 ID |
+| `merchandiser_name` | string \| null | 跟单员姓名 |
+| `designer` | integer \| null | 设计师员工 ID |
+| `designer_name` | string \| null | 设计师姓名 |
+| `style_name` | string \| null | 款号名称 |
+| `fabric` | string \| null | 布料 |
+| `fabric_source` | string \| null | 布料来源 |
+| `width` | string \| null | 幅宽 |
+| `production_method` | string \| null | 做货方式 |
+| `is_mark_frame` | boolean | 是否套唛架 |
+| `drawing_rating` | string \| null | 画图评级 |
+| `color_matching_rating` | string \| null | 调色评级 |
+| `sample_rating` | string \| null | 套样评级 |
+| `difficulty_rating` | string \| null | 难度评级 |
+| `sample_meter` | string \| null | 米样 |
+| `required_sample_meters` | decimal string \| null | 客户要求米样米数 |
+| `required_completion_date` | datetime \| null | 要求完成时间 |
+| `completion_date` | datetime \| null | 完成时间 |
+| `approval_result` | string \| null | 审批结果 |
+| `is_ordered` | boolean | 是否已下单 |
+| `customer_feedback` | string \| null | 客户修改意见 |
+| `print_count` | integer | 打印次数 |
+| `process` | integer | 关联流程 ID |
+| `process_name` | string \| null | 流程名称 |
+| `status` | string | 当前流程状态名称；无当前节点时通常表示已完成 |
+| `status_id` | integer \| null | 当前待执行状态 ID |
+| `is_completed` | boolean | 流程是否完成 |
+| `has_started` | boolean | 是否已有未撤销的流程记录 |
+| `progress_percentage` | integer | 流程进度百分比 |
+| `business_object_id` | integer \| null | 关联流程实例 ID |
+| `last_completed_state` | string | 最后一个已完成节点名称；没有时为空字符串 |
+| `created_by` | integer \| null | 创建人用户 ID |
+| `created_at` | datetime | 创建时间 |
+| `updated_at` | datetime | 更新时间 |
+
+## `plate_image` 数据形态
+
+`plate_image` 是 JSON 数组，常见元素结构如下：
+
+```json
+{
+  "file_id": 123,
+  "name": "图片名称",
+  "path": "uploads/example.jpg",
+  "url": "https://example.com/media/uploads/example.jpg",
+  "size": 102400,
+  "content_type": "image/jpeg",
+  "uploaded_at": "2026-06-30T10:00:00+08:00"
+}
+```
+
+兼容历史数据时，元素也可能只有 `url` 或 `path`。前端展示图片优先使用 `plate_image_url`。
+
+## 响应示例
+
+```json
+{
+  "id": 18839,
+  "original_id": null,
+  "merchant_id": 1,
+  "design_code": "18839",
+  "plate_type": "首版",
+  "plate_date": "2026-06-30T10:00:00+08:00",
+  "plate_method": "普通开版",
+  "plate_image": [
+    {
+      "file_id": 123,
+      "name": "开版图",
+      "path": "uploads/plate/example.jpg",
+      "url": "https://example.com/media/uploads/plate/example.jpg",
+      "size": 102400,
+      "content_type": "image/jpeg",
+      "uploaded_at": "2026-06-30T09:58:00+08:00"
+    }
+  ],
+  "plate_image_url": [
+    "https://example.com/media/uploads/plate/example.jpg"
+  ],
+  "image_name": "开版图",
+  "plate_notes": "注意事项",
+  "reprint_reason": null,
+  "urgency_level": "正常",
+  "is_invalid": false,
+  "customer": 1001,
+  "customer_name": "示例客户",
+  "customer_phone": "13800000000",
+  "area": "广州",
+  "default_address": "广州市示例地址",
+  "salesperson": 11,
+  "salesperson_name": "销售员A",
+  "merchandiser": 12,
+  "merchandiser_name": "跟单员B",
+  "designer": 13,
+  "designer_name": "设计师C",
+  "style_name": "款号001",
+  "fabric": "棉布",
+  "fabric_source": "客户来布",
+  "width": "150cm",
+  "production_method": "印花",
+  "is_mark_frame": false,
+  "drawing_rating": null,
+  "color_matching_rating": null,
+  "sample_rating": null,
+  "difficulty_rating": null,
+  "sample_meter": "米样说明",
+  "required_sample_meters": "5.00",
+  "required_completion_date": "2026-07-01T18:00:00+08:00",
+  "completion_date": null,
+  "approval_result": null,
+  "is_ordered": false,
+  "customer_feedback": null,
+  "print_count": 0,
+  "process": 1,
+  "process_name": "开版流程",
+  "status": "画图",
+  "status_id": 2,
+  "is_completed": false,
+  "has_started": true,
+  "progress_percentage": 25,
+  "business_object_id": 5001,
+  "last_completed_state": "接单",
+  "created_by": 7,
+  "created_at": "2026-06-30T09:50:00+08:00",
+  "updated_at": "2026-06-30T10:10:00+08:00"
+}
+```
+