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

后台工作台页面接口分析

一、原始需求

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

二、项目特性规范

技术栈

• 前端: 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 fetchPointsTrend fetchPointsStructure	⚠️ Mock数据	需要实现3个接口

---

四、需要补充的后端接口清单

4.1 运营分析接口 (Operations)

1. 产品动销排行 GET /admin/operations/product_performance

// 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

// 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

// 无请求参数

// Response
[
  {
    "id": 101,
    "name": "商品名称",
    "type": "physical|virtual|coupon",
    "stock": 3,
    "threshold": 5,
    "salesSpeed": 1.2  // 日均消耗速度
  }
]

4. 风险事件监控 GET /admin/operations/risk_events

// 无请求参数

// 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

// Request
{ "rangeType": "7d|30d" }

// Response
{
  "totalIssued": 1258400,     // 发行总积分
  "totalConsumed": 985600,    // 消耗总积分
  "netChange": 272800,        // 净变化
  "activeUsersWithPoints": 5640, // 持分活跃用户数
  "conversionRate": 78.5      // 活跃持仓率%
}

6. 积分趋势 GET /admin/operations/points_trend

// 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

// Request
{ "rangeType": "7d|30d" }

// Response
[
  {
    "category": "任务奖励",
    "amount": 85000,
    "percentage": 45.2,
    "trend": "+12.5%"
  }
]

---

4.3 实时播报接口 (Live Stream)

8. 实时中奖播报 GET /admin/dashboard/live_winners

// 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）