zt-closet-backend/.codebuddy/plans/补充_README_接口调用逻辑文档_747f2d39.md

name, overview, todos

name	overview	todos
补充 README 接口调用逻辑文档	在现有 README 的 API 概览基础上，补充通用调用约定（鉴权/响应/分页/幂等/状态码映射）、全量接口入参出参字段表（基于 internal/dto）、核心业务调用流程时序（登录、衣物上传与 AI 处理轮询、AI 推荐、订单支付、点赞收藏），并附关键接口示例，使其他开发者可通过 README 确认调用逻辑。	id content status extract-contracts 使用 [subagent:code-explorer] 读取全部 dto 与 handler 文件，产出逐接口契约事实清单（绑定方式/请求响应字段/枚举） completed id content status dependencies write-conventions-details 在 README 的 API 概览章节增补通用调用约定与 11 个模块的接口请求/响应字段详解表 completed extract-contracts id content status dependencies write-flows-examples 增补 5 条核心业务调用流程（mermaid 时序图与步骤说明）及关键接口 curl 调用示例 completed write-conventions-details id content status dependencies proofread-readme 全文校对：字段、枚举、错误码、路由与代码一致，检查 Markdown 与 mermaid 渲染正确 completed write-flows-examples

用户需求

在上一轮已完成 README.md（含项目简介、核心功能、技术栈、目录结构、快速开始、配置说明、API 路由概览表、错误码分段表等章节）的基础上，进一步补充完善 README，使其他人（前端 / 联调开发者）仅凭 README 即可确认接口的调用逻辑：

• 每个接口如何调用：方法、路径、请求参数（字段/类型/必填/说明）、响应字段
• 关键业务的调用顺序与依赖关系
• 统一调用约定：鉴权方式、响应结构、HTTP 状态码与业务错误码映射、分页、幂等
• 关键接口的调用示例（curl + 响应 JSON）

交付物：仅修改 /root/zt-closet-backend/README.md，在现有内容上增补，不重写已有章节，中文撰写；所有字段名、枚举值、默认值以代码为准，不虚构。

核心内容

1. 通用调用约定：Bearer 鉴权（11000/11001/11002/11004 错误）、统一响应结构（成功/失败 JSON 示例）、HTTP 状态码与业务 code 映射（401/403/429/500）、分页约定（page/page_size，max 50）、幂等约定（点赞/收藏 Action 切换、AI 推荐保存防重）。
2. 接口调用详解：按 11 个业务模块（用户/额度/运势/衣物/穿搭/衣柜分享/点赞收藏/通知/商品/订单/AI 推荐）为全部 40+ 接口给出请求参数表与响应字段表，字段严格以 internal/dto 的 json tag、binding 与注释为准。
3. 核心业务调用流程：5 条流程（登录与 token 刷新、衣物上传到 AI 处理状态轮询、AI 推荐到保存为穿搭、订单创建到微信支付回调到查询、点赞/收藏切换），配 mermaid 时序图与编号步骤。
4. 调用示例：登录、衣物上传、状态查询、AI 推荐等关键接口的 curl 命令与响应 JSON。

撰写策略

事实来源与准确性保障

• 全部接口契约以 internal/dto/（13 个文件的 Request/Response 结构体：json tag、binding 约束、中文注释）与 internal/routers/router.go（路由注册、path 参数）为准。
• 参数绑定方式（JSON body / GET form / path / multipart file）以 internal/routers/api/v1/ 下 12 个 handler 文件为准；若 dto 与 handler 不一致，以 handler 与 router.go 为准。
• 枚举与常量（衣物处理状态 1-5、点赞/收藏 Action 1/2、订单状态 1-5 等）以 internal/service/constants.go 为准。

文档结构（在现有 README 的 API 概览章节内增补）

1. 通用调用约定：鉴权头格式与失效表现、成功/失败响应 JSON 示例、HTTP 状态码映射表、分页约定、幂等约定。
2. 接口调用详解：每个模块小节先列路由清单，再逐接口给请求参数表与响应字段表，采用紧凑三列表格（字段/类型/说明），字段类型按 JSON 语义标注（string/int/int64/bool/object/array），必填性依据 binding 标签。
3. 核心业务调用流程：5 条流程各配一张 mermaid sequenceDiagram（参与方：小程序前端、后端、微信/推理服务/大模型），流程图下附编号步骤说明与关键注意点（如衣物上传后立即返回排队状态、前端需轮询 status 接口；订单支付回调为公开路由、注意验签）。
4. 调用示例：登录、衣物上传（multipart）、状态查询、AI 推荐等关键接口的 curl 示例与响应 JSON。

篇幅控制

• 复用已有路由总表与错误码表，不重复整表；详解部分只补充字段级信息。
• 字段过多的响应（如衣物 15 维分类字段）用紧凑表格呈现；公共分页结构说明一次，列表接口仅标注内嵌 PageResponse。
• 保持既有章节编号与顺序不变，仅在 API 概览内插入小节。

推荐使用的扩展

SubAgent

• code-explorer
• 用途：读取 internal/dto/ 全部 13 个文件与 internal/routers/api/v1/ 全部 12 个 handler 文件，提取每个接口的绑定方式（JSON body/form/path/multipart）、请求与响应字段（json tag、类型、binding、注释）、以及 internal/service/constants.go 中的相关枚举常量
• 预期结果：输出一份逐接口的契约事实清单（模块/接口/方法/路径/参数绑定方式/请求字段表/响应字段表/枚举值），作为撰写 README 的唯一事实依据，确保无虚构字段