WMS_MAIN/temp/docs/association_validation_checklist.md

8.5 KiB
Raw Blame History

Association Validation Checklist

更新时间: 2026-03-23 范围: app/model/*.js + 核心系统 service 调用链

1. 核心检查项

  • AccountStoreRole 幽灵引用已移除(服务主链路)。
  • AccountStoreEmployee <-> EmployeeRole <-> Role 关系可用。
  • hasMany alias 复数化(employeeRoles/accountStoreEmployees)。
  • 重复兼容 alias 已清理(主链路)。
  • 对外接口输出一致(baseline/compare mismatch=0)。
  • 关键登录与用户信息链路测试通过。

2. 关键模型校验结果

模型 关键关联 结果 备注
Account hasMany AccountStoreEmployee as accountStoreEmployees PASS 已移除 accountStoreRoles
AccountStoreEmployee hasMany EmployeeRole as employeeRoles PASS 已移除 employeeRole
Role hasMany EmployeeRole as employeeRoles PASS 已移除 employeeRole
Store hasMany AccountStoreEmployee as accountStoreEmployees PASS 已移除 accountStoreEmployee
AccountPlatformActive belongsTo AccountStoreEmployee as accountStoreEmployee PASS belongsTo 单数语义保留

3. 服务调用链校验结果

服务 校验项 结果
systems/account_platform include/读取 employeeRoles 一致 PASS
systems/auth/user include alias 使用 employeeRoles PASS
systems/store 角色绑定链路使用 EmployeeRole PASS
systems/storage/receiving StoreWarehouse 关联补 warehouse_id/use_status 过滤,避免跨仓错关联 PASS

4. 验证记录

  • method-output compare: mismatch=0
  • generated test: 8 passing
  • smoke test (login/info/home): 6 passing

5. 4.1 全量审计结果(2026-03-23)

  • 审计报告: association_fk_consistency_report.md
  • DB 外键: 51
  • 模型关联: 89
  • 可直接匹配: 53
  • 模型定义但 DB 无外键约束: 28
  • DB 有外键但模型未声明: 13
  • 动态模型/示例占位导致无法静态解析: 5

高优先级差异(建议先处理):

  • receiving / receiving_detail / storage 三表关联的 FK 约束缺失项(第一批已处理:删除无效 hasMany(Storage) 关联,并修正 service include 过滤)
  • store_warehouse 与 stock_warehouse/receiving 的 store_id 外键语义差异(已完成服务层与模型层双收敛)
  • role / role_permission / permission 的部分 FK 未在 DB 层约束(核心约束已补齐,remaining: permission.parent_id 自关联约束策略评估)

5.1 高优先差异处理进展(receiving 第一批)

  • 处理内容:
    • 移除 Receiving.hasMany(Storage, foreignKey: 'receiving_id') 无效关联(storage 表不存在 receiving_id)。
    • 移除 ReceivingDetail.hasMany(Storage, foreignKey: 'receiving_detail_id') 无效关联(storage 表不存在 receiving_detail_id)。
    • systems/storage/receiving 多处 StoreWarehouse include/query 增加 warehouse_id + use_status 过滤,规避跨仓库错关联。
    • create 流程中 store_name 改为来源 store_remask,与仓库门店展示语义对齐。
  • 验证结果:
    • method-output compare: mismatch=0
    • generated regression + smoke: 14 passing

5.2 高优先差异处理进展(store_warehouse/stock_warehouse 第二批)

  • 处理内容:
    • systems/stock_store 的 store_stock include 全量补齐 warehouse_id + use_status 条件,避免仅按 store_id 关联导致跨仓误匹配。
    • 覆盖 count/findAll/search 三处核心查询路径,保持原有返回结构不变。
  • 验证结果:
    • method-output compare: mismatch=0
    • generated regression + smoke: 14 passing

5.3 高优先差异处理进展(role/permission 第三批)

  • 处理内容:
    • systems/auth/user 的权限与菜单查询链路补齐 Role.status=1 约束,仅启用角色参与授权。
    • 权限查询补齐 Permission.status=1 约束,禁用权限不再进入 user.permissions 与菜单树。
    • 对 role_id/permission_id 增加去重处理,避免重复关联导致的冗余查询和重复路径。
  • 验证结果:
    • method-output compare: mismatch=0
    • generated regression + smoke: 14 passing

5.4 DB 约束补齐进展(role_permission 第四批)

  • 处理内容:
    • 新增迁移 database/migrations/20260323103000-align-role-permission-fk.js:
      • 将 wms_role_permission.permission_id 对齐为 int(11)(与 wms_permission.id 一致)。
      • 在无孤儿数据时添加 fk_wms_role_permission_permission 外键(ON DELETE CASCADE, ON UPDATE RESTRICT)。
    • 同步模型字段类型: app/model/role_permission.js 的 permission_id 改为 INTEGER。
  • 执行结果:
    • 已完成数据清洗:wms_role_permission.permission_id 孤儿记录 4 条已备份并删除;wms_role.store_id=0 的 3 条记录已备份并修正为 NULL。
    • 已执行迁移核心动作:permission_id 类型已对齐为 int(11),且外键 fk_wms_role_permission_permission 已生效。
    • SequelizeMeta 已登记 20260323103000-align-role-permission-fk.js。
    • 门禁结果:method-output compare mismatch=0,generated regression + smoke: 14 passing。

5.5 DB 约束补齐进展(role.store_id 第五批)

  • 处理内容:
    • 新增迁移 database/migrations/20260323113000-add-role-store-fk.js:
      • 将 wms_role.store_id 对齐为 bigint(20) unsigned NULL。
      • 补充索引 idx_store_id。
      • 添加外键 fk_wms_role_store(ON UPDATE RESTRICT, ON DELETE SET NULL)。
  • 执行结果:
    • wms_role.store_id 外键已生效,孤儿计数=0。
    • SequelizeMeta 已登记 20260323113000-add-role-store-fk.js。
    • 门禁结果:method-output compare mismatch=0,generated regression + smoke: 14 passing。

5.6 模型层复合键语义治理进展(store_warehouse/stock_warehouse 第六批)

  • 处理内容:
    • StoreWarehouse 模型新增统一构造器:buildScopedWhere / buildStoreStockInclude,收敛 store_stock include 的复合键语义。
    • StockWarehouse.belongsTo(StoreWarehouse as store_stock) 与 StoreWarehouse.hasMany(StockWarehouse as store_stock) 显式标记 constraints: false,避免误导为单列外键。
    • Receiving.belongsTo(StoreWarehouse as store) 显式标记 constraints: false,与 store_id + warehouse_id 业务语义对齐。
    • systems/stock_store 与 systems/storage/receiving 已改为复用模型构造器,减少散落条件。
  • 验证结果:
    • method-output compare: mismatch=0
    • generated regression + smoke: 14 passing

5.7 DB 约束补齐进展(permission.parent_id 第七批)

  • 处理内容:
    • 新增迁移 database/migrations/20260323123000-add-permission-parent-fk.js:
      • 将 wms_permission.parent_id 根节点语义从 0 规范为 NULL。
      • 添加自关联外键 fk_wms_permission_parent(ON UPDATE RESTRICT, ON DELETE SET NULL)。
    • 模型与服务语义对齐:
      • Permission.parent_id 改为 allowNull: true / defaultValue: null,并在 setter 中兼容输入 0 -> NULL。
      • 权限树构建根节点判断由 parent_id===0 收敛为 !parent_id(兼容历史与新语义)。
  • 执行结果:
    • 数据复核: root_zero_after=0、root_null_after=42、orphan_after=0。
    • 外键生效: fk_wms_permission_parent 已存在。
    • SequelizeMeta 已登记 20260323123000-add-permission-parent-fk.js。
    • 触发器策略: 目标库因权限限制(binlog + SUPER)未创建触发器,改由应用层归一化 0 -> NULL。
  • 验证结果:
    • method-output compare: mismatch=0
    • generated regression + smoke: 14 passing

6. 后续检查

  • 全量扫描其余模型类方法中的 include 别名一致性(service as 与 model as 差集扫描结果: 0)。
  • 补充 N+1 风险清单与 eager-loading 建议(见 association_eager_loading_n_plus_one_guideline.md)。

6.1 include alias 一致性收尾扫描(2026-03-23)

  • 扫描范围:
    • app/model/**/*.js 中 association as 定义
    • app/service/**/*.js 中 include as 使用
  • 扫描方式:
    • 先做全量检索(model association / service include)
    • 再做集合差集(service alias - model alias)自动比对
  • 扫描结论:
    • model alias 总数: 48
    • 差集可疑项: 0
    • 结论: 未发现 include alias 不一致问题,可关闭阶段 4 收尾检查第 1 项。

7. 4.4 规约落地记录(2026-03-23)

  • 规约文档: association_eager_loading_n_plus_one_guideline.md
  • 已固化要求:
    • 禁止循环内逐条查询关联表(N+1)。
    • include 必须声明 attributes。
    • 仓库链路 include 必须补齐 warehouse_id + use_status 约束。
    • 涉及关联查询改动必须执行 compare + generated test + smoke。