---
name: soloforge-api-spec
description: 生成可供实现、客户端和自动化工具共同消费的 API 文档与 OpenAPI 契约。
when: API 设计 / api_spec / scope.api
---

# API 规格

## 适用性

任务新增或改变外部/跨模块接口时使用。若状态机、权限、数据来源或消费方未确定，先解决上游决策；内部纯实现细节不应伪装成公共 API。

## 事实输入

- 需求场景、调用方、权限模型、状态机、幂等和并发语义。
- 真实持久化属性或其他数据来源、现有接口兼容约束和版本策略。
- 错误处理、限流、分页、审计和隐私要求。
- `template.md` 和 `examples.md`。

## 关键决策

- 资源边界、方法与路径、同步/异步方式、幂等键和一致性承诺。
- 请求、响应、错误码和 HTTP 状态必须一义；枚举与当前数据源或领域约束保持一致。
- breaking change 必须有版本、兼容期和迁移计划。
- **Tag 分组**：按业务域聚合（如「订单/支付/对账」），禁按技术层分（「CRUD」「管理后台」）；同一 path 的不同 method 按触发方归属不同 tag（如 `POST /bills` 归计费流程、`GET /bills` 归查询）；外部回调/webhook 归所属业务 tag，但须 `security: []` 且幂等重复返 2xx。

## 产出方法

1. 同步维护人读文档与 `openapi.yaml`，二者表达同一契约。
2. 默认路径为 `docs/design/02-API接口规格文档.md` 和 `docs/api/openapi.yaml`；有 project map override 时使用解析后的权威路径。
3. 每个 endpoint 写消费方、来源需求、权限、请求、响应、错误、副作用、验收场景和数据映射。
4. 对资源型接口明确状态机或 CRUD 范围，不按惯例补齐不需要的操作。
5. 使用锁定配置的 OpenAPI lint，并修复结构或引用错误。
6. 维护顶级 `tags:` 声明，每个 tag 带 description 枚举覆盖的子能力；每个 endpoint operation 标 `tags` 且与 `x-soloforge-endpoint-id` 所属业务域对齐；资金/对账等行业分组按适用条件组织（见 `examples.md`）。

## 禁止项

- 不得虚构数据字段、消费方、业务码或已实现行为。
- 不得只写成功响应，省略权限、校验、冲突、限流和下游失败。
- 不得让同一业务码在不同接口表达不同含义或 HTTP 状态。
- 不得用文档说明覆盖 `openapi.yaml` 的缺失或不一致。

## 交付自检

- 文档与 OpenAPI 的路径、方法、字段、必填性、枚举和错误一致。
- 每个持久化字段映射到当前存储的真实数据来源（如表字段、文档属性、键、对象元数据或事件字段），非持久化字段说明派生或外部来源。
- 幂等、分页上限、权限和副作用可验证。
- 所有 `N/A` 均有理由，未确认项没有伪装成最终契约。

## 权威验证

编辑后先处理 quick 反馈，再调用 `sf_verify action="full" task_id="当前任务ID" artifact="api_spec"`。完整验证通过后，代码与运行时响应仍必须按契约测试。


## 交付前对抗审查

`sf_verify` 通过只证明结构/编译/测试层；语义质量（承接正确性、异常/并发/权限/边界是否可靠、是否含空话或无法证伪的承诺）须经独立对抗审查。advance/deliver 前用 `sf_review action="start" task_id="当前任务ID" artifact="<本产物 kind>"` 发起 per_artifact 审查，用**独立 session/subagent**（非产出本产物的同一会话）执行返回的 prompt、submit findings，按 next_step 完成 K 次独立采样与闭环。deliver 会阻断未完成/未闭环的审查；活跃豁免与被驳回 error 会被注入审查 focus 供独立复核。