WMS_MAIN/temp/docs/model_boundary_rules.md

3.7 KiB
Raw Blame History

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: 基于本文件持续执行审查,作为后续模型改动的门禁依据。