design-interface

design-interface

使用时机

• 仅被 design skill 显式调用

接口定义

• 接口是“能力边界”的可执行表达: 将逻辑实体对外提供的能力与协作方式，抽象为可被调用、可被测试、可被版本化的契约（HTTP API、RPC、消息事件、SDK 函数等）。
• 接口契约应明确其能力语义（做什么/为何需要）、输入输出（参数、返回、错误）、调用场景（谁在何时调用）、处理流程（核心步骤与关键分支）以及代码映射（如可推导）。
• 接口分为两类:
  • 对外接口: 逻辑实体边界之外的调用方可直接调用（系统外部或内部其他模块）
  • 内部接口: 仅用于逻辑实体内部/实体间协作的实现细节，不应作为“直接对外能力”暴露

注意事项:

1. 以逻辑实体为单位收敛“能力清单”，将能力映射为接口候选，并为每个候选明确:

• 所属逻辑实体: ENTITY-XXX
• 接口类型: 对外接口 / 内部接口
• 调用方: 实体边界之外的调用者是谁（对外）或协作方是谁（内部）

2. 结合有效架构约束文档（见下「架构文档解析」）校验:

• 对外接口的暴露形式与所在层次是否合理（避免在低层泄露上层语义或形成反向依赖）
• 内部接口是否被错误地当作对外能力暴露（导致边界外泄）

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

按以下顺序选用第一个存在的文件作为本次步骤的架构输入；均不存在则不阻塞，不将「缺少架构文件」视为失败，依赖 FEATURE_SPEC、context.md 与 IMPL_DESIGN 已有分层描述进行接口层次校验，并在必要时在契约说明中显式记录假设：

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

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

指令

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

• 实体输入: 读取 IMPL_DESIGN 中的「逻辑实体」章节（特别是实体职责边界、协作关系、方法/能力说明）。
• 架构约束: 按「架构文档解析」加载有效架构约束文档；若已加载，据此明确系统分层、跨层调用方向与允许的依赖边界；若未加载，基于 IMPL_DESIGN / FEATURE_SPEC 中的分层假设校验接口暴露层次与调用方向。
• 上下文文件: 优先读取 FEATURE_DIR/context.md 中的「相关接口文档」章节，作为既有接口的主要参考来源。
• on-demand 上下文（可选优先）:
  • 若 context_mode = evidence_first，优先消费 on_demand.scope.interfaces、on_demand.traceability、on_demand.contract_deltas、on_demand.risks、on_demand.evidence_gaps。

步骤2: 分析接口与确定动作类型

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

动作类型定义:

• MODIFY: 业务意图要求调整既有接口的语义、参数/返回或行为约束时。优先基于 FEATURE_DIR/context.md 指向的既有接口文档进行修改。
• INSERT:
  • 理解既有接口，现有接口无法表达该能力边界或会导致语义混淆/职责过载时。
  • 不存在既有接口时，则需新增所需接口。
• DELETE: 除非删除具有明确业务必要性且风险可控，否则不删除；必须给出充分理由与影响分析（依赖方、兼容策略、回滚策略）。
• REFER: 既有接口已充分覆盖当前业务意图，无需对接口内容作任何修改，但需建立引用关系以支持后续波及分析。

on-demand 接口消费规则（仅 evidence_first 模式）：

• 以 on_demand.scope.interfaces 建立接口基线（白名单）。
• 以 on_demand.contract_deltas 作为契约变化的主输入：
  • request_added[] → 请求参数新增/约束
  • response_added[] / response_modified[] → 响应结构变化与兼容策略
• 通过 on_demand.traceability 校验每个接口是否有对应功能来源，避免“无来源接口”。
• 未在 scope 且无证据链支撑的接口不得进入主契约（防止边界外扩）。
• on_demand.risks / on_demand.evidence_gaps 至少映射到一个错误处理或兼容说明条目。

兼容规则（default 模式）：

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

步骤3: 按照模板生成「接口契约」内容

# 接口契约

## 对外接口

### [动作类型:INSERT/MODIFY/DELETE/REFER] - [接口ID] - [接口名称]

**变更原因**: [接口的变更描述]

**所属逻辑实体**: [逻辑实体ID] - [逻辑实体名称]

**调用方**: [谁调用/何时调用；INTERNAL需明确协作方]

[接口具体内容]

## 内部接口

### [接口名称]

**变更原因**: [接口的变更描述]

**调用方**: [谁调用/何时调用；INTERNAL需明确协作方]

[接口具体内容]

[按上述格式继续描述其他接口...]

MODIFY

1. 从既有接口文档中准确提取对应条目的关键信息，填充到上述模板占位符。
2. 基于本次 业务意图 明确需要调整的契约要素（语义、参数/返回、约束、错误、流程）。对新增或修改的部分使用 **加粗** 标记，对计划移除的内容使用 ~~删除线~~ 标记，以便评审与追踪。

INSERT

1. 生成接口ID:

• 读取 DOC_DIR/specs/interfaces/0.interface_list.md，提取已存在的 API-XXX 最大ID，并以 最大ID + 1 作为新接口ID。
• 不存在 0.interface_list.md 时，接口ID从 API-001 开始。

2. 明确接口类型（EXTERNAL/INTERNAL）与所属逻辑实体；若已加载有效架构约束文档，须与其分层约束一致；若未加载，与 IMPL_DESIGN 中已记录的分层假设一致并在契约中可追溯到该假设。
3. 依据 .infra/metamodel/7.interface-template.md 中的规范生成[接口具体内容]:
   • 参考 DOC_DIR/specs/interfaces/ 下既有文档的组织方式与粒度，使新接口在抽象层级上与既有接口保持一致。
4. 使用步骤 3 中的模板，将生成的接口内容整理为「接口契约」。

DELETE

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

REFER

从既有接口文档中提取对应条目的关键信息填入模板，变更原因 统一填写为 无变更，并补充可定位信息（文件路径/章节/锚点）；无需重复粘贴契约全文。

步骤4: 将生成的「接口契约」内容保存到 FEATURE_DIR/contracts/api-contract.md

DoD（完成校验）

• 能力边界清晰: 每个接口均能被追溯到对应 ENTITY-XXX 的对外能力或内部协作诉求，避免“接口语义漂移”或职责重叠。
• 分层一致: 若已加载有效架构约束文档，接口暴露层次与调用方向须符合该文档；若未加载，须与 IMPL_DESIGN 中显式分层假设一致，无明显不合理的反向依赖或循环依赖诱因。
• 变更规范: 接口条目按 INSERT/MODIFY/DELETE/REFER 规则完成更新，且加粗/删除线标记准确一致；DELETE 具备充分理由与影响分析。
• 契约可验证: 接口契约包含输入输出、约束与错误（如适用），并与需求/规则来源具备可追溯关系；处理流程描述可执行。
• ID一致: 新增接口的 API-XXX ID基于当前最大值顺序递增，无冲突或缺号。