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

## 一、明确需求描述

补充后台工作台页面中使用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` |