---
name: 生成前端接口文档
overview: 全量分析 zt-closet-backend 代码，在根目录 `接口文档.md`（当前为空文件）生成一份面向前端工程师的自包含接口文档：覆盖全部 42 个路由的字段级入参/出参、业务逻辑与状态机、调用时序图与 curl 示例、完整错误码表与前端处理约定。README.md 保持不变。
todos:
  - id: explore-facts
    content: 用 [subagent:code-explorer] 全量抽取路由、DTO 字段与校验、路径参数名、业务规则与错误码事实清单
    status: completed
  - id: doc-conventions
    content: 撰写文档头、目录、通用调用约定、42 路由总表与公共数据结构
    status: completed
    dependencies:
      - explore-facts
  - id: doc-user-module
    content: 撰写用户、额度、运势模块的字段级接口详解
    status: completed
    dependencies:
      - doc-conventions
  - id: doc-clothes-outfit-ai
    content: 撰写衣物、穿搭、AI 推荐模块接口详解及异步处理/额度规则
    status: completed
    dependencies:
      - doc-conventions
  - id: doc-social
    content: 撰写衣柜分享、收藏、点赞、通知模块接口详解及交互规则
    status: completed
    dependencies:
      - doc-conventions
  - id: doc-trade
    content: 撰写商品、订单模块接口详解，标注支付回调为服务端专用
    status: completed
    dependencies:
      - doc-conventions
  - id: doc-biz-errcode
    content: 补写业务逻辑与状态机章节、mermaid 时序图、curl 示例、全量错误码表与前端 FAQ
    status: completed
    dependencies:
      - doc-user-module
      - doc-clothes-outfit-ai
      - doc-social
      - doc-trade
  - id: doc-verify
    content: 对照代码复核路径参数名、字段名差异、枚举取值与错误码，修正不一致
    status: completed
    dependencies:
      - doc-biz-errcode
---

## 用户原始需求

分析 `zt-closet-backend` 全量代码，生成一份**面向前端工程师**的接口文档，并且在文档中把**业务逻辑**也描述清楚。

## 澄清后的补充约定

1. **交付形式**：填充根目录已有的空文件 `接口文档.md`，产出一份自包含 Markdown 文档（含全部 42 个路由、字段级入参/出参、业务逻辑、时序图、错误码、curl 示例），可直接交付前端。不产出 OpenAPI/Swagger 文件。
2. **内容范围（四项全选）**：

- 字段级入参/出参表：必填性、类型、长度限制、枚举含义，必须以 `internal/dto` 的 `json`/`form`/`binding` tag 逐字段核对，不得臆造
- 业务逻辑与状态机：额度扣减/回退、衣物 AI 处理状态机、订单状态机、穿搭公开/审核状态机、衣柜分享状态机、通知触发规则
- 调用时序图 + 示例：mermaid 时序图（登录刷新、上传轮询、AI 推荐保存、下单支付、点赞收藏切换）+ curl/JSON 示例
- 错误码全表与前端处理建议：按业务域列出全部错误码，说明 401 刷新 token、以 `code` 为准、金额单位为分等前端约定

3. **README.md 保持不动**：允许与接口文档有少量重复；发现 README 与代码不一致时，只以代码为准写入接口文档，不修改 README。

## 核心产出内容

- 文档头与服务信息：BasePath `/api/v1`、环境说明、鉴权方式
- 通用调用约定：Bearer Token、统一响应结构、HTTP 状态码与业务码映射、分页约定、金额单位、时间戳单位、幂等约定、轮询策略
- 42 个路由总表（公开 6 + 鉴权 35 + 健康检查 1）
- 11 个业务模块的接口详解（用户、额度、运势、衣物、穿搭、衣柜分享、收藏、点赞、通知、商品、订单、AI 推荐）
- 公共数据结构定义（user_info / ClothesItem / OutfitItem / GoodsItem / OrderItem / NotificationItem / QuotaFlowItem）
- 业务逻辑章节：7 条业务主线 + 状态机图 + 额度规则 + 通知触发规则
- 5 张 mermaid 时序图 + curl/JSON 示例
- 全量错误码表（按业务域分段）+ 前端处理建议
- 前端联调 FAQ / 检查清单

## 约束

- 唯一写入文件：`/root/zt-closet-backend/接口文档.md`
- 所有路径、字段名、枚举值、错误码必须与代码一致；微信支付/退款回调需标注"服务端专用，前端禁止调用"

## 技术栈

