bindbox-game/.trae/documents/APP商品API设计与交付计划.md

项目架构对齐

• 后端框架：gin（internal/pkg/core），统一中间件与响应封装
• 路由分组：internal/router/router.go 下 APP 公开/鉴权分组可扩展 products 资源
• 鉴权：APP 端采用 core.WrapAuthHandler(intc.AppTokenAuthVerify)，Authorization: Bearer <token>
• ORM/DB：gorm + gorm/gen（internal/repository/mysql/dao/Query），读写分离 GetDbR/GetDbW
• Swagger：通过注释生成（swaggo/swag），挂载 GET /swagger/*any
• 商品相关模型：product（SPU）、sku、category、spec、spec_option、product_spec、sku_spec_value、推荐位 recommendation_slot/item

接口设计

1) 商品列表

• 路径：GET /api/app/products
• 鉴权：需要（App Token）
• 请求参数：
  • page（默认1）pageSize（默认20，最大50）
  • categoryId（可选）
  • priceMin、priceMax（可选，闭区间）
  • salesMin（可选）
  • inStock（布尔，可选，默认true，仅展示可售）
  • sortBy（sales|price|createdAt）order（asc|desc，默认 desc）
• 业务规则：只返回 status=上架 的 SPU；inStock=true 时需至少一个 SKU stock-stock_locked>0
• 响应结构：

{
  "total": 1234,
  "currentPage": 1,
  "pageSize": 20,
  "list": [
    {
      "id": 1001,
      "name": "羽绒服",
      "mainImage": "https://.../xx.jpg",
      "price": 299.00,
      "sales": 5230,
      "inStock": true,
      "categoryId": 12
    }
  ]
}

• 过滤/排序实现：
  • 基于 product 表 status/category_id/sales_count/created_at/price_min/price_max 组合条件
  • inStock 通过子查询/EXISTS 关联 sku 计算有效库存

2) 商品详情

• 路径：GET /api/app/products/:id
• 鉴权：需要（App Token）
• 业务规则：SPU status=上架 且可售；下架/缺货返回业务态错误码
• 响应结构：

{
  "id": 1001,
  "name": "羽绒服",
  "album": ["https://.../1.jpg", "https://.../2.jpg"],
  "priceRange": {"min": 199.00, "max": 399.00},
  "sales": 5230,
  "stock": {"total": 235, "available": 220},
  "specs": [
    {"name": "颜色", "options": ["黑色", "白色"]},
    {"name": "尺码", "options": ["M", "L", "XL"]}
  ],
  "description": "高蓬松保暖...",
  "service": ["7天无理由", "运费险"],
  "recommendations": [
    {"id": 1002, "name": "羽绒马甲", "mainImage": "...", "price": 199.00}
  ]
}

• 规格/相册/描述来源：
  • 相册：product.images_json 或关联表（若存在），解析为数组
  • 规格：product_spec + spec + spec_option 聚合；
  • 描述/服务保障：从 product 富文本字段（或扩展表）读取
• 推荐逻辑：
  • 优先使用 recommendation_slot.scene='detail_related' 的绑定数据
  • 兜底：同类目类目内 sales_count Top N（去重当前商品）

路由与代码结构

• 路由注册：internal/router/router.go
  • appAuthGroup := router.Group("/api/app", core.WrapAuthHandler(intc.AppTokenAuthVerify))
  • appAuthGroup.GET("/products", product.New(repo, logger).List)
  • appAuthGroup.GET("/products/:id", product.New(repo, logger).Detail)
• Handler：internal/api/product/list_app.go、internal/api/product/detail_app.go
  • 统一入参校验、容错与错误码
• Service：internal/service/product/service.go
  • 封装查询、库存计算、推荐聚合、缓存命中
• DAO查询：使用 dao.Query 与 GetDbR
• DTO：internal/api/product/dto.go（列表项与详情结构体）

鉴权与权限

• 使用现有 APP Token 验证中间件；Swagger @Security LoginVerifyToken
• 接口动作无需RBAC（面向APP用户），但保留限流与风控扩展点

性能与优化（500ms SLA）

• 索引：
  • product(status, category_id, sales_count, created_at) 复合索引
  • sku(product_id, status)、sku(stock, stock_locked) 参与计算库存
• 查询：
  • 列表：单次查询 + EXISTS 子查询校验库存；分页使用 LIMIT/OFFSET（页码≤100）
  • 详情：读取 SPU + 聚合 SUM(stock-stock_locked) + 规格与相册多表查询
• 缓存：
  • 本地 TTL 缓存：
    • 列表：键 list:{filters}:{page}:{pageSize}，TTL 30s，命中后直接返回
    • 详情：键 detail:{id}，TTL 60s；库存变更事件可主动失效（后续扩展）
  • 并发合并：使用 singleflight 避免热点详情击穿
• 传输：仅必要字段；GZIP 已由中间件统一处理
• 限流：/products 每用户每秒 ≤10（后续中间件实现，可选）

错误码与校验

• 下架：PRODUCT_OFFSHELF（HTTP 200，业务码），提示“商品已下架”
• 缺货：PRODUCT_OUT_OF_STOCK
• 参数错误：INVALID_PARAM（页码、价格区间校验）
• 统一响应封装沿用 internal/pkg/core/context.go

Swagger文档

• 在两个 Handler 顶部添加注释：
  • @Summary、@Description、@Tags products
  • @Param（列出查询参数与类型）
  • @Success 200 {object} ListResp / DetailResp
  • @Router /api/app/products [get]、/api/app/products/{id} [get]
  • @Security LoginVerifyToken
• 生成后可在 http://127.0.0.1:9991/swagger/index.html 查看

单元测试

• Handler：httptest.NewServer + 构造 Authorization 头，校验分页与过滤、错误码
• Service：使用内存/模拟 DAO（或事务性测试库）覆盖：库存计算、规格聚合、推荐兜底
• 覆盖率目标：核心逻辑 ≥70%

压力测试

• 工具：hey 或 wrk
• 示例：
  • 列表：hey -n 5000 -c 100 'http://localhost:9991/api/app/products?page=1&pageSize=20'
  • 详情：wrk -t4 -c200 -d30s 'http://localhost:9991/api/app/products/1001'
• 目标：P95 ≤ 500ms，错误率 < 0.1%

联调与交付

• 与前端约定字段与筛选参数；提供响应示例与错误码表
• 提供 Swagger 文档与可复用的 Postman/HTTP 文件
• 完成线上/测试环境联调回归

验收标准

• 两个接口完成并通过单元与压力测试
• Swagger 文档完整，含请求/响应示例
• P95 响应时间 ≤ 500ms（测试环境数据量下）
• 鉴权与状态校验生效；缓存命中率提升热点访问性能