# 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 修复必须与关联关系校验一起推进。 - 数据库表名不在本阶段统一修改范围内。