WMS_MAIN/model_todo.txt

136 lines
8.1 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Model 重构总计划(数据库 + Migrations + Models)
更新时间: 2026-03-23
当前状态: 执行中(阶段 1-5 已完成,阶段 6 进行中)
负责人:
目标截止时间:
执行分支:
[事务归属]
- 本子事务已纳入 `todo.txt` 总事务看板统一管理。
- 主里程碑对齐总事务 DDL(2026-04-15),以总事务验收为最终关闭条件。
[最终目标]
- 梳理数据库中所有表结构并形成统一基线。
- 补全并对齐 database/migrations 目录下的迁移文件。
- 规范所有 model 的命名与内部关联。
- 清理所有 model 内部能力(移除死代码、职责收敛、保持模型层可预测)。
[执行规则]
- [x] 本文件用于规划拆解,已完成初始化。
- [x] 已收到新任务,开始执行阶段 1。
- [x] 进入代码改动前,先核对目标 service 的真实调用链。
- [x] 若 service 已被 system/qimen 入口使用,则必须同步更新对应 API 文档。
- [x] 所有联动修改需记录到 temp/docs/SERVICE_API_CHANGE_AUDIT_20260322.md,便于后续复盘。
- [x] 任何模型/关联改动前,使用测试账号执行 method 基线回放(配置与样本来源必须可追溯)。
- [x] 任何模型/关联改动后,执行同一批 method 对比回放并输出比对报告。
- [x] 新增交付条件:修改前后 method 输出结果一致(允许仅屏蔽 token/timestamp 等波动字段)。
- [x] 后续所有接口返回数据检测,统一使用“自动生成的 Egg.js 标注测试脚本”执行校验。
[阶段 1: 全量盘点与基线建立]
- [x] 1.1 盘点所有数据表(字段、主键、索引、约束、注释)。
- [x] 1.2 盘点所有 model 文件(app/model 下文件、导出名、表映射)。
- [x] 1.3 盘点 model 关联(belongsTo/hasMany/hasOne/belongsToMany 与外键使用)。
- [x] 1.4 产出 DB 结构与 model 定义差异报告。
- [x] 1.5 在根目录生成 temp/docs/modelList.md,构建 model 层级结构与说明。
- [x] 1.6 在 README.md 增加对 temp/docs/modelList.md 的引用说明。
交付物:
- temp/docs/table_schema_inventory.md
- temp/docs/model_inventory.md
- temp/docs/model_association_inventory.md
- temp/docs/schema_model_gap_report.md
- temp/docs/modelList.md
退出标准:
- 100% 数据表与 100% model 文件覆盖完成。
- temp/docs/modelList.md 可用于快速定位模型层级与职责。
[阶段 2: Migration 补全与执行顺序设计]
- [x] 2.1 审核现有 database/migrations 的命名、顺序、幂等性。
- [x] 2.2 根据阶段 1 差异清单补齐缺失迁移任务。
- [x] 2.3 设计迁移执行顺序(先结构后索引/约束,必要时分批回填数据)。
- [x] 2.4 为每个迁移定义可执行回滚步骤。
- [x] 2.5 形成 local/test 环境演练方案。
交付物:
- temp/docs/migration_gap_list.md
- temp/docs/migration_execution_plan.md
- temp/docs/rollback_plan.md
退出标准:
- 每个结构差异都有明确迁移归属与回滚路径。
[阶段 3: Model 命名规范化]
- [x] 3.1 定义命名规范(文件名、类名、model key、表映射、alias)。
- [x] 3.2 产出非规范命名的重命名映射表。
- [x] 3.3 评估跨层影响(service/controller/query 调用点)。
- [x] 3.4 制定兼容策略(临时别名或分批重命名)。
交付物:
- temp/docs/model_naming_standard.md
- temp/docs/model_rename_map.md
- temp/docs/rename_impact_report.md
退出标准:
- 所有命名不规范项有明确修复路径与影响说明。
[阶段 4: 关联关系规范化]
- [x] 4.1 逐项校验关联定义与真实外键关系一致性(详见 temp/docs/association_fk_consistency_report.md)。
- [x] 4.2 统一 alias 命名与双向关联完整性。
- [x] 4.3 清理重复或冲突关联。
- [x] 4.4 形成 eager-loading 与 N+1 风险规约(详见 temp/docs/association_eager_loading_n_plus_one_guideline.md)。
交付物:
- temp/docs/association_fix_plan.md
- temp/docs/association_validation_checklist.md
退出标准:
- 关联关系可预测、无冲突、与数据库关系一致。
[阶段 5: Model 内部能力清理]
- [x] 5.1 识别应迁移到 service 层的方法能力(见 temp/docs/model_cleanup_list.md 第一批清单)。
- [x] 5.2 清理 model 内死代码与调试代码(已完成:P2 两批无调用静态方法清理 + P1 四组方法迁移并回收 model 同名方法)。
- [x] 5.3 规范 hooks/scopes/virtual fields 的使用边界(盘点完成并已产出 temp/docs/model_boundary_rules.md)。
- [x] 5.4 固化模型层边界规则(新增 script/model-boundary-check.cjs 并接入 npm run check:model-boundary)。
交付物:
- temp/docs/model_cleanup_list.md
- temp/docs/model_boundary_rules.md
退出标准:
- 模型层聚焦于数据映射与轻量领域行为,职责边界清晰。
[阶段 6: 验证与交接]
- [ ] 6.1 在干净库上回放 migration 全流程。
- [ ] 6.2 验证 model CRUD 与关联查询正确性。
- [ ] 6.3 执行关键 API 冒烟回归(包含 method-output 基线/对比)。
- [ ] 6.4 更新最终文档(README + methods + 内部交接文档)。
交付物:
- verification_report.md
- handover_notes.md
退出标准:
- 无迁移漂移、无关联错配、无阻断回归问题。
[风险]
- 历史遗留表或隐式依赖未被识别。
- 环境间数据漂移导致验证结果不一致。
- 命名调整引发跨层调用副作用。
[依赖]
- 稳定可访问的数据库环境(盘点与验证)。
- 统一确认的命名与关联规范。
- 可执行的迁移窗口与回滚窗口。
[下一步]
- 阶段 4 的 4.1-4.4 已完成(含 receiving 第一批收敛与 N+1/eager-loading 规约落地)。
- 高优先差异项推进: 已完成 store_warehouse/stock_warehouse 第二批收敛(stock_store include 语义约束补齐),并通过门禁。
- 高优先差异项推进: 已完成 role / role_permission / permission 第三批收敛(启用状态过滤 + 去重),并通过门禁。
- 已完成“DB 约束补齐”执行: `wms_role_permission.permission_id -> wms_permission.id` 外键已生效,SequelizeMeta 已登记 `20260323103000-align-role-permission-fk.js`。
- 已完成数据清洗与备份: 4 条 permission 孤儿、3 条 role.store_id=0 哨兵数据均已处理(备份表见 `temp/docs/role_permission_fk_data_cleanup_plan.md`)。
- 已完成 `wms_role.store_id` 外键策略落地:外键 `fk_wms_role_store` 已生效(ON DELETE SET NULL),SequelizeMeta 已登记 `20260323113000-add-role-store-fk.js`。
- 已完成 store_warehouse / stock_warehouse 模型层复合键语义治理(统一 include 构造器 + constraints:false 显式化)。
- 已完成阶段 4 收尾检查(第 1 项):全量 include alias 一致性扫描(service alias 与 model alias 差集=0)。
- 已完成阶段 4 收尾检查(第 2 项):permission.parent_id 自关联约束策略已落地(root=NULL + FK)。
- 已完成阶段 5.1:识别应迁移到 service 层的方法能力(第一批清单见 temp/docs/model_cleanup_list.md)。
- 已完成阶段 5.2 第一批 P2 清理:ApiApp / InterfaceType / PrintItem,门禁通过。
- 已完成阶段 5.2 第二批 P2 清理:I18nTranslation / StockStore,门禁通过。
- 已完成阶段 5.2 P1 第一组:EntryOrder / EntryItems 8 个方法迁移到 service 并回收 model 同名方法。
- 已完成阶段 5.2 P1 第二组:Storage 10 个方法迁移到 service 并回收 model 同名方法。
- 已完成阶段 5.2 P1 第三组:Role / RolePermission 7 个方法迁移到 service 并回收 model 同名方法。
- 已完成阶段 5.2 P1 第四组:Store 5 个方法迁移到 service 并回收 model 同名方法。
- 已完成阶段 5.3:hooks/scopes/virtual fields 边界盘点与规则固化(见 temp/docs/model_boundary_rules.md)。
- 已完成阶段 5.4:新增 model 边界检查脚本并接入 npm 命令与 CI(check:model-boundary)。
- 已复跑阶段 5.4 门禁命令:`npm run check:model-boundary`,结果 PASS(files=45, hooks=2, scopeFiles=1, virtualLines=0)。
- 过程门禁:compare mismatch=0;generated regression 与 smoke 持续通过;新增 model-boundary 检查门禁。
- 下一步进入阶段 6.1:在干净库上回放 migration 全流程。