WMS_MAIN/rename_impact_report.md
2026-03-23 17:10:07 +08:00

168 lines
7.3 KiB
Markdown
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 命名影响评估报告
更新时间: 2026-03-22
范围:
- app/model/*.js
- app/service/**/*.js
- app/controller/**/*.js
## 1. 结论摘要
当前命名问题分成两层:
1. 真正会影响运行的调用错误。
2. 还能运行,但会持续制造理解成本和后续重构风险的 defineName/alias 漂移。
本轮确认的最高优先级风险有 3 个:
### 1.1 AccountStoreRole 是仓库内不存在的运行时 key
- 代码大量使用 ctx.model.AccountStoreRole。
- app/model 下没有对应的 account_store_role.js。
- 现有 schema 已落到 AccountStoreEmployee + EmployeeRole 两层关系。
- 这不是单纯命名风格问题,而是“旧关系名残留到新模型结构”的兼容断层。
### 1.2 动态分表工厂存在一组错误调用名
- 仓库主流调用是 OrderDeliveryFactory / OrderItemsFactory。
- 仅 app/service/apiMethods/test.js 仍在使用 WmsOrderDeliveryFactory / WmsOrderItemsFactory。
- 这会导致测试/调试路径与正式业务路径使用不同的模型入口。
### 1.3 alias 已经切到 employee 语义,但 service 仍按 role 语义取值
- app/model/account_platform_active.js 中 alias 是 accountStoreEmployee。
- 但 app/service/systems/account_platform.js 仍按 accountStoreRole 进行 include 和结果读取。
- 这说明 model 层与 service 层对同一关系的语义认知已经分叉。
## 2. 关键证据
### 2.1 不存在的 model key: AccountStoreRole
受影响位置:
- app/service/systems/account_platform.js:21
- app/service/systems/account_platform.js:102
- app/service/systems/account_platform.js:169
- app/service/systems/account_platform.js:226
- app/service/systems/account_platform.js:321
- app/service/systems/store.js:464
- app/service/systems/store.js:679
- app/service/systems/store.js:690
- app/model/role.js:151
现状说明:
- app/model/account_store_employee.js:6 定义的是 AccountStoreEmployee,表为 wms_account_store_employee。
- app/model/account_store_employee.js:82-99 说明当前关系是 AccountStoreEmployee -> EmployeeRole -> Role。
- app/model/account_platform_active.js:79-86 已把激活关系关联到 AccountStoreEmployee。
风险判断:
- 如果继续沿用 AccountStoreRole,后续关联收敛会同时破坏 include、字段读取、缓存结构与返回结构。
- 该问题必须在正式改 defineName 之前先做数据关系确认。
建议动作:
1. 先确认“平台激活”想绑定的是员工记录还是员工-角色明细。
2. 若绑定员工记录,则将 AccountStoreRole 全量替换为 AccountStoreEmployee,并改造 role 读取路径。
3. 若绑定员工-角色明细,则需要新增独立模型,而不是继续使用幽灵 key。
### 2.2 动态工厂 key 调用漂移
正常调用样本:
- app/service/systemMethods/order.js:22-23
- app/service/systems/delivery_order.js:14
- app/service/systems/delivery_order.js:311
- app/service/qimenMethods/deliveryorder.js:7-8
异常调用样本:
- app/service/apiMethods/test.js:50
- app/service/apiMethods/test.js:51
风险判断:
- 正式链路与调试链路的 model 入口不一致,后续如果只修主链路,测试链路会继续漂移。
- 这是低成本高收益修复项,应优先纳入第一批代码修正。
建议动作:
1. 将 WmsOrderDeliveryFactory 改为 OrderDeliveryFactory。
2. 将 WmsOrderItemsFactory 改为 OrderItemsFactory。
3. 回归验证动态表 current/history 获取能力是否一致。
### 2.3 alias 与语义漂移
证据位置:
- app/model/account.js:139 使用 alias accountStoreRoles,但实际模型是 AccountStoreEmployee。
- app/model/account_platform_active.js:84 使用 alias accountStoreEmployee。
- app/model/account_store_employee.js:95 使用 hasMany(EmployeeRole, { as: 'employeeRole' })。
- app/model/role.js:171 使用 hasMany(EmployeeRole, { as: 'employeeRole' })。
- app/service/systems/account_platform.js:102-136 仍按 accountStoreRole 读取嵌套字段。
风险判断:
- 当前 alias 命名混合了“员工关系”和“角色关系”两种语义。
- 若不先统一语义,后续只做名字替换会把问题从命名层转移到数据层。
建议动作:
1. 阶段 4 先梳理 employee、role、store 三者的真实关系。
2. hasMany alias 收敛为复数形式,如 employeeRoles、accountStoreEmployees。
3. service 层返回结构与 include 路径同步改名,避免只改 model 不改消费方。
## 3. defineName 漂移影响
以下问题当前通常不会直接导致运行失败,但会持续造成阅读成本与重构误判:
| 文件 | 证据 | 当前情况 | 风险 |
| --- | --- | --- | --- |
| app/model/platform_setting.js | :7 | defineName 为 platform_setting,运行时 key 为 PlatformSetting | 阅读时容易误以为 key 与 defineName 同名 |
| app/model/qimen_app.js | :6 | defineName 为 qimen_app,运行时 key 为 QimenApp | service 调用与模型定义风格分裂 |
| app/model/qimen_log.js | :8 | defineName 为 qimen_log,运行时 key 为 QimenLog | 日志模型定位成本高 |
| app/model/account_store_employee.js | :6 | defineName 为 wms_account_store_employee,运行时 key 为 AccountStoreEmployee | 将表名语义混入模型名 |
| app/model/stock_barcode.js | :6 | defineName 为 stock_barcodes,运行时 key 为 StockBarcode | 单复数与 key 同时漂移 |
| app/model/prohibited_type.js | :6 | defineName 为 prohibitedType,运行时 key 为 ProhibitedType | lowerCamelCase 与 PascalCase 混用 |
| app/model/print_stations.js | :5 | defineName 为 print_stations,运行时 key 为 PrintStations | 虽可运行,但风格不统一 |
影响判断:
- 新增 include、调试 SQL、追踪关联时,很容易把 defineName、key、tableName 当成同一件事。
- 后续如果继续新增 snake_case defineName,会放大维护面。
建议动作:
1. 先完成 P0 调用修复。
2. 再按 model_rename_map.md 分批将 defineName 收敛到 PascalCase。
3. 每次改 defineName 后,回归关联加载与 SQL 日志输出,确认未引入隐式副作用。
## 4. 稳定项与例外项
以下命名虽然不完全理想,但当前不建议仅因风格而改动:
- app/model/print_record.js
- defineName 已为 PrintRecord,运行时 key 与之保持一致。
- app/model/store_join.js
- defineName 已为 StoreJoin,当前问题主要不在命名层。
- app/model/order_delivery_factory.js
- 工厂模型对外 key 稳定,重点是调用方统一。
- app/model/order_items_factory.js
- 工厂模型对外 key 稳定,重点是调用方统一。
- app/model/print_stations.js
- 文件名和表名均为复数,当前更适合先保留为历史兼容项,不单独改文件名。
## 5. 推荐执行顺序
1. 第一批: 修正不存在的运行时 key 和错误工厂调用名。
2. 第二批: 收敛静态模型 defineName,保持 tableName 不变。
3. 第三批: 在关联核对完成后统一 alias 和 include 路径。
4. 第四批: 更新测试、README、modelList.md、关联清单等文档。
## 6. 对后续阶段的输入
- 阶段 4 需要重点核对 AccountPlatformActive、AccountStoreEmployee、EmployeeRole、Role、Store 的外键与 include 结构。
- 阶段 5 需要顺带清理与命名漂移绑定的死代码、调试日志和旧语义变量名。
- 阶段 6 验证时必须覆盖平台激活、仓库角色分配、动态订单分表、打印链路四类高风险场景。