bindbox-game/.trae/documents/Implement Backpack API for App Users.md

概述

为 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 控制
• 文档完整，前端对接字段明确；无越权与泄露