design-entity

design-entity

使用时机

• 仅被 design skill 显式调用

逻辑实体定义

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

注意事项:

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

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

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

架构文档解析（与 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 功能链路中且无证据支撑的新增实体，默认不纳入主设计范围。

兼容规则（default 模式）：

• 若 context_mode = default 或 on_demand 字段缺失，沿用原有逻辑，不阻塞实体设计。

步骤3: 按照模板生成「逻辑实体」章节内容

## 逻辑实体

###  [动作类型:INSERT/MODIFY/DELETE/REFER] - [逻辑实体ID]([逻辑实体名称])

**变更原因**: [变更来源与采用的方法等]

**支撑的功能**: [功能ID] - [功能名称]

**映射目录**: [逻辑实体的映射目录]

[逻辑实体具体内容]

[按照上述格式继续描述其他实体...]

MODIFY

1. 从既有逻辑实体文档中准确提取对应条目的关键内容，填充到上述模板占位符。
2. 基于本次 业务意图 明确需要调整的职责、协作关系或关键属性。对新增或修改的部分使用 **加粗** 标记，对计划移除的内容使用 ~~删除线~~ 标记，以便评审与追踪。

INSERT

1. 生成逻辑实体ID:

• 读取 DOC_DIR/specs/logic_entities/0.logic_entity_list.md，提取已存在的 ENTITY-XXX 最大ID，取 最大ID + 1 作为新逻辑实体的ID。
• 不存在 0.logic_entity_list.md 时，逻辑实体ID从 ENTITY-001 开始。

2. 明确新实体的归属层次与对外协作关系；若已加载有效架构约束文档，须与其分层约束一致；若未加载，须在 IMPL_DESIGN 中显式记录分层依据。
3. 依据 .infra/metamodel/6.entity-template.md 中的规范生成[逻辑实体具体内容]。
4. 使用步骤 3 中的模板，将生成的逻辑实体内容整理为「逻辑实体」章节条目。

DELETE

1. 从既有逻辑实体文档中提取计划删除条目的关键信息，填充到模板占位符。
2. 给出充分且可追溯的删除理由，并补充影响分析（依赖方、数据迁移/兼容、回滚策略）。

REFER

从既有逻辑实体文档中提取对应条目的关键信息填入模板，变更原因 统一填写为 无变更，仅建立引用关系以支持后续波及分析。

步骤4: 将生成的「逻辑实体」章节内容追加到 IMPL_DESIGN 末尾

步骤5: 生成数据模型

输入:

• 步骤2/步骤3 的逻辑实体分析与条目输出结果

分析方法:

1. 从逻辑实体中识别其承载的核心数据结构，并明确:

• 数据结构名称、关键字段与实体间关系
• 来自需求/规则的验证约束（必填、格式、范围、唯一性等）
• 状态与状态转换（如适用）

2. 对每个数据结构输出:

• 定义（结构化表示即可，例如类型定义/字段列表；不限定具体编程语言）
• 关键字段（字段名、类型、语义描述）
• 验证规则（必填、格式、范围等，可追溯到需求/规则来源）
• 状态转换（如存在状态机，描述状态与转换条件）
• 代码映射（如已知/可推导: 文件路径、结构体/类名；未知可标注 [NEEDS CLARIFICATION]）

3. 描述数据结构之间的关系:

• 组合关系、引用关系、继承关系（如适用）等，并明确关系方向与约束（1:1、1:N、N:M）

输出位置:

• 生成文件: FEATURE_DIR/data-model.md
• 参考模板: .infra/templates/data-model-template.md

DoD（完成校验）

• 边界清晰: 每个逻辑实体均明确 In scope / Out of scope，避免职责重叠与边界漂移。
• 分层一致: 若已加载有效架构约束文档，实体归属层次与协作/调用方向须符合该文档；若未加载，须在 IMPL_DESIGN 中显式记录分层与调用假设，且无明显不合理的反向依赖或循环依赖。
• 功能可追溯: 每个实体与 FUNC-XXX 的主责/协作关系清晰可追溯，能解释其为何存在以及如何支撑场景验收。
• 变更规范: 实体条目按 INSERT/MODIFY/DELETE/REFER 规则完成更新，且加粗/删除线标记准确一致；DELETE 具备充分且可追溯的理由与影响分析。
• 数据模型可验证: FEATURE_DIR/data-model.md 覆盖核心数据结构、关键字段与验证规则，并与需求/规则来源具备可追溯关系；状态转换（如适用）描述可执行。
• ID一致: 新增逻辑实体的 ENTITY-XXX ID基于当前最大值顺序递增，无冲突或缺号。