--- name: api-v1层完整实现 overview: 实现 internal/routers/api/v1 全部 HTTP handler 并在 router.go 完成中间件与路由接线，调用已完成的 service 层；同时修复阻断运行的中间件/启动初始化问题，形成可跑通的 RESTful 接口。 todos: - id: fix-infra content: 修复 middleware（requestid uuid 导入、JWTAuth 封禁判断反转与缓存回落 DB）、main.go 初始化 global.Tracer/CosClient 与运势任务、dto 列表字段补 form tag status: completed - id: handlers-user-basic content: 实现 user/quota/horoscope/goods 四个 handler（登录/刷新/信息/额度/运势/商品） status: completed dependencies: - fix-infra - id: handlers-clothes-outfit content: 实现 clothes（含 multipart 上传）与 outfit 两个 handler，覆盖增删改查与公开 status: completed dependencies: - fix-infra - id: handlers-community content: 实现 closet/collect/like/notification 四个 handler（分享、收藏、点赞、通知） status: completed dependencies: - fix-infra - id: handlers-order-ai content: 实现 order（含微信支付/退款回调按规范返回）与 airecommend 两个 handler status: completed dependencies: - fix-infra - id: wire-router content: 在 router.go 接线中间件链与 /api/v1 公开/鉴权路由，添加 /ping，go build 与 go vet 全量验证 status: completed dependencies: - handlers-user-basic - handlers-clothes-outfit - handlers-community - handlers-order-ai --- ## 产品概述 为"衣柜/穿搭"微信小程序后端补齐 **HTTP 接口层（api/v1）**：将已完成的 service 业务逻辑通过 Gin handler 暴露为 RESTful 接口，并完成路由与中间件接线，形成可跑通的完整后端服务。 ## 核心功能 - **用户与登录**：微信登录、刷新 Token、获取/修改个人信息 - **衣物管理**：上传（含图片处理）、状态查询、详情、修改、删除、列表 - **穿搭管理**：创建、详情、修改、删除、列表、公开设置 - **衣柜分享**：创建、详情（访客/属主）、我的分享列表、取消 - **社区互动**：点赞/取消、点赞状态与计数、收藏/取消、收藏列表 - **消息通知**：列表、详情、标记已读、未读数 - **商品与订单**：商品查询/列表、下单、订单列表、取消、退款申请、微信支付/退款回调 - **额度与运势**：额度概览与流水、今日运势 - **AI 推荐**：发起 AI 穿搭推荐、保存到我的搭配 ## 接口约定 - 统一前缀 `/api/v1`；成功返回 `{code:0,msg,data}`，失败按业务错误码返回。 - 登录、刷新 Token、商品查询、微信回调为公开接口；其余需登录鉴权。 - 微信支付/退款回调按微信规范返回受理结果。 ## 技术栈 - 语言/框架：Go 1.27 + Gin（沿用现有项目），复用 `pkg/app`（统一响应）、`pkg/errcode`（业务错误码）、`internal/middleware`（JWT/CORS/日志/追踪/RequestID）。 - 依赖注入：handler 结构体持有对应 `internal/service`，构造函数注入，与 service/dao 现有风格一致。 ## 实现思路 新增 `internal/routers/api/v1` 下按业务域拆分的 handler，并在 `router.go` 完成中间件与路由接线。handler 只负责：请求绑定与校验、path param 覆盖标识字段、从 context 取 userID、调用 service、统一响应转换；业务逻辑与归属校验（AuthZ）保持在 service 层，handler 不重复实现。 统一 handler 模式： 1. `resp := app.NewResponse(c)` 2. 绑定：JSON 用 `ShouldBindJSON`，GET query 用 `ShouldBindQuery`，失败返回 `errcode.InvalidParams.WithDetails(err.Error())` 3. REST 路径标识（uuid/code/orderNo 等）用 `c.Param(...)` 覆盖 req 对应字段 4. `middleware.GetUserID(c.Request.Context())` 取 userID 5. 调 service，错误 `resp.ToErrorResponse(e)`，成功 `resp.ToResponse(out)` ### 关键技术决策 - **同层静态路由与参数路由共存**：Gin v1.12 支持 `/notification/unread` 与 `/notification/:uuid`、`/order/refund` 与 `/order/:orderNo/cancel` 共存，无需拆分前缀，保持 URL 语义清晰。 - **微信回调独立处理**：回调不走 JWT，handler 读 `c.GetRawData()` 原始报文传 service（service 已做 V3 验签/GCM 解密），按微信规范返回 `{"code":"SUCCESS"}`（200）或 `{"code":"FAIL","message":...}`（非 200），避免微信重复回调。 - **文件上传**：`/clothes/upload` 用 `c.FormFile("file")` 取 `*multipart.FileHeader` 传 service。 ## 实现要点（防回归） 本次需一并修复阻断 api 层编译/运行的既有问题，否则接口无法跑通： - **middleware/requestid.go**：修复非法导入 `import "uuid"` → `github.com/google/uuid`，调用 `uuid.New().String()`（当前该文件导致 middleware 包无法编译）。 - **middleware/lzcwyjwt.go**： - 修复封禁判断反转：`if userInfo.Status == 1` → 应为 `!= 1` 时拒绝（1=正常），避免正常用户被拦、禁用用户放行。 - 缓存未命中（`redis.Nil`）回落 DB（`mysqldao.UserDao.UserGetByID`），成功回填 `redisdao.UserInfoSet`，仍失败再拒绝，避免缓存过期导致合法用户被锁死。 - **main.go 运行期初始化**（当前缺失，直接运行会 nil panic）： - `global.Tracer = otel.Tracer(global.OtelSetting.ServiceName)`（otel 默认 no-op provider 返回合法非 nil tracer，DAO 的 `global.Tracer.Start` 依赖它）。 - `global.CosClient, _ = cos.NewCosClient()`（衣物上传 `upload.FileUploadCos` 依赖）。 - 启动运势兜底：`tokenhub.EnsureTodayFortunes()` 与 `tokenhub.StartFortuneScheduler()`。 - **dto 补 form tag**（GET query 筛选可用的最小调整）：`OutfitListRequest.IsPublic/Source`、`GoodsListRequest.GoodsType`、`ClosetShareListRequest.Status` 当前仅 `json` tag，需补 `form` tag 才能 `ShouldBindQuery` 绑定。 - 不打印 token/密钥；绑定错误文本作为 details 返回可接受，不泄露内部实现。 ## 架构与数据流 请求 → Gin 中间件链（Recovery → RequestID → OTel → Slog → CORS）→ [公开路由 / JWTAuth 鉴权组] → v1 handler（绑定+取 userID）→ service（业务+AuthZ）→ dao/redis/pkg → 统一响应。 ## 目录结构 ``` zt-closet-backend/ ├── main.go # [MODIFY] 初始化 global.Tracer / global.CosClient；启动运势定时任务与启动兜底 ├── internal/ │ ├── dto/ │ │ ├── outfit.go # [MODIFY] OutfitListRequest.IsPublic/Source 补 form tag │ │ ├── goods.go # [MODIFY] GoodsListRequest.GoodsType 补 form tag │ │ └── closet.go # [MODIFY] ClosetShareListRequest.Status 补 form tag │ ├── middleware/ │ │ ├── requestid.go # [MODIFY] 修复 uuid 导入路径 │ │ └── lzcwyjwt.go # [MODIFY] 修复封禁状态判断反转 + 缓存未命中回落 DB 回填 │ └── routers/ │ ├── router.go # [MODIFY] 中间件链接线 + /api/v1 公开与鉴权路由注册 + /ping │ └── api/v1/ │ ├── user.go # [NEW] UserHandler：WxLogin/RefreshToken/InfoGetBySelf/ProfileUpdate │ ├── quota.go # [NEW] QuotaHandler：Info/FlowList │ ├── horoscope.go # [NEW] HoroscopeHandler：Today │ ├── clothes.go # [NEW] ClothesHandler：Upload/List/Get/Status/Update/Delete │ ├── outfit.go # [NEW] OutfitHandler：Create/Get/Update/Delete/List/Public │ ├── closet.go # [NEW] ClosetShareHandler：Create/Detail/List/Cancel │ ├── collect.go # [NEW] CollectHandler：Collect/List │ ├── like.go # [NEW] LikeHandler：Like/GetByTarget │ ├── notification.go # [NEW] NotificationHandler：List/Unread/Get/Read │ ├── goods.go # [NEW] GoodsHandler：GetByCode/List（公开） │ ├── order.go # [NEW] OrderHandler：Create/List/Cancel/RefundApply/PayNotify/RefundNotify │ └── airecommend.go # [NEW] AIRecommendHandler：Create/Save ``` ## 路由清单（前缀 /api/v1） 公开：POST /user/wxlogin、POST /user/refresh-token、GET /goods、GET /goods/:code、POST /order/pay/notify、POST /order/refund/notify 鉴权（JWTAuth）： - GET /user/info、PUT /user/profile - GET /quota/info、GET /quota/flow - GET /horoscope/today - POST /clothes/upload、GET /clothes、GET /clothes/:uuid、GET /clothes/:uuid/status、PUT /clothes/:uuid、DELETE /clothes/:uuid - POST /outfit、GET /outfit、GET /outfit/:uuid、PUT /outfit/:uuid、DELETE /outfit/:uuid、PUT /outfit/:uuid/public - POST /closet-share、GET /closet-share、GET /closet-share/:uuid、POST /closet-share/:uuid/cancel - POST /collect、GET /collect - POST /like、GET /like/:targetUUID - GET /notification、GET /notification/unread、GET /notification/:uuid、POST /notification/:uuid/read - POST /order、GET /order、POST /order/:orderNo/cancel、POST /order/refund - POST /ai-recommend、POST /ai-recommend/save ## SubAgent - **code-explorer** - Purpose：实现阶段如需核对个别 service 方法签名或 dto 字段（如回调 body 读取、multipart 字段名、path param 与 dto 字段映射），快速跨文件确认，避免签名臆测。 - Expected outcome：handler 与 service 签名、dto 绑定一次性对齐，减少编译期返工。