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

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