WMS_MAIN/temp/docs/model_naming_standard.md

5.9 KiB
Raw Blame History

Model 命名规范

更新时间: 2026-03-22 适用范围: app/model、app/service、app/controller 中的 app.model / ctx.model 调用

1. 目标

  • 统一 model 文件名、运行时 key、defineName、tableName、关联 alias 的命名规则。
  • 将“可直接收敛的风格问题”和“会影响业务语义的结构问题”拆开处理。
  • 为阶段 4 的关联规范化和阶段 5 的模型能力清理提供稳定基线。

2. 五层命名对象

当前仓库里,单个模型至少同时存在以下 5 个命名层:

  1. 文件名: app/model 下的文件名。
  2. 运行时 key: 代码里通过 app.model.Xxx / ctx.model.Xxx 使用的名称。
  3. defineName: Sequelize 的 app.model.define(name, attributes, options) 第一个参数。
  4. tableName: options.tableName,对应数据库真实对象名。
  5. alias: 关联查询里的 as 字段。

后续规范要求这 5 层职责分离,不再互相混用。

3. 统一规则

3.1 文件名

  • 一律使用 snake_case。
  • 文件名表达“模型职责”,不表达数据库前缀。
  • 工厂模型必须以 _factory 结尾。
  • 除非是稳定历史兼容项,否则不在文件名中保留 wms 前缀。

示例:

  • account_store_employee.js
  • platform_setting.js
  • order_delivery_factory.js

3.2 运行时 key

  • 一律使用 PascalCase。
  • 运行时 key 由文件名去掉扩展名后转为 PascalCase。
  • 这是 service/controller/model 之间的主兼容面,优先级高于 defineName。
  • 工厂模型保留 Factory 后缀。

示例:

  • account_store_employee.js -> AccountStoreEmployee
  • platform_setting.js -> PlatformSetting
  • order_delivery_factory.js -> OrderDeliveryFactory

3.3 defineName

  • 静态模型的 defineName 必须与运行时 key 保持一致。
  • 不再使用 snake_case、wms_ 前缀或局部 lowerCamelCase 作为 defineName。
  • 动态分表模型允许在运行时使用真实 tableName 作为 defineName,但外部只允许通过工厂 key 获取,不直接在业务层引用动态 defineName。

示例:

  • PlatformSetting: 正确
  • platform_setting: 不再推荐
  • prohibitedType: 不再推荐
  • wms_account_store_employee: 不再推荐

3.4 tableName

  • tableName 只负责映射数据库真实对象。
  • 一律保持数据库现状,不因 model 命名规范化而强制修改表名。
  • 物理表继续保留现有 wms_ 前缀、复数形式、历史拼写问题。
  • 视图、动态分表、历史表单独记录,不纳入静态命名统一的修改范围。

示例:

  • PlatformSetting -> tableName: wms_platfrom_setting
  • StockBarcode -> tableName: wms_stock_barcodes
  • PrintStations -> tableName: wms_print_stations

说明:

  • tableName 中的历史拼写错误属于数据库治理问题,不属于本阶段命名规范化问题。

3.5 alias

  • belongsTo / hasOne 使用 lowerCamelCase 单数。
  • hasMany / belongsToMany 使用 lowerCamelCase 复数。
  • alias 反映关联语义,不复用旧表名或旧模型名。
  • alias 必须与真实关系一致,不能把 employee 关系继续命名为 role。

示例:

  • belongsTo(Store, { as: 'store' })
  • hasMany(EmployeeRole, { as: 'employeeRoles' })
  • belongsTo(AccountStoreEmployee, { as: 'accountStoreEmployee' })

4. 兼容优先级

按风险从高到低分三类处理:

A 类: 运行时 key 不存在或调用错误

  • 必须先修。
  • 这类问题会直接导致运行时取不到模型,或拿到错误关联。
  • 典型例子:
    • AccountStoreRole
    • WmsOrderDeliveryFactory
    • WmsOrderItemsFactory

B 类: defineName 不规范但运行时可用

  • 可分批修。
  • 前提是 tableName 已显式声明,且不存在依赖 defineName 字符串的外部逻辑。
  • 典型例子:
    • platform_setting
    • qimen_app
    • qimen_log
    • prohibitedType
    • stock_barcodes

C 类: alias 与业务语义不一致

  • 必须与阶段 4 一起处理。
  • 不能只改 alias 文本,需要一起核对外键、include、返回结构。
  • 典型例子:
    • accountStoreRoles
    • accountStoreRole
    • employeeRole

5. 仓库内落地规则

5.1 本项目允许保留的历史兼容项

以下项目前阶段不因“风格统一”而强制改文件名:

  • print_stations.js
    • 原因: 运行时大量使用 PrintStations,且 tableName 为 wms_print_stations。
  • store_join.js
    • 原因: 运行时与 defineName 已一致,当前主要问题不在命名层。
  • order_delivery_factory.js / order_items_factory.js
    • 原因: 工厂职责明确,外部兼容面稳定。

5.2 本项目必须执行的统一动作

  • 所有静态模型的 defineName 逐步收敛到 PascalCase 运行时 key。
  • 所有业务代码统一通过 ctx.model.Xxx / app.model.Xxx 的 PascalCase key 调用。
  • 任何 include/as 字段都必须与当前模型关联定义一致。
  • 不再新增任何带 wms 前缀的 defineName。
  • 不再新增任何与真实语义不一致的 alias。

6. 参考示例

6.1 标准静态模型

  • 文件名: platform_setting.js
  • 运行时 key: PlatformSetting
  • defineName: PlatformSetting
  • tableName: wms_platfrom_setting

6.2 标准关联模型

  • 文件名: account_store_employee.js
  • 运行时 key: AccountStoreEmployee
  • defineName: AccountStoreEmployee
  • tableName: wms_account_store_employee
  • alias:
    • belongsTo(Account, { as: 'account' })
    • belongsTo(Store, { as: 'store' })
    • hasMany(EmployeeRole, { as: 'employeeRoles' })

6.3 标准工厂模型

  • 文件名: order_delivery_factory.js
  • 运行时 key: OrderDeliveryFactory
  • 对外入口:
    • ctx.model.OrderDeliveryFactory.getCurrentModel(warehouseId)
    • ctx.model.OrderDeliveryFactory.getHistoryModel(warehouseId)
  • 约束:
    • 业务代码不直接引用动态表 defineName。

7. 执行边界

  • 本阶段先统一标准、映射和影响面,不直接大规模改名。
  • 运行时 key 修复优先于 defineName 收敛。
  • alias 修复必须与关联关系校验一起推进。
  • 数据库表名不在本阶段统一修改范围内。