zt-closet-backend/.codebuddy/plans/生成前端接口文档_05e564d5.md

name, overview, todos

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