---
name: openspec-api-contract
description: OpenSpec API 契约规范。创建涉及接口的 OpenSpec 提案时使用。探索阶段提供业务与契约引导清单，提案文档要求 API 契约设计、错误码与完成标准等必填章节。
---

# OpenSpec API 契约规范

**适用场景**：创建涉及 API/接口的 OpenSpec 提案时，探索和提案两个阶段均须遵守本规范。

---

## 一、探索阶段引导清单

在 `openspec-explore` 阶段，当内容涉及接口时，讨论必须覆盖以下所有维度。

### 业务与契约确认

**输入与输出**
- 请求方是谁？用户类型（SuperAdmin/Platform/Agent/Enterprise/Personal）？
- 输入参数：必填/选填字段、格式约束、参数来源（路径/查询/Body）？
- 输出结构：哪些字段必须返回？是否需要分页？

**业务规则**
- 核心业务规则与边界条件？
- 是否涉及状态流转？状态机的完整定义？
- 依赖外部服务时，外部异常的降级行为？

**权限与资源所有权**
- 哪些用户类型可以访问？
- 是否涉及跨用户/跨店铺/跨企业的资源访问？（需三层越权防护）
- 资源所有权校验方式：`CanManageShop` / `CanManageEnterprise` / 自有资源？

**幂等性**
- 操作类型：查询（天然幂等）/ 创建 / 更新 / 删除？
- 写操作幂等策略：状态条件更新 / Redis 业务键防重 + 分布式锁 / 乐观锁（version）？
- 异步任务是否需要任务锁？

**数据模型变更**
- 是否需要新建表、修改现有表或数据回填？
- 迁移策略：上线顺序、兼容旧数据的方式？
- 是否影响 GORM Callback 自动数据权限过滤？

**错误码与异常语义**
- 预期错误场景及对应错误码？
- 错误响应是否泄露敏感信息？（参数校验失败统一返回 `CodeInvalidParam`）

---

## 二、提案文档必填章节

在 `openspec-propose` 生成的提案（`proposal.md` / `design.md`）中，涉及接口时以下内容**不可缺失**。

### API 契约设计

**接口定义**

| 项 | 内容 |
|---|---|
| Endpoint | `METHOD /api/{scope}/{resource}[/:id]` |
| 请求参数 | 字段名、类型、必填/选填、说明 |
| 响应结构 | `data` 字段的完整结构定义 |
| 鉴权要求 | 允许的用户类型 |
| 资源所有权 | 所有权校验方式 |

**列表接口额外要求**
- 分页：`page` + `page_size`（默认 20，最大 100）
- 排序：默认排序字段与方向
- 过滤：支持的过滤条件列表

**错误码清单**

| 场景 | 错误码 | 说明 |
|---|---|---|
| 参数校验失败 | `CodeInvalidParam` | 统一返回，不泄露细节 |
| 资源不存在/越权 | `CodeForbidden` | 不区分两者，防止信息泄露 |
| （业务错误场景...） | （对应错误码） | （说明） |

### 完成标准

**最小验证步骤**（按顺序列出可操作的验证步骤）

1. （例：调用创建接口，验证返回 `code=0`）
2. （例：查询接口确认数据存在且字段正确）
3. （例：PostgreSQL MCP 查询确认数据库记录符合预期）

**影响范围说明**
- 新增/修改的表：
- 影响的现有接口：
- 影响的权限与数据过滤范围：

---

## 约束（必须遵守）

- **优先复用现有架构与库**：不引入新依赖，错误码优先复用已有定义
- **不做顺手重构**：提案范围严格限定在目标功能；发现可优化点，记录到 backlog 但不执行
- **数据库设计**：禁止外键约束，禁止 GORM 关联标签，关联通过 ID 字段手动维护