portal-mini-go/.codebuddy/rules/api-doc-sync.md

description, globs, alwaysApply

description	globs	alwaysApply
在 internal/handler 下新增或修改 HTTP 接口后，询问用户是否需要同步更新 .codebuddy/docs 中对应的接口文档（不强制，由用户决定）。适用于所有 gin 路由接口的开发与变更。	internal/handler/**/*.go	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 的约定撰写，并保证示例与代码行为一致。