WMS_MAIN/temp/docs/model_boundary_rules.md

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