Files

colaftc 0c62398120 feat: added print_count api, added merchant setting model, added manual mode setting for purchase order

2025-11-28 15:01:11 +08:00

18 KiB

Raw Blame History

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
designer	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	datetime	否	要求完成时间起始（ISO8601，例：2025-11-20T08:00:00Z）
required_completion_date_to	datetime	否	要求完成时间结束（ISO8601）
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

响应示例

{
  "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": "李四",
      "designer": 8,
      "designer_name": "王五",
      "style_name": "花朵印染",
      "fabric": "棉布",
      "width": "150cm",
      "required_completion_date": "2025-11-20T18:00:00Z",
      "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

响应示例

{
  "id": 1,
  "design_code": "DESIGN001",
  "plate_type": "圆网",
  "plate_date": "2025-11-10T10:00:00Z",
  "plate_method": "手工",
  "plate_image": [
    {
      "file_id": 12,
      "name": "主图",
      "url": "https://example.com/media/uploads/2025/11/plate-a.jpg",
      "path": "uploads/2025/11/plate-a.jpg"
    },
    {
      "file_id": 13,
      "name": "细节图",
      "url": "https://example.com/media/uploads/2025/11/plate-b.jpg",
      "path": "uploads/2025/11/plate-b.jpg"
    }
  ],
  "plate_image_url": [
    "https://example.com/media/uploads/2025/11/plate-a.jpg",
    "https://example.com/media/uploads/2025/11/plate-b.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": "李四",
  "designer": 8,
  "designer_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-20T18:00:00Z",
  "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

请求体

{
  "customer": 5,
  "design_code": "DESIGN002",
  "plate_type": "平网",
  "style_name": "条纹印染",
  "fabric": "涤纶",
  "width": "160cm",
  "urgency_level": "正常",
  "salesperson": 3,
  "merchandiser": 4,
  "designer": 8,
  "plate_image": [
    {"file_id": 21, "name": "主图"},
    {"file_id": 22, "name": "细节图"}
  ],
  "required_completion_date": "2025-11-25T06:30:00Z",
  "is_mark_frame": false,
  "plate_method": "机器",
  "production_method": "小批量",
  "process": 1
}

必填字段

customer: 客户ID

可选字段

design_code: 设计编号
plate_type: 版型
plate_date: 开版日期
plate_method: 开版方式
plate_image: 开版图片引用列表（数组，元素包含 file_id 与可选 name，需要先通过 /api/v1/upload/ 上传文件）
plate_notes: 打版注意事项
reprint_reason: 复版原因
urgency_level: 紧急程度
area: 区域
default_address: 默认地址
salesperson: 业务员ID
merchandiser: 跟单员ID
designer: 设计师ID
style_name: 款式名称
fabric: 面料
fabric_source: 布料来源（可空字符串，如“客户提供”）
width: 幅宽
production_method: 做货方式
is_mark_frame: 是否套唛架
drawing_rating: 画图评级
color_matching_rating: 调色评级
sample_rating: 套样评级
difficulty_rating: 难度评级
sample_meter: 米样
required_sample_meters: 所需样品米数
required_completion_date: 要求完成时间（日期+具体时间，UTC 推荐）
completion_date: 完成时间
approval_result: 审批结果
is_ordered: 是否已下单
customer_feedback: 客户反馈
process: 流程ID（如果不传递则使用默认流程）

响应

状态码: 201 Created
响应体: 创建的开版订单详情（同详情接口）。若 design_code 为空，返回值会自动使用 6 位补零的主键（如 000123）。

错误响应

{
  "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

请求体示例

{
  "urgency_level": "特急",
  "is_mark_frame": true,
  "completion_date": "2025-11-15"
}

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

响应

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

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

请求

DELETE /api/v1/plate-orders/{id}/

响应

{
  "detail": "开版订单不支持删除操作，请使用作废功能"
}

状态码: 405 Method Not Allowed

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

7. 作废开版订单

请求

POST /api/v1/plate-orders/{id}/invalidate/

权限要求: printing.can_invalidate_plateorder

响应示例

{
  "detail": "开版订单已作废",
  "data": {
    "id": 1,
    "is_invalid": true,
    // ... 其他字段
  }
}

错误响应

无权限

{
  "detail": "您没有权限作废开版订单"
}

状态码: 403 Forbidden

订单已作废

{
  "detail": "该开版订单已经作废"
}

状态码: 400 Bad Request

8. 恢复开版订单

请求

POST /api/v1/plate-orders/{id}/activate/

权限要求: printing.can_activate_plateorder

响应示例

{
  "detail": "开版订单已恢复",
  "data": {
    "id": 1,
    "is_invalid": false,
    // ... 其他字段
  }
}

错误响应

无权限

{
  "detail": "您没有权限恢复开版订单"
}

状态码: 403 Forbidden

订单未作废

{
  "detail": "该开版订单未作废，无需恢复"
}

状态码: 400 Bad Request

9. 推进到下一个状态

请求

POST /api/v1/plate-orders/{id}/advance-to-next-state/

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

响应示例

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

错误响应

没有流程实例

{
  "detail": "该开版订单没有关联的流程实例"
}

状态码: 400 Bad Request

流程已完成或其他错误

{
  "detail": "流程已完成，无法继续推进"
}

状态码: 400 Bad Request

10. 回退一步

请求

POST /api/v1/plate-orders/{id}/step-back-one-state/

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

响应示例

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

错误响应

没有流程实例

{
  "detail": "该开版订单没有关联的流程实例"
}

状态码: 400 Bad Request

没有可回退的状态

{
  "detail": "没有可回退的状态"
}

状态码: 400 Bad Request

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

请求

GET /api/v1/plate-orders/{id}/completed-states/

查询参数

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

响应示例

{
  "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/

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

响应示例

{
  "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	array	开版图片引用列表（通过 `UploadedFile` ID 关联）
plate_notes	text	打版注意事项
reprint_reason	text	复版原因
urgency_level	string	紧急程度
is_invalid	boolean	是否作废
customer	FK	客户（外键）
area	string	区域
default_address	string	默认地址
salesperson	FK	业务员（外键）
merchandiser	FK	跟单员（外键）
designer	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	datetime	要求完成时间（ISO8601 字符串）
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: 搜索特定客户的加急订单

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

示例2: 创建开版订单

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-20T18:00:00Z",
    "process": 1
  }'

示例3: 作废订单

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

示例4: 按日期范围查询

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: 推进流程状态

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

示例6: 回退流程状态

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

示例7: 获取流程时间线

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	服务器内部错误

注意事项

软删除机制: 开版订单不支持物理删除，使用 is_invalid 字段进行软删除
权限控制: 作废和恢复操作需要特定权限
日期格式: 所有日期字段使用 ISO 8601 格式（YYYY-MM-DD 或 YYYY-MM-DDTHH:MM:SSZ）
分页: 列表接口默认支持分页，使用 limit 和 offset 参数控制
文件引用: 需先调用 /api/v1/upload/ 上传文件并获取 file_id，再通过 plate_image 数组提交引用（无需 multipart）
自动创建流程实例: 创建开版订单时，如果提供了 process 字段，系统会自动创建对应的 BusinessObject 流程实例。如果不提供则使用默认流程
流程验证: 提供的 process ID 必须在系统中存在，否则会返回验证错误
流程操作:
- 推进/回退操作需要订单已关联 BusinessObject
- timeline 接口不包含已撤销的流程记录
- completed-states 接口默认不包含已撤销记录，可通过 include_cancelled=true 参数包含
设计编号回退: 所有响应中若 design_code 为空，会自动使用主键生成 6 位补零字符串（如 000123），确保前端始终有值可显示
布料来源: fabric_source 为可选字段，建议用于区分客户提供、仓库调拨等不同来源信息

更新日志

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 操作
添加作废/恢复功能
支持多维度过滤和搜索

18 KiB Raw Blame History Unescape Escape

PlateOrder API 文档

概述

接口列表

1. 获取开版订单列表

2. 获取开版订单详情

3. 创建开版订单

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

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

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

7. 作废开版订单

8. 恢复开版订单

9. 推进到下一个状态

10. 回退一步

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

12. 获取流程时间线

数据模型

PlateOrder（开版订单）

权限说明

基础权限（DjangoModelPermissions）

自定义权限

使用示例

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

示例2: 创建开版订单

示例3: 作废订单

示例4: 按日期范围查询

示例5: 推进流程状态

示例6: 回退流程状态

示例7: 获取流程时间线

错误代码

注意事项

更新日志

v1.2.0 (2025-11-14)

v1.1.0 (2025-11-14)

v1.0.0 (2025-11-13)

18 KiB

Raw Blame History