first commit

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