> For the complete documentation index, see [llms.txt](https://cc-code.rongyeliu.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cc-code.rongyeliu.com/templates/api.md).

# 接口契约 (api.md)

> **L3 实现层** · 由 \[Architect] 角色维护 · Dev 必读禁写 · QA 必读（入参出参是黑盒行为，不算实现细节）。 📐 **写什么**：每个接口的 method / path / 入参 / 出参 / 错误码 / 鉴权。 🚫 **不写什么**：业务规则（→ `prd.md`）、字段与 DB 列对齐（→ `data.md`）、目录与选型（→ `project.md`）、验收断言（→ `prd.md` §1.5，跨层重复必漂移）。

### ⛔ 写入纪律（active = 最新 + 最完整 + 最纯净）

| 纪律          | 说明                                                                                                 |
| ----------- | -------------------------------------------------------------------------------------------------- |
| **就地收敛**    | 接口变更**直接改写该 path 的小节**，⛔ 禁新开 `## 增量 F-n` 章节。同一个 path 在本文件永远只有一段当前契约 —— 散成 N 段补丁，Dev 得脑内拼接才知道现在长什么样 |
| **过程外置**    | 契约漂移登记 / 裁决过程 / 实测前置约束 → `docs/plans/F-n-<需求名>.md`；本文件只留「接口现在长什么样」                                 |
| **不跨层重复**   | 验收断言只在 `prd.md` §1.5，本文件⛔不复制                                                                       |
| **台账留痕**    | 每次增量在文末「变更台账」追加一行                                                                                  |
| **历史靠 git** | 旧版本不在本文件留存，`git log -p` 即完整历史                                                                      |

## 契约与实况的关系

```
Architect 先定契约（应然） ──► Dev 按契约实现 ──► 用 codegraph 校准回填状态标记
                                                    │
                              ⚠️ 偏离 = 代码与契约不符, 必须二选一:
                                  改代码回归契约  或  Architect 显式修契约
                              绝不允许沉默偏离
```

**状态标记**：`⬜ 未实现` / `🟡 实现中` / `✅ 已实现且一致` / `⚠️ 已实现但偏离契约`

***

## 一、全局约定

> 所有接口共用的规则写在这里，各接口段不再重复。

| 项        | 约定                                               |
| -------- | ------------------------------------------------ |
| Base URL | \[待填写]                                           |
| 鉴权方式     | \[待填写]（Cookie session / Bearer / API Key）        |
| 响应包装     | \[待填写]（裸数据 / `{data,error}` / `{code,msg,data}`） |
| 错误响应结构   | \[待填写]                                           |
| 错误码风格    | \[待填写]（大写下划线 / 小写连字符 / 数字）                       |
| 分页协议     | \[待填写]（page+size / cursor；参数名与响应字段名）             |
| 排序协议     | \[待填写]                                           |
| 时间格式     | \[待填写]（ISO 8601 / 时间戳）                           |
| 幂等要求     | \[待填写]（哪些接口必须幂等，用什么键）                            |
| 限流       | \[待填写]                                           |

### 1.1 全局错误码

| HTTP | 错误码    | 含义      |
| ---- | ------ | ------- |
| 400  | \[待填写] | 参数校验失败  |
| 401  | \[待填写] | 未登录     |
| 403  | \[待填写] | 已登录但无权限 |
| 404  | \[待填写] | 资源不存在   |
| 409  | \[待填写] | 状态冲突    |
| 429  | \[待填写] | 触发限流    |
| 500  | \[待填写] | 服务端异常   |

***

## 二、模块：\[模块名称]

> 对应 `prd.md` 的模块 `M[n]`。

### 2.1 `[METHOD] /api/[path]`

| 项    | 值                                   |
| ---- | ----------------------------------- |
| 用途   | \[待填写]                              |
| 鉴权   | \[待填写]（公开 / 需登录 / 需特定角色）            |
| 对应断言 | `prd.md` A\[n]                      |
| 状态   | ⬜ 未实现                               |
| 实现位置 | `[待填写 file:line]`（由 codegraph 校准回填） |

**请求参数**

| 参数     | 位置                           | 类型 | 必填    | 校验规则 | 说明 |
| ------ | ---------------------------- | -- | ----- | ---- | -- |
| \[待填写] | query / path / body / header |    | ✅ / ⬜ |      |    |

**成功响应**（`200`）

| 字段     | 类型 | 可空 | 说明 |
| ------ | -- | -- | -- |
| \[待填写] |    |    |    |

**错误响应**

| HTTP   | 错误码 | 触发条件 |
| ------ | --- | ---- |
| \[待填写] |     |      |

**副作用**

> 写库 / 发消息 / 扣费 / 调外部服务 —— 有副作用必须列明，QA 据此判断能否在共享环境测试。

* \[待填写]

***

### 2.2 `[METHOD] /api/[path]`

（复制 2.1 结构）

***

## 三、契约覆盖总表

> 一眼看清哪些接口还没实现、哪些偏离了契约。

| 模块     | 接口数 | ⬜ 未实现 | 🟡 实现中 | ✅ 一致 | ⚠️ 偏离 |
| ------ | --- | ----- | ------ | ---- | ----- |
| \[待填写] | 0   | 0     | 0      | 0    | 0     |

***

## 附录、变更台账

> 每次增量落盘在此追加**一行**，正文永远只有当前态。 详情列指向 `docs/plans/F-n-<需求名>.md`（需求清单 / 裁决过程 / 迁移清单都在那里，不进本文件）。

| F 号    | 日期            | 改了什么（一句） | 冲突裁决             | 详情                    |
| ------ | ------------- | -------- | ---------------- | --------------------- |
| \[F-1] | \[YYYY-MM-DD] | \[待填写]   | \[覆盖 X / 共存 / 无] | `docs/plans/F-1-*.md` |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cc-code.rongyeliu.com/templates/api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.