92 lines
2.5 KiB
Markdown
92 lines
2.5 KiB
Markdown
# 后台工作台接口 - 共识文档
|
||
|
||
## 一、明确需求描述
|
||
|
||
补充后台工作台页面中使用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` |
|