更新 API 参考文档对齐游戏化变更

- 排行榜响应新增 meta 字段含周信息/分组/奖励预览
- xp 改为本周 XP，说明排名基于 20-30 人分组
- 广告恢复 session 新增 Plus 用户 subscriptionBenefits 响应
- 标注旧恢复接口已废弃，指向 session+complete 两步流程

docs/api-reference.md

@@ -440,13 +440,24 @@
       "userId": "uuid",
       "displayName": "玩家昵称",
       "avatarUrl": null,
-      "xp": 5000,
-      "badge": "王者",
+      "xp": 500,
+      "badge": "榜首",
       "isMe": false
     }
   ],
+  "meta": {
+    "weekStart": "2026-05-11",
+    "weekEnd": "2026-05-17",
+    "nextRefreshAt": "2026-05-18",
+    "groupId": "week-2026-05-11-group-1",
+    "rewardPreview": [
+      { "rank": 1, "coins": 300 },
+      { "rank": 2, "coins": 150 },
+      { "rank": 3, "coins": 50 }
+    ]
+  },
   "pagination": {
-    "total": 100,
+    "total": 25,
     "page": 1,
     "limit": 20
   },
@@ -454,6 +465,8 @@
 }
 ```
 
+> `xp` 为本周累计 XP（非全局累计），排名基于用户所在 20-30 人分组内。`meta.rewardPreview` 展示各组前 3 名的金币奖励，激励用户冲榜。
+
 #### GET /leaderboards/me
 
 认证：JWT
@@ -466,14 +479,26 @@
 {
   "success": true,
   "data": {
-    "rank": 15,
+    "rank": 3,
     "userId": "uuid",
     "displayName": "我",
     "avatarUrl": null,
-    "xp": 1500,
-    "badge": "新秀",
+    "xp": 150,
+    "badge": "前三",
     "isMe": true
   },
+  "meta": {
+    "weekStart": "2026-05-11",
+    "weekEnd": "2026-05-17",
+    "nextRefreshAt": "2026-05-18",
+    "groupId": "week-2026-05-11-group-1",
+    "rank": 3,
+    "rewardPreview": [
+      { "rank": 1, "coins": 300 },
+      { "rank": 2, "coins": 150 },
+      { "rank": 3, "coins": 50 }
+    ]
+  },
   "error": null
 }
 ```
@@ -701,6 +726,27 @@
 }
 ```
 
+Plus 用户响应（无需看广告，返回订阅权益摘要）：
+
+```json
+{
+  "success": true,
+  "data": {
+    "sessionId": null,
+    "eligible": false,
+    "reason": "already_subscribed",
+    "subscriptionBenefits": {
+      "tier": "pro",
+      "unlimitedHearts": true,
+      "dailyHighRewardSessions": null
+    }
+  },
+  "error": null
+}
+```
+
+> `subscriptionBenefits.dailyHighRewardSessions` 为 `null` 表示无限制。客户端可据此展示替代提示，引导用户享受订阅权益。
+
 #### POST /rewards/ad-recovery/complete
 
 认证：JWT
@@ -772,6 +818,8 @@
 
 `reason` 取值：`ad_not_completed`, `provider_verification_failed`, `session_expired`, `daily_limit_reached`, `cooldown_active`, `already_subscribed`, `invalid_type`。
 
+> 广告恢复奖励通过统一奖励结算层（`rewardLedger`）发放，以 `ad_recovery:{sessionId}` 为幂等 key，记录发放前后资源快照。旧接口 `POST /rewards/hearts/restore`、`POST /rewards/attempts/restore`、`POST /rewards/streak/protect`、`POST /progress/hearts/restore` 已废弃，请使用上述 session + complete 两步流程。
+
 ## 管理端 API
 
 管理端路由统一带 `/v1/admin` 前缀。

docs/gamification-server-plan.md

@@ -119,7 +119,7 @@
 
 | # | 任务 | 状态 | 验收标准 |
 |---|------|------|----------|
-| G6-1 | 更新 `docs/api-reference.md` | [ ] | 文档只保留最终客户端契约，包含挑战组、奖励、商店、背包、周榜、错误码 |
+| G6-1 | 更新 `docs/api-reference.md` | [x] | 文档只保留最终客户端契约，包含挑战组、奖励、商店、背包、周榜、错误码 |
 | G6-2 | 更新 `docs/implementation-plan.md` | [ ] | 将本计划作为 Phase 1d 或 Game Economy 阶段索引进去 |
 | G6-3 | 增加 Admin 配置或只读查看能力 | [ ] | 管理端至少能查看用户金币、道具、奖励流水、广告恢复记录 |
 | G6-4 | 增加 E2E 或集成测试 | [ ] | 覆盖游客登录、完成挑战组、广告恢复、购买道具、周榜查询 |