8.5 KiB
8.5 KiB
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多处StoreWarehouseinclude/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_stockinclude 全量补齐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_stockinclude 的复合键语义。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中 associationas定义app/service/**/*.js中 includeas使用
- 扫描方式:
- 先做全量检索(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。