- 项目：Go 1.27 + Gin + GORM/MySQL + go-redis + JWT + 腾讯云 COS + 微信支付 V3 + OpenTelemetry
- 文档：Markdown（GFM 表格）+ Mermaid（`sequenceDiagram` / `stateDiagram-v2` / `flowchart`），零新增依赖、零代码改动

## 实施策略

"事实抽取 → 分模块撰写 → 交叉复核"三段式：

1. **事实抽取**：以代码为唯一事实源，按顺序读取

- `internal/routers/router.go`：42 个路由的方法、路径、是否鉴权、路径参数名
- `internal/dto/*.go`（13 个）：请求/响应字段、`binding` 校验规则（必填/最大长度/枚举 `oneof`/数组 `min,max`）、`json` 与 `form` 差异
- `internal/routers/api/v1/*.go`（12 个）：参数来源（json/query/path/form）、路径参数真实名称（如 `:targetUUID`、`:orderNo`）
- `internal/service/*.go`（16 个）：业务规则、状态机、额度扣减/回退、幂等、异步流水线、通知触发
- `internal/mysqlmodel/*.go`：枚举值语义与字段含义
- `pkg/errcode/*.go`（10 个）：全量错误码与文案
- `pkg/app/`：统一响应结构 `{code, msg, data}` 与 `details` 行为
- `internal/middleware/`：JWT 鉴权、401/403 行为

2. **分模块撰写**：按业务域顺序写入同一文件，先写通用约定与公共数据结构，再写各模块接口，最后写业务规则、时序图、错误码与 FAQ，保证前端从上到下即可读懂。
3. **交叉复核**：逐项比对路由总数、路径参数名、请求/响应字段名差异、枚举取值，确保无遗漏无臆造。

## 关键设计决策

- **单一文件自包含**：前端只需一个文件，不拆分为多文档；用锚点目录做导航。
- **公共数据结构集中定义**：`user_info`、ClothesItem、OutfitItem、GoodsItem、OrderItem、NotificationItem、QuotaFlowItem 在"公共数据结构"章节统一定义，接口章节引用，避免重复与不一致（DRY）。
- **坑位显式高亮**：对已确认的不一致点加粗标注——更新衣物的主颜色请求字段为 `color`（响应为 `color_main`）；`GET /like/:targetUUID`、`POST /order/:orderNo/cancel` 的路径参数名非 `uuid`；通知 `is_read` 为 `1 未读 / 2 已读` 而非布尔；支付/退款回调不走统一响应且前端禁止调用。
- **业务与接口分离但互链**：业务逻辑章节独立成章（状态机 + 规则），接口章节每个接口挂"业务逻辑"小节与相关错误码，双向锚点引用。

## 实施注意事项

- **准确性优先**：每个字段表必须来自 dto tag 而非 README；README 仅作素材参考，遇冲突以代码为准且**不改动 README**。
- **性能/规模**：文档较长（预计 1500+ 行），分批追加写入，避免单次超长写入出错；表格列保持统一（字段 / 类型 / 必填 / 说明）。
- **兼容性**：不改动任何 Go 代码、配置与路由，零运行时影响。

## 目录结构

```
/root/zt-closet-backend/
└── 接口文档.md   # [MODIFY] 当前为空文件。写入完整前端接口文档：服务信息与 BasePath、通用调用约定
                  # （鉴权/统一响应/HTTP 与业务码映射/分页/金额与时间单位/幂等/轮询）、42 个路由总表、
                  # 公共数据结构、11 个业务模块字段级接口详解（含业务逻辑说明）、7 条业务主线与状态机
                  # （额度/衣物 AI/穿搭/衣柜分享/订单/AI 推荐/通知）、5 张 mermaid 时序图 + curl/JSON
                  # 示例、全量错误码表、前端联调 FAQ 与检查清单。
```

只读参考（不修改）：`internal/routers/router.go`、`internal/dto/*.go`、`internal/routers/api/v1/*.go`、`internal/service/*.go`、`internal/mysqlmodel/*.go`、`pkg/errcode/*.go`、`pkg/app/`、`internal/middleware/`、`README.md`

## Agent Extensions

### SubAgent

- **code-explorer**
- 用途：全量扫描 `internal/routers`、`internal/dto`、`internal/routers/api/v1`、`internal/service`、`internal/mysqlmodel`、`pkg/errcode`、`pkg/app`、`internal/middleware`，抽取路由清单、字段级 DTO 与校验规则、路径参数名、业务状态机与规则、全量错误码
- 预期产出：一份可直接用于撰写的事实清单（路由 × 参数 × 响应 × 枚举 × 错误码 × 业务规则），保证文档零臆造