bindbox-game/docs/后台工作台接口分析/CONSENSUS_后台工作台接口.md

后台工作台接口 - 共识文档

一、明确需求描述

补充后台工作台页面中使用Mock数据的8个接口，实现真实的后端数据查询逻辑。

需求范围

1. 运营分析接口 (4个)

   • 产品动销排行
   • 优惠券效能排行
   • 库存预警列表
   • 风险事件监控

2. 积分经济接口 (3个)

   • 积分经济总览
   • 积分趋势
   • 积分收支结构

3. 实时播报接口 (1个)

   • 实时中奖播报

---

二、技术实现方案

2.1 后端接口实现位置

• 文件: internal/api/admin/dashboard_admin.go (现有文件，追加新接口)
• 路由注册: 在现有admin路由组中添加新路径

2.2 数据来源表

接口	主要数据表	关联表
产品动销排行	orders, activities	issues, products
优惠券效能	user_coupons, coupons	orders
库存预警	issues, prizes	products
风险事件	draw_logs, users	user_login_logs (如存在)
积分经济	user_points_logs	users
实时中奖	draw_logs	users, prizes

2.3 接口设计原则

• 保持与现有接口风格一致
• 使用 rangeType 参数统一时间范围过滤
• 金额单位统一为分
• 百分比保留2位小数

---

三、验收标准

功能验收

• 所有8个接口正常返回数据
• 响应格式与前端TypeScript类型定义一致
• 时间范围过滤逻辑正确

性能验收

• 单接口响应时间 < 500ms
• 无N+1查询问题

集成验收

• 前端调用后端接口无报错
• 工作台各模块正确展示真实数据

---

四、技术约束

1. 不引入新依赖: 使用现有GORM查询
2. 复用现有工具函数: 如 parseRange(), percentChange() 等
3. 统一错误处理: 使用现有 core.HandlerFunc 模式

---

五、已解决的不确定性

基于现有代码分析:

• ✅ 积分日志表 user_points_logs 已存在，包含 change_type 字段可区分来源
• ✅ 用户登录日志可通过 draw_logs 和 orders 推断活跃度
• ✅ 库存阈值可通过 prizes.quantity 与剩余数量对比计算

---

六、实现优先级

优先级	接口	原因
P0	产品动销排行	经营大盘核心指标
P0	积分经济总览+趋势	风控预警必需
P1	优惠券效能	营销分析重要
P1	库存预警	运营监控
P2	风险事件	可先用简化版
P2	实时中奖播报	可复用现有 draw_stream