# 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  
**审核状态**: 待人工审核