105 lines
3.7 KiB
Markdown
105 lines
3.7 KiB
Markdown
# model_boundary_rules
|
||
|
||
更新时间: 2026-03-23
|
||
适用范围: app/model/**/*.js
|
||
目标: 约束 model 层仅承担数据映射与轻量领域行为,避免业务编排回流到模型层。
|
||
|
||
## 1. 当前盘点结果(阶段 5.3)
|
||
|
||
- hooks:
|
||
- app/model/entry_items.js
|
||
- EntryItems.beforeSave
|
||
- EntryItems.beforeUpdate
|
||
- scopes:
|
||
- app/model/print_item.js
|
||
- tableFields
|
||
- groupFields
|
||
- active
|
||
- byBusiness
|
||
- byPlatform
|
||
- virtual fields:
|
||
- 当前未检出 DataTypes.VIRTUAL / VIRTUAL 字段定义。
|
||
|
||
结论:
|
||
- 目前模型层 hooks/scopes 使用量较低,适合在当前阶段一次性固化边界规则。
|
||
|
||
## 2. 模型层职责边界
|
||
|
||
模型层允许:
|
||
- 表结构映射(字段、索引、注释、主键、表名映射)。
|
||
- 关联定义(belongsTo/hasMany/hasOne/belongsToMany)与关联语义辅助。
|
||
- 轻量实例行为(如 isEnabled/isExpired/getProgress 等纯实例判断)。
|
||
- 与单行数据一致性相关的同步校验(例如数量非负、上下限关系)。
|
||
|
||
模型层禁止:
|
||
- 跨表业务编排(批量流转、聚合统计、分配策略、权限树组装)。
|
||
- 事务边界控制(begin/commit/rollback)与重试策略。
|
||
- 外部副作用(调用第三方接口、写 Redis、发消息、发通知)。
|
||
- 依赖请求上下文(ctx、当前登录人、租户动态鉴权)。
|
||
|
||
## 3. Hooks 规则
|
||
|
||
允许场景:
|
||
- 单行数据写入前的确定性校验。
|
||
- 无 I/O 的轻量数据规整(例如 trim、默认值兜底)。
|
||
|
||
禁止场景:
|
||
- hook 中查询其他 model 决定业务分支。
|
||
- hook 中进行跨记录批处理或库存/权限编排。
|
||
- hook 中访问 service、http、cache、mq。
|
||
|
||
实现要求:
|
||
- 必须保持幂等与可重复执行安全。
|
||
- 必须是低成本逻辑,避免在热路径引入重查询。
|
||
- 错误信息聚焦数据约束,不承载业务流程语义。
|
||
|
||
## 4. Scopes 规则
|
||
|
||
允许场景:
|
||
- 静态筛选片段复用(状态、业务类型、平台等)。
|
||
- 参数化但纯查询片段的 where 条件构造。
|
||
|
||
禁止场景:
|
||
- 将权限判断或业务流程分支下沉到 scope。
|
||
- 在 scope 中拼装复杂 include 链并耦合排序/分页策略。
|
||
- 在 scope 中引入时间窗口策略或上下文依赖(如当前用户、当前 project)。
|
||
|
||
实现要求:
|
||
- scope 输出应稳定、可预期、可独立单测。
|
||
- 命名必须体现过滤语义,不使用模糊命名。
|
||
|
||
## 5. Virtual Fields 规则
|
||
|
||
允许场景:
|
||
- 展示层只读衍生值(字段拼接、标签映射、轻量格式化)。
|
||
|
||
禁止场景:
|
||
- virtual getter 内进行数据库查询或异步调用。
|
||
- 承载鉴权、状态流转或可写业务语义。
|
||
|
||
实现要求:
|
||
- 明确只读语义,不作为持久化字段参与写入。
|
||
- 若需要跨表推导,改由 service 返回 DTO 字段。
|
||
|
||
## 6. 现有代码归属说明
|
||
|
||
- app/model/entry_items.js hooks 保留原因:
|
||
- 仅执行已收货数量与计划数量的单行一致性校验。
|
||
- 未引入跨表查询、事务或副作用,符合模型边界。
|
||
|
||
- app/model/print_item.js scopes 保留原因:
|
||
- 仅复用静态筛选条件,不承载业务编排。
|
||
- 范围清晰,可作为查询片段复用。
|
||
|
||
## 7. 变更准入清单(新增/修改 model 时必须检查)
|
||
|
||
- 是否引入了跨表编排逻辑?若是,必须移至 app/service/systems/*。
|
||
- 是否引入了事务控制?若是,必须移至 service。
|
||
- 是否新增 hook 且包含 I/O?若是,不允许合入。
|
||
- 是否新增 scope 且耦合业务流程/鉴权?若是,不允许合入。
|
||
- 是否新增 virtual 并依赖查询/异步?若是,不允许合入。
|
||
|
||
## 8. 与阶段计划的映射
|
||
|
||
- 阶段 5.3: 已完成(盘点 + 规则固化)。
|
||
- 阶段 5.4: 基于本文件持续执行审查,作为后续模型改动的门禁依据。 |