design-interface

design-interface

使用时机

• 仅被 design skill 显式调用

接口定义

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

注意事项:

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

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

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

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

架构文档解析（与 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 至少映射到一个错误处理或兼容说明条目。