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