---
description: 在 internal/handler 下新增或修改 HTTP 接口后，询问用户是否需要同步更新 .codebuddy/docs 中对应的接口文档（不强制，由用户决定）。适用于所有 gin 路由接口的开发与变更。
globs: "internal/handler/**/*.go"
alwaysApply: false
---

# 接口文档同步提示（非强制）

每次在 `internal/handler/` 下**新增或修改** HTTP 接口（gin 路由，如 `r.GET` / `r.POST` / `r.PUT` / `r.DELETE` 及对应的 handler 方法）后，**询问用户是否需要**同步更新 `.codebuddy/docs` 下对应的接口文档。是否补充由用户决定，不强制。

## 1. 文档归属

根据接口挂载的路由前缀判断归属，写入对应文件：

| 接口归属 | 路由前缀特征 | 文档文件 |
| --- | --- | --- |
| 后台管理接口 | `/api/admin` | `.codebuddy/docs/admin-api.md` |
| 小程序端接口 | 小程序相关（如 `/api/miniapp`） | `.codebuddy/docs/miniapp-api.md` |
| 新增独立模块 | 既不在 admin 也不在 miniapp | 在 `.codebuddy/docs/` 下新建 `<module>-api.md`，并在本规则 §1 登记 |

> 归属以路由注册时挂载的 group 前缀为准，而非文件名。

## 2. 若用户同意补充，需包含的内容

每个接口在文档中至少包含：

- **名称与简介**：一句话说明用途。
- **请求**：方法 + 完整路径、是否需要鉴权、相关请求头（如 `Authorization`）。
- **请求参数**：
  - 路径参数 / 查询参数 / Body 字段，用表格列出：字段名、类型、是否必填、校验规则（`binding` tag，如 `required`、`max=32`）、说明。
  - 复杂结构给出 JSON 示例。
- **响应**：
  - 成功响应结构与字段说明（字段名、类型、含义）及示例 JSON。
  - 关键业务错误码（非 `0` 的 `code`）及其含义。
- **示例**：至少一个成功调用示例（`curl` 或 JSON）。

## 3. 文档格式约定

- 对齐 `.codebuddy/docs` 已有文件的风格：参数/响应用 Markdown 表格描述，示例用 ```` ```json ```` / ```` ```bash ```` 代码块。
- 文档应可独立阅读，前端/测试无需看代码即可对接。
- 描述用中文；字段名、路径、代码保持英文原样。

## 4. 变更同步（仅当用户选择维护文档时）

- 若用户选择维护文档，接口**删除 / 重命名 / 改路径 / 改参数 / 改响应结构**时，同步更新文档对应段落。
- 不得遗留过期、错误的接口描述（仅在维护该文档的前提下）。

## 5. 提示时机与方式

- 完成接口代码后，主动询问用户："是否需要更新接口文档？（admin-api.md / miniapp-api.md）"
- 用户确认后才执行文档更新；用户拒绝或忽略则跳过，不强制。
- 若接口改动较大（删除 / 重命名 / 改路径 / 改参 / 改响应），仍只提示，不强制执行。
- 用户同意补充时，参照 §2、§3 的约定撰写，并保证示例与代码行为一致。