feat: stateflow v2 (params required)

stateflow/PRINTING_API_CLEANUP_2025-11-15.md

@@ -0,0 +1,254 @@
+# 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/` - 查询已完成的流程列表（便捷方法）
+
+---
+
+## 迁移指南
+
+### 旧接口 → 新接口映射
+
+#### 推进到下一状态
+
+**旧方式（已废弃）**:
+```bash
+POST /api/v1/printing-jobs/123/advance-to-next-state/
+# 或
+POST /api/v1/plate-orders/456/advance-to-next-state/
+```
+
+**新方式（推荐）**:
+```bash
+# 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": "张三"
+  }
+}
+```
+
+#### 回退一步
+
+**旧方式（已废弃）**:
+```bash
+POST /api/v1/printing-jobs/123/step-back-one-state/
+# 或
+POST /api/v1/plate-orders/456/step-back-one-state/
+```
+
+**新方式（推荐）**:
+```bash
+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 行
+
+**问题代码**:
+```python
+# ❌ 错误：只接收 2 个返回值
+success, message = stateflow_services.advance_to_next_state(
+    job.business_object, request.user
+)
+```
+
+**实际签名**:
+```python
+# ✅ 正确：返回 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. 考虑添加废弃警告（可选）
+如果需要渐进式迁移，可以暂时保留旧接口但返回废弃警告：
+```python
+@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  
+**审核状态**: 待人工审核