forked from erp-dev/erp
feat: stateflow v2 (params required)
This commit is contained in:
402
stateflow/CHANGELOG_2025-11-15.md
Normal file
402
stateflow/CHANGELOG_2025-11-15.md
Normal file
@@ -0,0 +1,402 @@
|
||||
# Stateflow 模块更新日志 - 2025年11月15日
|
||||
|
||||
## 概述
|
||||
本次更新对 stateflow 模块进行了重大重构，主要涉及数据模型关系调整、新增字段、服务层功能扩展、API 接口增强以及测试优化。
|
||||
|
||||
---
|
||||
|
||||
## 一、数据模型变更
|
||||
|
||||
### 1.1 State 与 StateParameter 关系重构
|
||||
**Migration: 0017_state_parameter_many_to_many**
|
||||
|
||||
- **变更内容**：将 State 与 StateParameter 的关系从 **一对多** 改为 **多对多**
|
||||
- **原设计**：StateParameter 通过 ForeignKey 关联到 State（一个参数只能属于一个状态）
|
||||
- **新设计**：State 通过 ManyToManyField 关联 StateParameter（多个状态可以共享同一个参数）
|
||||
- **数据迁移**：清空了旧的测试数据
|
||||
- **影响范围**：
|
||||
- 模型定义：`State.parameters = models.ManyToManyField(StateParameter)`
|
||||
- API 接口：需要使用 `parameter_ids` 进行参数关联
|
||||
- 序列化器：支持参数列表的读写操作
|
||||
|
||||
### 1.2 移除 StateParameter.name 字段
|
||||
**Migration: 0018_remove_stateparameter_name**
|
||||
|
||||
- **变更原因**：`name` 字段与 `key` 字段语义重复
|
||||
- **保留字段**：使用 `key` 作为参数的唯一标识符
|
||||
- **影响**：简化了参数模型，避免了字段冗余
|
||||
|
||||
### 1.3 新增 StateParameter.is_required 字段
|
||||
**Migration: 0019_stateparameter_is_required**
|
||||
|
||||
- **字段类型**：`BooleanField(default=False)`
|
||||
- **用途**：标记参数是否为必填项
|
||||
- **应用场景**：
|
||||
- 前端表单验证
|
||||
- API 可以通过 `required_only=true` 查询参数只获取必填参数
|
||||
- 业务逻辑中强制验证必填参数的提供
|
||||
|
||||
### 1.4 新增 StateParameter.is_image_path 字段
|
||||
**Migration: 0020_stateparameter_is_image_path**
|
||||
|
||||
- **字段类型**：`BooleanField(default=False)`
|
||||
- **用途**：标记 `value` 字段是否存储图片 URL 路径
|
||||
- **应用场景**：
|
||||
- 前端根据此字段决定是否以图片形式渲染
|
||||
- 支持混合参数类型（文本、图片、附件等）
|
||||
- 便于后续扩展不同类型的参数
|
||||
|
||||
---
|
||||
|
||||
## 二、current_state 语义修正（重要变更）
|
||||
|
||||
### 2.1 语义变更
|
||||
**原语义**：`current_state` 表示"下一个待执行的节点"（未完成的节点）
|
||||
**新语义**：`current_state` 表示"最后完成的状态"（已完成的节点）
|
||||
|
||||
### 2.2 影响的函数
|
||||
|
||||
#### stateflow/services.py
|
||||
1. **get_business_object_current_state()**
|
||||
- 原逻辑：返回第一个未完成的节点
|
||||
- 新逻辑：返回最后一个已完成的节点，未开始时返回 None
|
||||
|
||||
2. **advance_to_next_state()**
|
||||
- 更新：基于新的 current_state 逻辑计算下一个待完成节点
|
||||
|
||||
3. **get_next_pending_state()** (新增函数)
|
||||
- 用途：获取下一个待执行节点（替代了原 current_state 的部分功能）
|
||||
|
||||
4. **get_business_object_state_status()**
|
||||
- 移除：删除了 'in_progress' 状态
|
||||
- 保留：只有 'not_started' 和 'completed' 两种状态
|
||||
|
||||
5. **get_overall_status()**
|
||||
- 更新：基于新的 current_state 逻辑判断整体状态
|
||||
|
||||
6. **can_advance_to_next_state()**
|
||||
- 更新：判断逻辑基于新的 current_state 语义
|
||||
|
||||
7. **get_business_object_state_timeline()**
|
||||
- 更新：时间线生成逻辑适配新语义
|
||||
|
||||
#### stateflow/admin.py
|
||||
- **BusinessObjectAdmin.current_state_display()**
|
||||
- 更新：显示最后完成的状态，未开始时显示"未开始"
|
||||
|
||||
### 2.3 测试更新
|
||||
- 更新了 34 个既有测试以适配新语义
|
||||
- 新增 9 个测试用例
|
||||
- 所有 43 个测试全部通过
|
||||
|
||||
---
|
||||
|
||||
## 三、新增服务层功能
|
||||
|
||||
### 3.1 get_next_pending_state()
|
||||
**位置**：`stateflow/services.py`
|
||||
|
||||
```python
|
||||
def get_next_pending_state(business_object, include_parameters=True):
|
||||
"""
|
||||
获取业务对象的下一个待执行节点
|
||||
|
||||
参数:
|
||||
business_object: 业务对象实例
|
||||
include_parameters: 是否包含节点参数（默认 True）
|
||||
|
||||
返回:
|
||||
dict 或 None: 包含 state, order, parameters（可选）
|
||||
"""
|
||||
```
|
||||
|
||||
**功能**：
|
||||
- 返回流程中下一个未完成的节点
|
||||
- 可选择是否包含该节点的参数列表
|
||||
- 流程完成时返回 None
|
||||
|
||||
**测试**：`test_get_next_pending_state()` - 已通过
|
||||
|
||||
### 3.2 get_all_pending_states()
|
||||
**位置**：`stateflow/services.py`
|
||||
|
||||
```python
|
||||
def get_all_pending_states(business_object):
|
||||
"""
|
||||
获取业务对象的所有待执行节点列表
|
||||
|
||||
参数:
|
||||
business_object: 业务对象实例
|
||||
|
||||
返回:
|
||||
list: 包含所有待执行节点的列表
|
||||
"""
|
||||
```
|
||||
|
||||
**功能**：
|
||||
- 返回所有尚未完成的节点列表（按顺序）
|
||||
- 不包含参数信息（减少数据量）
|
||||
- 适用于显示整体进度
|
||||
|
||||
**测试**：`test_get_all_pending_states()` - 已通过
|
||||
|
||||
### 3.3 get_state_parameters()
|
||||
**位置**：`stateflow/services.py`
|
||||
|
||||
```python
|
||||
def get_state_parameters(state, required_only=False):
|
||||
"""
|
||||
获取状态的参数列表
|
||||
|
||||
参数:
|
||||
state: State 实例
|
||||
required_only: 是否只返回必填参数（默认 False）
|
||||
|
||||
返回:
|
||||
QuerySet: StateParameter 查询集
|
||||
"""
|
||||
```
|
||||
|
||||
**功能**：
|
||||
- 获取指定状态的所有参数
|
||||
- 支持筛选只返回必填参数
|
||||
- 基于多对多关系查询
|
||||
|
||||
**测试**：`test_get_state_parameters()` - 已通过
|
||||
|
||||
---
|
||||
|
||||
## 四、新增 API 接口
|
||||
|
||||
### 4.1 获取下一个待执行节点
|
||||
**端点**：`GET /api/v1/stateflow/business-objects/{id}/next_pending_state/`
|
||||
|
||||
**查询参数**：
|
||||
- `include_parameters`: boolean（默认 true）- 是否包含参数
|
||||
|
||||
**响应示例**：
|
||||
```json
|
||||
{
|
||||
"business_object_id": 1,
|
||||
"next_state": {
|
||||
"state": {
|
||||
"id": 1,
|
||||
"name": "状态1",
|
||||
"description": "第一个状态"
|
||||
},
|
||||
"order": 0,
|
||||
"parameters": [
|
||||
{
|
||||
"id": 1,
|
||||
"key": "param1",
|
||||
"value": "value1",
|
||||
"is_required": true,
|
||||
"is_image_path": false
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**测试**：`test_next_pending_state_api()` - 已通过
|
||||
|
||||
### 4.2 获取所有待执行节点
|
||||
**端点**：`GET /api/v1/stateflow/business-objects/{id}/pending_states/`
|
||||
|
||||
**响应示例**：
|
||||
```json
|
||||
{
|
||||
"business_object_id": 1,
|
||||
"count": 3,
|
||||
"pending_states": [
|
||||
{
|
||||
"state": {"id": 1, "name": "状态1"},
|
||||
"order": 0
|
||||
},
|
||||
{
|
||||
"state": {"id": 2, "name": "状态2"},
|
||||
"order": 1
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**测试**：`test_pending_states_api()` - 已通过
|
||||
|
||||
### 4.3 获取当前状态的参数
|
||||
**端点**：`GET /api/v1/stateflow/business-objects/{id}/current_state_parameters/`
|
||||
|
||||
**查询参数**：
|
||||
- `required_only`: boolean（默认 false）- 是否只返回必填参数
|
||||
|
||||
**响应示例**：
|
||||
```json
|
||||
{
|
||||
"business_object_id": 1,
|
||||
"state": {
|
||||
"id": 1,
|
||||
"name": "状态1"
|
||||
},
|
||||
"count": 2,
|
||||
"parameters": [
|
||||
{
|
||||
"id": 1,
|
||||
"key": "param1",
|
||||
"is_required": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**注意**：当 business_object 未开始时（current_state 为 None），返回空参数列表和提示消息。
|
||||
|
||||
**测试**：`test_current_state_parameters_api()` - 已通过
|
||||
|
||||
### 4.4 获取状态的参数列表
|
||||
**端点**：`GET /api/v1/stateflow/states/{id}/parameters/`
|
||||
|
||||
**查询参数**：
|
||||
- `required_only`: boolean（默认 false）- 是否只返回必填参数
|
||||
|
||||
**响应示例**：
|
||||
```json
|
||||
{
|
||||
"state_id": 1,
|
||||
"count": 2,
|
||||
"parameters": [
|
||||
{
|
||||
"id": 1,
|
||||
"key": "param1",
|
||||
"value": "value1",
|
||||
"is_required": true,
|
||||
"is_image_path": false,
|
||||
"description": "参数描述"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**测试**：`test_state_parameters_api()` - 已通过
|
||||
|
||||
---
|
||||
|
||||
## 五、测试优化
|
||||
|
||||
### 5.1 测试文件重组
|
||||
**变更**：将 `stateflow/tests.py` 移动到 `stateflow/tests/test_services.py`
|
||||
|
||||
**原因**：
|
||||
- 解决文件与目录命名冲突
|
||||
- 符合 Django 测试最佳实践
|
||||
- 便于后续测试文件的组织和扩展
|
||||
|
||||
### 5.2 测试数据管理优化
|
||||
**优化的测试类**：`StateAPITestCase`
|
||||
|
||||
**改进内容**：
|
||||
- 将重复的测试数据创建移至 `setUp()` 方法
|
||||
- 创建共享的基础数据：`self.param1`, `self.param2`, `self.state1`, `self.state2`
|
||||
- 避免每个测试方法中重复创建相同数据
|
||||
- 提高测试执行效率和可维护性
|
||||
|
||||
**优化前**：每个测试方法内部创建 State 和 Parameter
|
||||
**优化后**：在 setUp 中创建基础数据，测试方法直接使用
|
||||
|
||||
### 5.3 新增测试用例
|
||||
**文件**：`stateflow/test_api.py` - `BusinessObjectNewAPITestCase`
|
||||
|
||||
包含 4 个新的 API 测试：
|
||||
1. `test_next_pending_state_api()` - 测试获取下一个待执行节点
|
||||
2. `test_pending_states_api()` - 测试获取所有待执行节点
|
||||
3. `test_current_state_parameters_api()` - 测试获取当前状态参数
|
||||
4. `test_state_parameters_api()` - 测试获取状态参数列表
|
||||
|
||||
**文件**：`stateflow/tests/test_services.py`
|
||||
|
||||
新增 3 个服务层测试：
|
||||
1. `test_get_next_pending_state()` - 测试获取下一个待执行节点服务
|
||||
2. `test_get_all_pending_states()` - 测试获取所有待执行节点服务
|
||||
3. `test_get_state_parameters()` - 测试获取状态参数服务
|
||||
|
||||
### 5.4 测试覆盖率
|
||||
- **总测试数**：43 个
|
||||
- **测试状态**：全部通过 ✓
|
||||
- **执行时间**：约 6.5 秒
|
||||
- **覆盖模块**：
|
||||
- 数据模型（Model）
|
||||
- 服务层（Services）
|
||||
- API 接口（Views）
|
||||
- 序列化器（Serializers）
|
||||
|
||||
---
|
||||
|
||||
## 六、受影响的文件清单
|
||||
|
||||
### 6.1 模型层
|
||||
- `stateflow/models.py` - State 和 StateParameter 关系及字段变更
|
||||
|
||||
### 6.2 服务层
|
||||
- `stateflow/services.py` - current_state 逻辑修正 + 3 个新函数
|
||||
|
||||
### 6.3 序列化器
|
||||
- `stateflow/serializers.py` - 适配多对多关系和新字段
|
||||
|
||||
### 6.4 管理后台
|
||||
- `stateflow/admin.py` - current_state 显示逻辑更新
|
||||
|
||||
### 6.5 API 视图
|
||||
- `api_v1/views/stateflow/business_object.py` - 新增 3 个 action
|
||||
- `api_v1/views/stateflow/state.py` - 新增 1 个 action
|
||||
|
||||
### 6.6 测试文件
|
||||
- `stateflow/tests/test_services.py` - 服务层测试（重组 + 新增）
|
||||
- `stateflow/test_api.py` - API 测试（优化 + 新增）
|
||||
- `stateflow/tests/test_step_back.py` - 更新适配新语义
|
||||
- `stateflow/tests/test_step_back_api.py` - 更新适配新语义
|
||||
|
||||
### 6.7 数据库迁移
|
||||
- `0017_state_parameter_many_to_many.py`
|
||||
- `0018_remove_stateparameter_name.py`
|
||||
- `0019_stateparameter_is_required.py`
|
||||
- `0020_stateparameter_is_image_path.py`
|
||||
|
||||
---
|
||||
|
||||
## 七、向后兼容性
|
||||
|
||||
### 7.1 破坏性变更
|
||||
1. **StateParameter.state 字段已移除** - 不再支持一对多关系
|
||||
2. **StateParameter.name 字段已移除** - 请使用 `key` 字段
|
||||
3. **current_state 语义变更** - 从"下一个待执行"变为"最后完成的"
|
||||
4. **移除 'in_progress' 状态** - 只保留 'not_started' 和 'completed'
|
||||
|
||||
### 7.2 迁移建议
|
||||
- 如果代码中使用了 `business_object.get_current_state()` 期望获取"下一个待执行节点"，请改用 `get_next_pending_state(business_object)`
|
||||
- 如果代码中引用了 `parameter.state`，请改用 `parameter.states.all()` 获取关联的状态列表
|
||||
- 如果代码中使用了 `parameter.name`，请改用 `parameter.key`
|
||||
|
||||
---
|
||||
|
||||
## 八、后续工作计划
|
||||
|
||||
### 8.1 待验证模块
|
||||
- **api_man 模块**：需要检查其中可能存在的 State 和 StateParameter 相关接口，确保兼容本次变更
|
||||
|
||||
### 8.2 待扩展功能
|
||||
- **printing 模块依赖更新**：验证 printing 模块对 stateflow 的依赖是否需要调整
|
||||
- **参数验证逻辑**：实现基于 `is_required` 的自动验证机制
|
||||
- **图片参数处理**：完善 `is_image_path` 的前后端集成
|
||||
|
||||
---
|
||||
|
||||
## 九、总结
|
||||
|
||||
本次更新显著提升了 stateflow 模块的灵活性和可维护性：
|
||||
|
||||
1. **更灵活的参数管理**：多对多关系允许参数复用
|
||||
2. **更明确的语义**：current_state 现在准确表示"已完成到哪里"
|
||||
3. **更强大的 API**：新增 4 个接口满足不同查询需求
|
||||
4. **更完善的测试**：43 个测试确保代码质量
|
||||
5. **更清晰的代码组织**：测试文件重组，数据管理优化
|
||||
|
||||
所有变更已通过完整测试验证，可以安全部署。
|
||||
Reference in New Issue
Block a user