131 lines
7.5 KiB
Plaintext
131 lines
7.5 KiB
Plaintext
Model 重构总计划(数据库 + Migrations + Models)
|
||
更新时间: 2026-03-22
|
||
当前状态: 执行中(阶段 1-3 已完成)
|
||
负责人:
|
||
目标截止时间:
|
||
执行分支:
|
||
|
||
[事务归属]
|
||
- 本子事务已纳入 `todo.txt` 总事务看板统一管理。
|
||
- 主里程碑对齐总事务 DDL(2026-04-15),以总事务验收为最终关闭条件。
|
||
|
||
[最终目标]
|
||
- 梳理数据库中所有表结构并形成统一基线。
|
||
- 补全并对齐 database/migrations 目录下的迁移文件。
|
||
- 规范所有 model 的命名与内部关联。
|
||
- 清理所有 model 内部能力(移除死代码、职责收敛、保持模型层可预测)。
|
||
|
||
[执行规则]
|
||
- [x] 本文件用于规划拆解,已完成初始化。
|
||
- [x] 已收到新任务,开始执行阶段 1。
|
||
- [x] 进入代码改动前,先核对目标 service 的真实调用链。
|
||
- [x] 若 service 已被 system/qimen 入口使用,则必须同步更新对应 API 文档。
|
||
- [x] 所有联动修改需记录到 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 在根目录生成 modelList.md,构建 model 层级结构与说明。
|
||
- [x] 1.6 在 README.md 增加对 modelList.md 的引用说明。
|
||
交付物:
|
||
- table_schema_inventory.md
|
||
- model_inventory.md
|
||
- model_association_inventory.md
|
||
- schema_model_gap_report.md
|
||
- modelList.md
|
||
退出标准:
|
||
- 100% 数据表与 100% model 文件覆盖完成。
|
||
- modelList.md 可用于快速定位模型层级与职责。
|
||
|
||
[阶段 2: Migration 补全与执行顺序设计]
|
||
- [x] 2.1 审核现有 database/migrations 的命名、顺序、幂等性。
|
||
- [x] 2.2 根据阶段 1 差异清单补齐缺失迁移任务。
|
||
- [x] 2.3 设计迁移执行顺序(先结构后索引/约束,必要时分批回填数据)。
|
||
- [x] 2.4 为每个迁移定义可执行回滚步骤。
|
||
- [x] 2.5 形成 local/test 环境演练方案。
|
||
交付物:
|
||
- migration_gap_list.md
|
||
- migration_execution_plan.md
|
||
- rollback_plan.md
|
||
退出标准:
|
||
- 每个结构差异都有明确迁移归属与回滚路径。
|
||
|
||
[阶段 3: Model 命名规范化]
|
||
- [x] 3.1 定义命名规范(文件名、类名、model key、表映射、alias)。
|
||
- [x] 3.2 产出非规范命名的重命名映射表。
|
||
- [x] 3.3 评估跨层影响(service/controller/query 调用点)。
|
||
- [x] 3.4 制定兼容策略(临时别名或分批重命名)。
|
||
交付物:
|
||
- model_naming_standard.md
|
||
- model_rename_map.md
|
||
- rename_impact_report.md
|
||
退出标准:
|
||
- 所有命名不规范项有明确修复路径与影响说明。
|
||
|
||
[阶段 4: 关联关系规范化]
|
||
- [x] 4.1 逐项校验关联定义与真实外键关系一致性(详见 association_fk_consistency_report.md)。
|
||
- [x] 4.2 统一 alias 命名与双向关联完整性。
|
||
- [x] 4.3 清理重复或冲突关联。
|
||
- [x] 4.4 形成 eager-loading 与 N+1 风险规约(详见 association_eager_loading_n_plus_one_guideline.md)。
|
||
交付物:
|
||
- association_fix_plan.md
|
||
- association_validation_checklist.md
|
||
退出标准:
|
||
- 关联关系可预测、无冲突、与数据库关系一致。
|
||
|
||
[阶段 5: Model 内部能力清理]
|
||
- [x] 5.1 识别应迁移到 service 层的方法能力(见 model_cleanup_list.md 第一批清单)。
|
||
- [ ] 5.2 清理 model 内死代码与调试代码(进行中:第一批/第二批 P2 无调用静态方法已清理;P1 前两组 EntryOrder/EntryItems 与 Storage 已迁移到 service)。
|
||
- [ ] 5.3 规范 hooks/scopes/virtual fields 的使用边界。
|
||
- [ ] 5.4 固化模型层边界规则(可做/不可做)。
|
||
交付物:
|
||
- model_cleanup_list.md
|
||
- 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 哨兵数据均已处理(备份表见 `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 层的方法能力(第一批清单见 model_cleanup_list.md)。
|
||
- 已启动阶段 5.2:已完成第一批 P2 无调用静态方法清理(ApiApp / InterfaceType / PrintItem),门禁通过。
|
||
- 已完成阶段 5.2 删除前引用复核(第二批):I18nTranslation 5 个候选静态方法、StockStore 2 个候选静态方法均未检出业务调用。
|
||
- 已完成阶段 5.2 第二批 P2 方法删除(I18nTranslation / StockStore),compare + generated regression + smoke 门禁通过。
|
||
- 已完成阶段 5.2 P1 第一组迁移:EntryOrder / EntryItems 共 8 个静态方法已迁移到 `app/service/systems/entry_order.js`,并从 model 删除;compare + generated regression + smoke 门禁通过。
|
||
- 已完成阶段 5.2 P1 第二组迁移:Storage 共 10 个静态方法已迁移到 `app/service/systems/storage/index.js`,并从 model 删除。
|
||
- 下一步继续阶段 5.2:推进 P1 剩余方法(RolePermission / Store)从 model 向 service 收敛,并在迁移完成后回收对应静态方法。
|