Files
dxdesigner-part-replacement/docs/architecture/bom-import-lifecycle.md
T

46 lines
3.2 KiB
Markdown

# BOM 导入状态机
用户反馈:失败后重新导入时,旧失败报告在新结果出来前仍显示。导入生命周期由 `bom_import_state.py` 的 `BomImportMachine` 管理;`ProjectPlanPanel` 按批次(无批次则按任务)保存状态机。界面不再分别保存报告缓存和状态文字缓存。
```mermaid
stateDiagram-v2
[*] --> 空闲
空闲 --> 读取表格: 开始
读取表格 --> 校验表格
校验表格 --> 获取库存
获取库存 --> 匹配位号
匹配位号 --> 获取库存: 下一工程
匹配位号 --> 预览就绪: 全部通过
读取表格 --> 校验未通过: 文件错误
校验表格 --> 校验未通过: 格式或规则错误
匹配位号 --> 校验未通过: 匹配错误
读取表格 --> 取消中: 请求取消
校验表格 --> 取消中: 请求取消
获取库存 --> 取消中: 请求取消
匹配位号 --> 取消中: 请求取消
取消中 --> 已取消: 后台收尾完成
取消中 --> 异常: 收尾失败
```
图示突出主路径。读取、校验、库存与匹配阶段均可因运行异常转入 `FAILED`,也可返回含错误行的 `REJECTED` 报告;完整转换规则以 `_NEXT`、`receive`、`finish` 为准。
## 约束
- `phase` 表示业务阶段;`settled` 表示后台工作线程是否完成收尾。收到最终报告后仍可能暂时 `busy=True`,此时禁止启动新导入;取消按钮只在仍接收阶段事件时可用。
- `start()` 增加 `attempt`,同时清除本轮旧报告与提示。取消文件选择不会调用 `start()`。
- 阶段事件由后端 `on_phase(phase, message)` 明确发出,不解析中文提示来判断阶段。普通 `on_progress(message)` 只更新当前合法阶段内的进度。
- 所有转换在 GUI 线程处理。旧停止事件、被替换的状态机实例和旧 `attempt` 的回调都不能更新当前导入。
- 取消请求先进入 `CANCELLING`,阻止后续进度和结果;真实异常优先于取消,工作线程结束才进入 `CANCELLED` 或 `FAILED`。
- `report` 是状态的一部分,摘要和详情在显示时生成。保存、放弃预览只释放报告中的预览引用,保留 `PREVIEW_READY` 的成功含义并更新说明。
- 替换计划草稿独立于导入状态。失败、取消、重试不会自动删除已有草稿。保存与执行前的工程核验保持原流程。
此状态机只负责 BOM 导入,不替代数据库中的任务执行状态,也不管理原生 CAD 会话资源本身。
## 验证
`tests/v1_1/test_bom_import_state.py` 验证轮次隔离、非法倒退、多工程往返、取消与异常优先级、成功报告释放预览后的语义。UI 回归验证阶段事件驱动提示和按钮、等待状态不会被普通摘要刷新覆盖,以及取消后的迟到事件不会恢复旧结果。服务回归验证两工程发出明确的阶段序列。
新增用例先确认失败,再接入实现。首轮 BOM、任务 UI、预览及懒加载定向回归:70 项通过,22.97 秒。测试使用 offscreen Qt 和模拟库存,不重复启动真实 CAD。
最终加入库存取消、界面响应与保存安全回归,合计 90 项通过,34.78 秒。只读代码复核未发现新增问题;两轮测试有重叠,不累加计数。