WMS_MAIN/temp/docs/rename_impact_report.md

7.3 KiB
Raw Blame History

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 验证时必须覆盖平台激活、仓库角色分配、动态订单分表、打印链路四类高风险场景。