feat: add learning leaderboards

docs/refactor/taro-frontend-integration.md

@@ -159,6 +159,7 @@ tenant:<tenantId>:theme
 | 错题复习 | `GET /api/learning/wrong-questions/review-plan`、`POST /api/learning/practice-sessions` with `mode=wrong_review` |
 | 收藏夹 | `GET/POST /api/learning/favorites/questions` |
 | 练习历史/统计 | `GET /api/learning/practice-sessions/history`、`GET /api/learning/stats`、`GET /api/learning/trend` |
+| 学习排行榜 | `GET /api/learning/leaderboard?metric=questions&period=all` |
 | 题目视频 | `GET /api/questions/{questionId}/videos`、`POST /api/questions/videos/batch`、`POST /api/videos/play` |
 | 题目反馈 | `POST /api/profile/feedbacks`、`GET /api/profile/feedbacks` |
 | 背单词 | `/api/catalog/vocabulary-units`、`/api/catalog/vocabulary-words` |
@@ -302,6 +303,7 @@ tenant:<tenantId>:theme
 | 学习概览卡片 | `GET /api/learning/stats?days=30` | 返回总答题、正确率、报告数、错题数、收藏数、题型分布 |
 | 正确率趋势图 | `GET /api/learning/trend?days=14` | 返回每日答题数、正确数、错题数、session 数、报告数 |
 | 错题复习入口 | `GET /api/learning/wrong-questions/review-plan?limit=20` | 返回建议复习题和后端组卷 nextAction |
+| 排行榜 | `GET /api/learning/leaderboard?metric=questions&period=7d&regionId=...&classId=...` | 返回排名、用户展示信息、当前用户排名和范围信息 |
 
 错题复习创建 session：
 
@@ -319,6 +321,22 @@ tenant:<tenantId>:theme
 - 收藏夹复习同理可调用 `POST /api/learning/practice-sessions`，body 为 `{ "mode": "favorite_review", "questionLimit": 20 }`。
 - 趋势图以接口返回日期桶为准，缺失日期后端会补 0，不需要前端补点。
 
+### 排行榜
+
+排行榜由后端统一聚合，前端不要读取答题记录、单词进度或模考报告后自行排名，避免越权、口径漂移和跨租户数据泄露。
+
+可选参数：
+
+| 参数 | 可选值 | 说明 |
+| --- | --- | --- |
+| `metric` | `questions`、`score`、`vocabulary`、`mock_exam` | 分别表示累计答题、积分、掌握单词、模考最高分 |
+| `period` | `all`、`7d`、`30d` | 统计周期 |
+| `regionId` | UUID | 地区范围，可选 |
+| `classId` | UUID | 班级范围，可选，后端按当前租户校验 |
+| `limit` / `page` | 正整数 | 分页 |
+
+响应会包含 `items` 和 `currentUser`。即使当前用户未进入前 N 名，也应优先展示 `currentUser` 作为“我的排名”。后台后续会补日/周榜预聚合和防刷策略，前端只消费接口返回口径。
+
 ### 背单词计划与复习上报
 
 背单词页面分三类数据：单元列表、每日计划、单词进度。前端不需要计算下次复习日期，只提交“认识/不认识”，由后端统一更新 `nextReviewDate`、连续正确、掌握状态和每日复习计划。