165 lines
8.5 KiB
Markdown
165 lines
8.5 KiB
Markdown
# Association Validation Checklist
|
||
|
||
更新时间: 2026-03-23
|
||
范围: app/model/*.js + 核心系统 service 调用链
|
||
|
||
## 1. 核心检查项
|
||
|
||
- [x] AccountStoreRole 幽灵引用已移除(服务主链路)。
|
||
- [x] AccountStoreEmployee <-> EmployeeRole <-> Role 关系可用。
|
||
- [x] hasMany alias 复数化(employeeRoles/accountStoreEmployees)。
|
||
- [x] 重复兼容 alias 已清理(主链路)。
|
||
- [x] 对外接口输出一致(baseline/compare mismatch=0)。
|
||
- [x] 关键登录与用户信息链路测试通过。
|
||
|
||
## 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. 后续检查
|
||
|
||
- [x] 全量扫描其余模型类方法中的 include 别名一致性(service as 与 model as 差集扫描结果: 0)。
|
||
- [x] 补充 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。 |