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