erpnew/stateflow/PRINTING_API_CLEANUP_2025-11-15.md

Printing 模块 API 清理记录

日期: 2025年11月15日
目的: 删除 printing 模块中冗余的状态流转接口，统一使用 stateflow 的业务对象接口

---

删除的接口

1. PrintingJobViewSet (印染任务)

删除的方法：

1.1 advance_to_next_state() 方法

• 路径: POST /api/v1/printing-jobs/{id}/advance-to-next-state/
• 原位置: api_v1/views/printing/views.py 约第 309-342 行
• 删除原因:
  • 功能与 stateflow 统一接口重复
  • 不支持参数传递
  • 调用签名过时（只接收2个返回值，实际返回3个）

1.2 step_back_one_state() 方法

• 路径: POST /api/v1/printing-jobs/{id}/step-back-one-state/
• 原位置: api_v1/views/printing/views.py 约第 345-380 行
• 删除原因: 与 stateflow 统一接口重复

---

2. PlateOrderViewSet (开版订单)

删除的方法：

2.1 advance_to_next_state() 方法

• 路径: POST /api/v1/plate-orders/{id}/advance-to-next-state/
• 原位置: api_v1/views/printing/views.py 约第 656-690 行
• 删除原因:
  • 功能与 stateflow 统一接口重复
  • 不支持参数传递
  • 调用签名过时（只接收2个返回值，实际返回3个）

2.2 step_back_one_state() 方法

• 路径: POST /api/v1/plate-orders/{id}/step-back-one-state/
• 原位置: api_v1/views/printing/views.py 约第 693-728 行
• 删除原因: 与 stateflow 统一接口重复

---

保留的接口

PrintingJobViewSet 保留：

• ✅ GET /api/v1/printing-jobs/{id}/completed-states/ - 查询已完成的流程列表（便捷方法）

PlateOrderViewSet 保留：

• ✅ GET /api/v1/plate-orders/{id}/completed-states/ - 查询已完成的流程列表（便捷方法）

---

迁移指南

旧接口 → 新接口映射

推进到下一状态

旧方式（已废弃）:

POST /api/v1/printing-jobs/123/advance-to-next-state/
# 或
POST /api/v1/plate-orders/456/advance-to-next-state/

新方式（推荐）:

# 1. 先获取 business_object_id
GET /api/v1/printing-jobs/123/
# 或
GET /api/v1/plate-orders/456/

# 响应中包含 business_object_id 或 business_object.id

# 2. 调用 stateflow 统一接口（支持参数传递）
POST /api/v1/stateflow/business-objects/{business_object_id}/advance/
{
  "parameters": {
    "temperature": "25.5",
    "humidity": "60%",
    "operator": "张三"
  }
}

回退一步

旧方式（已废弃）:

POST /api/v1/printing-jobs/123/step-back-one-state/
# 或
POST /api/v1/plate-orders/456/step-back-one-state/

新方式（推荐）:

POST /api/v1/stateflow/business-objects/{business_object_id}/step_back/

---

新接口的优势

1. 支持参数管理

• ✅ 推进时可传递参数
• ✅ 自动校验必填参数
• ✅ 支持参数历史记录
• ✅ 支持补充参数

2. 统一的接口设计

• ✅ 所有业务对象使用相同接口
• ✅ 统一的错误处理
• ✅ 统一的响应格式

3. 更强大的功能

• ✅ 查询下一个待执行节点及参数要求
• ✅ 查询状态时间线
• ✅ 查询参数历史
• ✅ 重置进度

---

完整的 stateflow 接口列表

状态流转控制

• POST /api/v1/stateflow/business-objects/{id}/advance/ - 推进（支持参数）
• POST /api/v1/stateflow/business-objects/{id}/step_back/ - 回退
• POST /api/v1/stateflow/business-objects/{id}/reset/ - 重置进度

状态查询

• GET /api/v1/stateflow/business-objects/{id}/timeline/ - 状态时间线
• GET /api/v1/stateflow/business-objects/{id}/next_pending_state/ - 下一个待执行节点
• GET /api/v1/stateflow/business-objects/{id}/pending_states/ - 所有待执行节点
• GET /api/v1/stateflow/business-objects/{id}/current_state_parameters/ - 当前状态参数

参数管理

• POST /api/v1/stateflow/business-objects/{id}/state-logs/{log_id}/add-parameters/ - 补充参数
• GET /api/v1/stateflow/business-objects/{id}/state-logs/{log_id}/parameters/ - 查询参数

详见: stateflow/BusinessObject_API.md

---

模型层修改

无需修改

• ✅ PlateOrder.business_object 字段保留
• ✅ PrintingJob.business_object 字段保留
• ✅ PlateOrder.status 属性保留（便捷访问器）
• ✅ PrintingJob.status 属性保留（便捷访问器）
• ✅ PlateOrder.is_completed 属性保留
• ✅ PrintingJob.is_completed 属性保留
• ✅ PlateOrder.has_started 属性保留
• ✅ PrintingJob.has_started 属性保留

这些模型方法和属性设计正确，无需调整。

---

识别的问题（已修复）

问题 1: 调用签名不匹配 ❌

位置:

• api_v1/views/printing/views.py 第 325、672 行
• api_v1/views/printing/views.py 第 360、708 行

问题代码:

# ❌ 错误：只接收 2 个返回值
success, message = stateflow_services.advance_to_next_state(
    job.business_object, request.user
)

实际签名:

# ✅ 正确：返回 3 个值
def advance_to_next_state(...) -> Tuple[bool, str, Optional['models.StateFlowRecord']]:
    return success, message, state_log

解决方案: 删除这些接口，使用 stateflow 统一接口 ✅

问题 2: 缺少参数支持 ❌

• printing 模块的接口不接受 parameters
• 无法传递状态参数
• 不支持必填参数校验

解决方案: 使用 stateflow 统一接口（完整支持参数管理）✅

---

测试状态

• ❌ printing 模块测试失败（与本次修改无关）

  • 原因: PlateOrder 模型缺少 plate_code 字段
  • 建议: 修复 PlateOrder 模型定义或测试用例

• ✅ stateflow 模块测试全部通过（55个测试）

---

后续建议

1. 更新前端代码

• 将所有调用 printing-jobs/advance 的代码改为调用 stateflow API
• 将所有调用 plate-orders/advance 的代码改为调用 stateflow API

2. 文档更新

• ✅ 已创建 stateflow/BusinessObject_API.md
• 建议: 在 printing 模块文档中添加迁移说明

3. 修复 printing 测试

• PlateOrder 模型缺少 plate_code 字段定义
• 或者测试用例使用了错误的字段名

4. 考虑添加废弃警告（可选）

如果需要渐进式迁移，可以暂时保留旧接口但返回废弃警告：

@action(detail=True, methods=['post'])
def advance_to_next_state(self, request, pk=None):
    return Response({
        'error': 'This endpoint is deprecated. Please use /api/v1/stateflow/business-objects/{id}/advance/'
    }, status=status.HTTP_410_GONE)

---

影响范围

代码变更

• ✅ 删除 4 个 API 方法
• ✅ 文件行数减少约 138 行
• ✅ 无破坏性变更（只要前端同步更新）

API 变更

• ❌ 破坏性变更: 删除了 4 个 API 端点
• ✅ 替代方案: stateflow 统一接口功能更强

数据库变更

• ✅ 无需数据库迁移
• ✅ 无数据丢失风险

---

变更完成时间: 2025-11-15
执行人: AI Assistant
审核状态: 待人工审核