design-entity

design-entity

使用时机

• 仅被 design skill 显式调用

逻辑实体定义

• 逻辑实体是承载业务能力与数据职责的逻辑边界，用于将功能切分到可演进、可协作、可验证的模块单元。
• 逻辑实体应明确其责任边界（In scope / Out of scope）、关键职责（职责清单与非职责项）、协作关系（同层协作与跨层调用方向）以及关键状态与属性（与需求相关、可被验证）。
• 逻辑实体以目录为载体: 以“具有明确业务含义的叶子目录”为最小粒度进行映射；不将 include/、source/ 等通用/基础设施类目录视为逻辑实体（除非该目录本身承载明确业务语义且在需求/场景中可追溯）。

注意事项:

1. 以 FEATURE_DIR/spec.md 的功能列表为依据，识别支撑功能所需的逻辑实体，并为每个功能明确:

• 主责逻辑实体: 对功能结果负责（每个功能至少 1 个主责实体）
• 协作逻辑实体: 为主责实体提供数据/能力支持（可为 0..N）

1. 结合有效架构约束文档（见下「架构文档解析」），校验实体之间的调用方向是否合理，避免形成跨层反向依赖或循环依赖。

架构文档解析（与 design / design-interface 一致）

按以下顺序选用第一个存在的文件作为本次步骤的架构输入；均不存在则不阻塞，不将「缺少架构文件」视为失败，仅在产出中依赖 FEATURE_SPEC、context.md 与 IMPL_DESIGN 已有上下文自行给出分层假设并显式记录：

1. ${DOC_DIR}/on-demand/logic_architecture.md（按需反构，优先）
2. ${DOC_DIR}/specs/logic_architecture.md（规格库）

下文所称「有效架构约束文档」指按上式解析得到的文件；若未解析到任何文件，则称「未加载架构文档」。

指令

步骤1: 明确输入与上下文

• 功能: 读取 IMPL_DESIGN 中的「功能」章节，获得业务意图对应的功能内容。
• 架构约束: 按「架构文档解析」加载有效架构约束文档；若已加载，据此明确系统分层、跨层调用方向与允许的依赖边界；若未加载，基于 FEATURE_SPEC 与 context.md 做出合理分层假设并在 IMPL_DESIGN 中写明，仍须避免明显跨层反向依赖。
• 上下文文件: 优先读取 FEATURE_DIR/context.md 中的「相关逻辑实体文档」章节，作为既有逻辑实体的主要参考来源。
• on-demand 上下文（可选优先）:
  • 若 context_mode = evidence_first，优先消费 on_demand.scope、on_demand.traceability、on_demand.risks、on_demand.evidence_gaps，并以 in-scope 功能为实体识别起点。

步骤2: 分析逻辑实体

基于步骤1输入与上下文，按「逻辑实体定义」识别并产出本次变更涉及的全部逻辑实体条目（含INSERT/MODIFY/DELETE/REFER），作为后续步骤的范围基线。

动作类型定义:

• MODIFY: 业务意图要求调整既有逻辑实体的职责、结构或关键属性时。优先基于 FEATURE_DIR/context.md 指向的既有逻辑实体文档进行修改。
• INSERT:
  • 理解既有逻辑实体，无法合理承载新增职责或需要引入新的职责边界，且需要新增目录时，才增加逻辑实体。
  • 不存在既有逻辑实体时，则新增当前目录的逻辑实体。
• DELETE: 仅在删除具有明确业务必要性且风险可控时允许；必须提供充分理由与影响分析（含依赖方与数据迁移/兼容策略）。
• REFER: 既有逻辑实体已充分覆盖当前业务意图，无需对实体内容作任何修改，但需建立引用关系以支持后续波及分析。

on-demand 实体消费规则（仅 evidence_first 模式）：

• 先以 on_demand.scope 中 in-scope 功能倒推主责/协作实体，限制实体分析范围。
• 利用 on_demand.traceability 保证“需求-功能-接口-实体”链路可追溯，避免孤立实体。
• 对 on_demand.risks / on_demand.evidence_gaps，在实体边界或数据模型中显式记录假设与约束。
• 未在 in-scope 功能链路中且无证据支撑的新增实体，默认不纳入主设计范围。