forked from erp-dev/erp
255 lines
6.9 KiB
Markdown
255 lines
6.9 KiB
Markdown
# 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
|
||
**审核状态**: 待人工审核
|