wenzi/specs/002-data-analytics/plan.md

实施计划: 002 - 数据与分析

本文档为“数据与分析”功能规格的技术实施计划。

1. 总体思路

数据分析功能对性能有较高要求。为避免实时计算带来的延迟，核心指标将通过定时任务进行预聚合。前端将使用专业的图表和网络图库来提供丰富的可视化效果。

2. 后端开发任务 (Backend Tasks)

2.1. 数据处理与存储

• 创建预聚合统计表:
  • 新建 daily_activity_stats 表，字段包括 activity_id, date, pv, uv, participants, new_registrations, k_factor, total_rewards_cost。
• 开发定时任务 (Cron Job):
  • 创建一个每日执行的定时任务，用于计算前一天的各项核心指标，并填充到 daily_activity_stats 表中。
• 缓存策略:
  • 为“超级传播者榜单”的查询结果设置缓存（如 Redis，缓存时间5-10分钟），以降低数据库压力。

技术选型说明: 裂变网络图的查询，V1.0阶段可通过SQL的递归查询（CTE）实现。若未来性能遇到瓶颈，可考虑引入图数据库（如 Neo4j）进行优化。

2.2. API Endpoint 设计

• GET /api/v1/activities/{id}/stats: 获取仪表盘数据

  • Query Params: start_date, end_date。
  • Logic: 从 daily_activity_stats 表中查询指定时间范围的数据。

• GET /api/v1/activities/{id}/graph: 获取裂变网络图数据

  • Query Params: center_user_id, depth。
  • Logic: 根据中心用户ID，递归查询指定深度的上下级关系并返回节点和边的集合。

• GET /api/v1/activities/{id}/leaderboard: 获取超级传播者榜单

  • Query Params: sort_by (enum: direct, total), page, limit。
  • Logic: 执行排序和分页查询，优先从缓存读取。

• GET /api/v1/activities/{id}/leaderboard/export: 导出榜单

  • Logic: 查询完整榜单数据，生成CSV格式的文件流并返回。

3. 前端开发任务 (Frontend Tasks)

3.1. UI 组件设计

• AnalyticsDashboard.vue: 数据分析页面的主容器，包含日期选择器和各个图表/榜单组件。
• DateRangePicker.vue: 可复用的日期范围选择组件，包含预设（昨天、过去7天等）和自定义范围功能。
• StatsChart.vue: 使用 ECharts for Vue 库，将核心指标以折线图或柱状图的形式进行可视化展示。
• NetworkGraphViewer.vue: 使用 Vue Flow 库，渲染网络图。需要实现节点的懒加载、点击展开、缩放和平移功能。
• LeaderboardTable.vue: 可排序的表格组件，包含排序切换控件和“导出CSV”按钮。

3.2. API 集成

• 在API客户端模块中新增上述4个数据相关接口的请求函数。
• 在 AnalyticsDashboard.vue 组件中统一管理数据获取、加载状态和错误处理，并将数据分发给各个子组件。