# 后台工作台页面接口分析

## 一、原始需求
分析后台工作台页面的所有设计，确定需要对应哪些接口，并补充后端缺失的接口实现。

## 二、项目特性规范

### 技术栈
- **前端**: 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）