邹方成
45815bfb7d
refactor(utils): 修复密码哈希比较逻辑错误 feat(user): 新增按状态筛选优惠券接口 docs: 添加虚拟发货与任务中心相关文档 fix(wechat): 修正Code2Session上下文传递问题 test: 补充订单折扣与积分转换测试用例 build: 更新配置文件与构建脚本 style: 清理多余的空行与注释
74 lines
4.4 KiB
Markdown
74 lines
4.4 KiB
Markdown
## 概述
|
||
为 APP 端提供“用户背包”能力，覆盖用户资产的六类数据：积分消费明细、优惠券、道具卡、头衔、订单、中奖资产（背包）。在保留现有分项查询接口的基础上，新增缺失的 APP 端接口与一个聚合概要接口，统一鉴权与分页规范，并更新 API 文档。
|
||
|
||
## 新增接口
|
||
- GET `/api/app/users/{user_id}/inventory`
|
||
- 功能：用户背包列表（中奖资产），按时间倒序，支持分页
|
||
- 返回：`InventoryWithProduct` 列表（含商品名称、图片、等级/备注、关联活动/奖励ID）
|
||
- 鉴权：`LoginVerifyToken`
|
||
- GET `/api/app/users/{user_id}/titles`
|
||
- 功能：用户头衔列表，支持分页
|
||
- 返回：`UserTitleItem` 列表（称号ID、名称、来源/获得时间、可选效果）
|
||
- 鉴权：`LoginVerifyToken`
|
||
- GET `/api/app/users/{user_id}/backpack`
|
||
- 功能：聚合概要接口，返回六类资产的“计数+最近N条”，用于首页/概览展示
|
||
- 查询参数：`limit=5`（各类最近条数），`include=points,coupons,item_cards,titles,orders,inventory`（可选，默认全包含）
|
||
- 返回：
|
||
- `points: {count, recent: UserPointsLedger[]}`
|
||
- `coupons: {count, recent: CouponItem[]}`
|
||
- `item_cards: {count, recent: ItemCardWithTemplate[]}`
|
||
- `titles: {count, recent: UserTitleItem[]}`
|
||
- `orders: {count, recent: Orders[]}`
|
||
- `inventory: {count, recent: InventoryWithProduct[]}`
|
||
- 鉴权：`LoginVerifyToken`
|
||
|
||
## 复用现有 APP 接口（保持不变）
|
||
- 积分明细：GET `/api/app/users/{user_id}/points`（已存在）
|
||
- 积分余额：GET `/api/app/users/{user_id}/points/balance`（已存在）
|
||
- 优惠券：GET `/api/app/users/{user_id}/coupons`（已存在）
|
||
- 道具卡：GET `/api/app/users/{user_id}/item_cards`、GET `/api/app/users/{user_id}/item_cards/uses`（已存在）
|
||
- 订单：GET `/api/app/users/{user_id}/orders`（已存在）
|
||
|
||
## 数据模型（响应结构）
|
||
- `InventoryWithProduct`：`{ id, product_id, title, images[], activity_id, reward_id, order_id, level, created_at }`
|
||
- `UserTitleItem`：`{ user_title_id, title_id, title_name, acquired_at, effects?: [{key, value, unit}], expires_at? }`
|
||
- `CouponItem`（沿用现有）：`{ id, name, amount, valid_start, valid_end, status, rules }`
|
||
- `ItemCardWithTemplate`（沿用现有）：含模板字段与剩余次数/有效期
|
||
- `Orders`（沿用现有）：按现有模型返回
|
||
- `UserPointsLedger`（沿用现有）：按现有模型返回
|
||
|
||
## 技术实现
|
||
- 目录与文件：
|
||
- `internal/api/user/inventory_app.go`：`ListUserInventoryForApp()`（调用 `usersvc.ListInventoryWithProduct`）
|
||
- `internal/api/user/titles_app.go`：`ListUserTitlesForApp()`（新增 usersvc 方法或复用 admin 服务逻辑）
|
||
- `internal/api/user/backpack_app.go`：`GetUserBackpackOverview()`（各服务查询计数与最近N条）
|
||
- 路由：`internal/router/router.go`
|
||
- APP 认证组注册：`/users/:user_id/inventory`、`/users/:user_id/titles`、`/users/:user_id/backpack`
|
||
- Service 层：`internal/service/user`
|
||
- `ListInventoryWithProduct(ctx, userID, page, pageSize)`（已有）
|
||
- `ListUserTitles(ctx, userID, page, pageSize)`（新增）：查询用户称号关联与系统称号名称/效果
|
||
- 计数方法：各类 `CountXxx(ctx, userID)`（供概要接口聚合）
|
||
|
||
## 鉴权与约束
|
||
- 所有接口使用 `LoginVerifyToken`
|
||
- `user_id` 为路径参数，但服务端以会话 `SessionUserInfo().Id` 校验一致性，防越权
|
||
- 分页统一：`page`、`page_size`（默认 1/20，最大 100），按 `created_at` 倒序
|
||
|
||
## Swagger 文档
|
||
- 为新增 3 个接口添加注解：`@Summary`、`@Description`、`@Tags APP端.用户`、`@Security LoginVerifyToken`、`@Param`、`@Success`/`@Failure`、`@Router`
|
||
- 模型定义共用已有结构；为新结构 `UserTitleItem`、`InventoryWithProduct` 增加定义
|
||
- 执行脚本生成文档：`scripts/swagger.sh`
|
||
|
||
## 测试与验收
|
||
- 单元/集成：
|
||
- 伪造用户会话，验证分页与鉴权；数据空集场景返回空数组
|
||
- 概要接口在 `include` 过滤时仅返回所选分组
|
||
- 手工验证：
|
||
- 分别对六类接口 `curl` 测试分页与计数一致性
|
||
- Swagger 文档能正确展示并可试用
|
||
|
||
## 验收标准
|
||
- 三个新增接口可用且鉴权正确；分页与计数正确
|
||
- 概要接口耗时可控（<200ms 在百条内数据量）；可通过 `include` 控制
|
||
- 文档完整，前端对接字段明确；无越权与泄露
|