260 lines
6.9 KiB
Markdown
260 lines
6.9 KiB
Markdown
# 后台工作台页面接口分析
|
||
|
||
## 一、原始需求
|
||
分析后台工作台页面的所有设计，确定需要对应哪些接口，并补充后端缺失的接口实现。
|
||
|
||
## 二、项目特性规范
|
||
|
||
### 技术栈
|
||
- **前端**: Vue 3 + TypeScript + Element Plus
|
||
- **后端**: Go + Gin + GORM
|
||
- **API风格**: RESTful
|
||
|
||
### 现有架构
|
||
- 前端API定义: `web/admin/src/api/dashboard.ts`, `web/admin/src/api/operations.ts`
|
||
- 后端处理器: `internal/api/admin/dashboard_admin.go`
|
||
|
||
---
|
||
|
||
## 三、工作台页面模块与接口对应关系
|
||
|
||
### 维度1: 经营大盘 (overview)
|
||
|
||
| 组件 | 功能 | 前端API | 后端状态 | 备注 |
|
||
|------|------|---------|----------|------|
|
||
| `card-list.vue` | 顶部统计卡片 | `fetchCardStats` | ✅ 已实现 | `DashboardCards` |
|
||
| `sales-overview.vue` | 销售趋势分析 | `fetchSalesDrawTrend` | ✅ 已实现 | `DashboardSalesDrawTrend` |
|
||
| `product-performance.vue` | 产品动销排行 | `fetchProductPerformance` | ⚠️ Mock数据 | 需要实现 |
|
||
| `user-economics.vue` | 用户经济分析 | `fetchUserEconomics` | ✅ 已实现 | `DashboardUserEconomics` |
|
||
|
||
---
|
||
|
||
### 维度2: 奖池与欧气 (lottery)
|
||
|
||
| 组件 | 功能 | 前端API | 后端状态 | 备注 |
|
||
|------|------|---------|----------|------|
|
||
| `prize-pool-health.vue` | 奖池健康度分析 | `fetchPrizeDistribution` | ✅ 已实现 | `DashboardPrizeDistribution` |
|
||
| `live-stream-premium.vue` | 全服欧气实时播报 | 无（模拟数据） | ⚠️ 需要实现 | 需要新增实时中奖播报接口 |
|
||
|
||
---
|
||
|
||
### 维度3: 营销转化 (marketing)
|
||
|
||
| 组件 | 功能 | 前端API | 后端状态 | 备注 |
|
||
|------|------|---------|----------|------|
|
||
| `growth-analytics.vue` | 增长经济模型分析 | `fetchUserEconomics` | ✅ 已实现 | 复用 `DashboardUserEconomics` |
|
||
| `coupon-roi.vue` | 营销券效能排行 | `fetchCouponEffectiveness` | ⚠️ Mock数据 | 需要实现 |
|
||
| `retention-cohort.vue` | 留存同类群组分析 | `fetchRetentionAnalytics` | ✅ 已实现 | `DashboardRetentionAnalytics` |
|
||
| `marketing-conversion.vue` | 订单转化全链路监控 | `fetchOrderFunnel` | ✅ 已实现 | `DashboardOrderFunnel` |
|
||
|
||
---
|
||
|
||
### 维度4: 风控预警 (security)
|
||
|
||
| 组件 | 功能 | 前端API | 后端状态 | 备注 |
|
||
|------|------|---------|----------|------|
|
||
| `inventory-alert.vue` | 库存预警监控 | `fetchInventoryAlerts` | ⚠️ Mock数据 | 需要实现 |
|
||
| `risk-monitor.vue` | 异常风险监控 | `fetchRiskEvents` | ⚠️ Mock数据 | 需要实现 |
|
||
| `points-economy.vue` | 积分经济总览 | `fetchPointsEconomySummary`<br>`fetchPointsTrend`<br>`fetchPointsStructure` | ⚠️ Mock数据 | 需要实现3个接口 |
|
||
|
||
---
|
||
|
||
## 四、需要补充的后端接口清单
|
||
|
||
### 4.1 运营分析接口 (Operations)
|
||
|
||
#### 1. 产品动销排行 `GET /admin/operations/product_performance`
|
||
```json
|
||
// Request
|
||
{ "rangeType": "7d|30d|today" }
|
||
|
||
// Response
|
||
[
|
||
{
|
||
"id": 1,
|
||
"seriesName": "系列名称",
|
||
"salesCount": 1540,
|
||
"amount": 285000, // 销售金额(分)
|
||
"contributionRate": 35.5, // 利润贡献率%
|
||
"inventoryTurnover": 8.5 // 周转率
|
||
}
|
||
]
|
||
```
|
||
|
||
#### 2. 优惠券效能排行 `GET /admin/operations/coupon_effectiveness`
|
||
```json
|
||
// Request
|
||
{ "rangeType": "7d|30d" }
|
||
|
||
// Response
|
||
[
|
||
{
|
||
"couponId": 1,
|
||
"couponName": "新用户专享券",
|
||
"type": "满减券",
|
||
"issuedCount": 1200,
|
||
"usedCount": 680,
|
||
"usedRate": 56.7, // 使用率%
|
||
"broughtOrders": 720, // 带动订单数
|
||
"broughtAmount": 3600000, // 带动金额(分)
|
||
"roi": 3.2 // 投资回报率
|
||
}
|
||
]
|
||
```
|
||
|
||
#### 3. 库存预警列表 `GET /admin/operations/inventory_alerts`
|
||
```json
|
||
// 无请求参数
|
||
|
||
// Response
|
||
[
|
||
{
|
||
"id": 101,
|
||
"name": "商品名称",
|
||
"type": "physical|virtual|coupon",
|
||
"stock": 3,
|
||
"threshold": 5,
|
||
"salesSpeed": 1.2 // 日均消耗速度
|
||
}
|
||
]
|
||
```
|
||
|
||
#### 4. 风险事件监控 `GET /admin/operations/risk_events`
|
||
```json
|
||
// 无请求参数
|
||
|
||
// Response
|
||
[
|
||
{
|
||
"userId": 5001,
|
||
"nickname": "用户昵称",
|
||
"avatar": "头像URL",
|
||
"type": "frequent_win|batch_register|ip_clash",
|
||
"description": "24小时内中奖5次一等奖",
|
||
"riskLevel": "high|medium|low",
|
||
"createdAt": "13:20"
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
### 4.2 积分经济接口 (Points Economy)
|
||
|
||
#### 5. 积分经济总览 `GET /admin/operations/points_economy_summary`
|
||
```json
|
||
// Request
|
||
{ "rangeType": "7d|30d" }
|
||
|
||
// Response
|
||
{
|
||
"totalIssued": 1258400, // 发行总积分
|
||
"totalConsumed": 985600, // 消耗总积分
|
||
"netChange": 272800, // 净变化
|
||
"activeUsersWithPoints": 5640, // 持分活跃用户数
|
||
"conversionRate": 78.5 // 活跃持仓率%
|
||
}
|
||
```
|
||
|
||
#### 6. 积分趋势 `GET /admin/operations/points_trend`
|
||
```json
|
||
// Request
|
||
{ "rangeType": "7d|30d" }
|
||
|
||
// Response
|
||
[
|
||
{
|
||
"date": "2026-01-01",
|
||
"issued": 20000,
|
||
"consumed": 15000,
|
||
"expired": 1000,
|
||
"netChange": 4000,
|
||
"balance": 250000
|
||
}
|
||
]
|
||
```
|
||
|
||
#### 7. 积分收支结构 `GET /admin/operations/points_structure`
|
||
```json
|
||
// Request
|
||
{ "rangeType": "7d|30d" }
|
||
|
||
// Response
|
||
[
|
||
{
|
||
"category": "任务奖励",
|
||
"amount": 85000,
|
||
"percentage": 45.2,
|
||
"trend": "+12.5%"
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
### 4.3 实时播报接口 (Live Stream)
|
||
|
||
#### 8. 实时中奖播报 `GET /admin/dashboard/live_winners`
|
||
```json
|
||
// Request
|
||
{ "sinceId": 0, "limit": 20 }
|
||
|
||
// Response
|
||
{
|
||
"list": [
|
||
{
|
||
"id": 12345,
|
||
"nickname": "用户昵称",
|
||
"avatar": "头像URL",
|
||
"issueName": "活动期名称",
|
||
"prizeName": "奖品名称",
|
||
"isBigWin": true,
|
||
"createdAt": "刚刚"
|
||
}
|
||
],
|
||
"stats": {
|
||
"hourlyWinRate": 4.2, // 近1小时爆率
|
||
"drawsPerMinute": 128 // 连抽频率
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 五、疑问澄清
|
||
|
||
### 5.1 需要确认的问题
|
||
|
||
1. **风险事件监控**: 目前系统是否有用户行为日志表可供分析？如果没有，是否需要先创建相关基础设施？
|
||
|
||
2. **库存预警阈值**: 库存预警的阈值应该从哪里获取？是固定配置还是每个商品可单独设置？
|
||
|
||
3. **积分经济统计范围**: 积分发行/消耗是否需要区分来源类型（任务奖励、抽奖中奖、兑换消耗等）？
|
||
|
||
4. **实时播报频率**: 前端轮询间隔建议设为多少？3秒是否合适？
|
||
|
||
---
|
||
|
||
## 六、边界与限制
|
||
|
||
### 6.1 任务边界
|
||
- ✅ 补充后端缺失的运营分析接口
|
||
- ✅ 实现积分经济相关接口
|
||
- ✅ 实现库存预警和风险监控接口
|
||
- ✅ 更新前端API调用从Mock数据改为真实后端调用
|
||
- ❌ 不涉及前端UI重构
|
||
- ❌ 不涉及权限管理改动
|
||
|
||
### 6.2 依赖关系
|
||
- 依赖现有数据库表: `users`, `orders`, `user_points_logs`, `coupons`, `user_coupons`, `prizes`, `draw_logs` 等
|
||
- 可能需要新增数据库视图或缓存层以提高查询性能
|
||
|
||
---
|
||
|
||
## 七、预期验收标准
|
||
|
||
1. 所有前端Mock数据的接口均已替换为真实后端调用
|
||
2. 后端接口响应格式与前端类型定义一致
|
||
3. 各项统计数据计算逻辑准确
|
||
4. 查询性能在可接受范围内（响应时间 < 500ms）
|