---
name: api-doc-maintainer
description: >
  当用户修改、新增或删除任何 API 接口时，同步更新 docs/api/ 下的 Markdown 文档。
  触发场景：修改 Controller、DTO、Service 中的接口逻辑或参数，新增/删除 endpoint，
  变更响应结构，添加错误码。只要涉及 src/modules/*/  下的接口代码改动，都应触发此技能。
---

# API 文档维护技能

## 为什么文档同步如此重要

MemeMind 的客户端是 Cocos Creator 小游戏，客户端开发者依赖 `docs/api/` 下的文档来接入后端接口。文档滞后意味着客户端开发者要去读源码才能对接，这会严重拖慢开发节奏。所以每次接口变更，文档必须同步更新。

## 代码结构索引

在更新文档前，先确认变更涉及哪些文件：

```
src/modules/
├── auth/           # 认证模块：wx-login、user assets、game-data
│   ├── auth.controller.ts
│   ├── dto/
│   └── auth.service.ts
├── wechat-game/    # 游戏模块：levels、configs
│   ├── wechat-game.controller.ts
│   ├── dto/
│   └── wechat-game.service.ts
└── share/          # 分享挑战模块：创建分享、加入、进度上报
    ├── share.controller.ts
    ├── dto/
    └── share.service.ts
```

Controller 定义了路由和参数，DTO 定义了请求/响应的数据结构，Service 包含业务逻辑。三者共同决定文档内容。

## 文档存放与组织

文档统一放在 `docs/api/` 目录下，按功能模块分文件：

| 模块 | 文档文件 | 对应代码 |
|------|----------|----------|
| 用户认证 | `auth-api.md` | `src/modules/auth/` |
| 游戏关卡 | `game-api.md` | `src/modules/wechat-game/` |
| 分享挑战 | `share-challenge-api.md` | `src/modules/share/` |
| 排行榜 | `leaderboard-api.md` | （预留） |

新增模块时，创建对应的文档文件并在 `docs/api/README.md` 中注册索引。

## 文档结构

每个模块的 API 文档包含以下章节：

```markdown
# 模块名称 API

## Changelog
- YYYY-MM-DD: 变更说明

## 概述
功能说明、前置依赖

## 认证方式
（如需要）说明鉴权方式

## 通用响应格式
（引用统一响应格式即可）

## 接口列表
### 1. 接口名称
（按下方模板）

## 错误码说明
| 错误码 | HTTP 状态码 | 说明 | 触发条件 |

## 接入流程
典型业务场景的调用顺序

## 客户端示例
Cocos Creator TypeScript 调用代码
```

## 接口文档模板

根据接口类型智能选择模板，不需要填写不适用的字段。

### 查询类接口（GET，无请求体）

```markdown
### N. 接口名称

**接口地址**：`GET /api/v1/{module}/{endpoint}`

**是否需要认证**：是/否

**路径参数**（如有）：
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|

**查询参数**（如有）：
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|

**成功响应示例**：
```json
{ "success": true, "data": { ... }, "message": null, "timestamp": "..." }
```

**业务逻辑说明**：
- 规则 1
```

### 写入类接口（POST/PUT/PATCH/DELETE，有请求体）

```markdown
### N. 接口名称

**接口地址**：`POST /api/v1/{module}/{endpoint}`

**是否需要认证**：是/否

**请求体**：
```json
{
  "field": "value"
}
```

**字段说明**：
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|

**成功响应示例**：
```json
{ "success": true, "data": { ... }, "message": null, "timestamp": "..." }
```

**失败响应示例**（如有特殊错误场景）：
```json
{ "success": false, "data": null, "message": "错误描述", "timestamp": "..." }
```

**业务逻辑说明**：
- 规则 1
```

如果某个字段（如路径参数、查询参数）不适用于当前接口，直接省略该小节。

## 统一响应格式

所有 API 响应使用统一包装：

```typescript
interface ApiResponse<T> {
  success: boolean;       // 请求是否成功
  data: T | null;         // 响应数据
  message: string | null; // 错误信息（成功时为 null）
  timestamp: string;      // ISO 8601 时间戳
}
```

## 更新工作流

当接口代码发生变更时，按以下步骤操作：

### 新增接口
1. 在对应模块文档中按模板添加接口章节
2. 从 Controller 读取路由路径和方法，从 DTO 读取参数定义
3. 补充业务逻辑说明（来自 Service）
4. 添加 Cocos Creator 调用示例
5. 更新 Changelog
6. 在 `docs/api/README.md` 索引中确认已注册

### 修改接口
1. 对比代码变更，确定文档中哪些内容需要更新
2. 更新受影响的字段：路径、参数、响应结构、业务逻辑
3. 更新示例响应（确保与实际代码一致）
4. 在 Changelog 中记录变更

### 删除接口
1. 在文档中标记为「已废弃」并注明替代方案，或直接移除
2. 更新索引
3. 在 Changelog 中记录

### 错误码变更
1. 在错误码表中新增/修改/删除条目
2. 注明触发条件

## 完成后输出

文档更新完成后，向用户简要报告：
1. 哪些文档被修改了
2. 具体变更了什么内容
3. 是否有需要客户端配合调整的地方