feat: manage tenant badges

docs/refactor/taro-frontend-integration.md

@@ -172,7 +172,7 @@ tenant:<tenantId>:theme
 | 商城 | `/api/catalog/svip-plans`、`POST /api/commerce/coupons/claim`、`POST /api/commerce/orders`、`POST /api/commerce/payments/create` |
 | 订单/权益 | `/api/commerce/orders`、`/api/commerce/orders/detail`、`/api/commerce/orders/status`、`/api/commerce/entitlements` |
 | 激活码 | `POST /api/commerce/activation-codes/check`、`POST /api/commerce/activation-codes/redeem` |
-| 个人中心 | `GET/PATCH /api/profile/me`、`POST /api/profile/check-in`、`GET /api/profile/score-events`、`GET /api/profile/exam-countdowns` |
+| 个人中心 | `GET/PATCH /api/profile/me`、`POST /api/profile/check-in`、`GET /api/profile/score-events`、`GET /api/profile/exam-countdowns`、`GET /api/profile/badges` |
 | 销售分享 | `/api/referral/resolve`、`track-event`、`bind` |
 | 租户数据看板 | `GET /api/tenant-admin/dashboard?timeRange=30d&regionId=...` |
 | 租户班级 | `GET/PUT /api/tenant-admin/classes`、`POST /api/tenant-admin/classes/disable` |
@@ -183,6 +183,7 @@ tenant:<tenantId>:theme
 | 租户教师 | `GET /api/tenant-admin/teachers` |
 | 租户考试日期 | `GET/PUT /api/tenant-admin/exam-dates` |
 | 租户反馈处理 | `GET /api/tenant-admin/feedbacks`、`POST /api/tenant-admin/feedbacks/status`、`GET /api/tenant-admin/feedbacks/events` |
+| 租户勋章 | `GET/PUT /api/tenant-admin/badges`、`GET/POST /api/tenant-admin/badge-grants` |
 | 公共题库采纳 | `GET /api/tenant-content/public-question-banks`、`POST /api/tenant-content/public-question-banks/adopt` |
 
 ## 练习访问控制契约
@@ -230,6 +231,31 @@ tenant:<tenantId>:theme
 - `PRACTICE_SESSION_QUESTION_FORBIDDEN`：说明提交答案的题目不在本次 session 快照内，应清理本地异常进度并重新开始。
 - 提交答案必须传 `practiceSessionId`；后端会拒绝不属于本人有效 session 的题目。
 
+## 勋章
+
+学生个人中心或学习成就页调用：
+
+```text
+GET /api/profile/badges?includeLocked=true&category=practice
+```
+
+说明：
+
+- `includeLocked=true` 时返回已解锁和未解锁勋章；不传时只返回已解锁。
+- `category` 可选：`learning`、`practice`、`vocabulary`、`mock_exam`、`activity`、`feedback`、`sales`、`system`、`custom`。
+- 前端只展示后端返回的 `unlocked/grantId/grantedAt`，不要在本地自行认定用户已经获得勋章。
+
+租户后台勋章管理：
+
+```text
+GET  /api/tenant-admin/badges?category=practice&includeInactive=true
+PUT  /api/tenant-admin/badges
+GET  /api/tenant-admin/badge-grants?userId=...&badgeId=...
+POST /api/tenant-admin/badge-grants
+```
+
+`PUT /api/tenant-admin/badges` 支持同租户内 `legacyId` 幂等更新；如果 `id` 与 `legacyId` 指向不同记录会返回 `BADGE_ID_CONFLICT`。`POST /api/tenant-admin/badge-grants` 对同一用户同一勋章幂等，不会重复生成多条发放记录。当前后端支持手动发放，自动发放规则后续由 worker/事件流补齐。
+
 ### 模考交卷与报告
 
 全真模拟、试卷模式、顺序练习的最终报告都走后端交卷接口。前端不得传分数、正确数或题目范围；后端只信任 `practice_sessions.question_ids` 快照和 `answer_records` 最新答题记录。
@@ -1040,7 +1066,7 @@ ACTIVATION_CODE_REGION_MISMATCH
 9. `pages/scoreline/index`
    - 动态字段筛选和趋势。
 10. `pages/profile/index`
-   - 会员、订单、激活码、学习数据。
+   - 会员、订单、激活码、学习数据、勋章。
 
 ## 租户后台前端建议
 
@@ -1057,6 +1083,7 @@ ACTIVATION_CODE_REGION_MISMATCH
 - 题目/单词/知识手册/分数线/视频维护
 - 题目/单词/知识手册/分数线/视频 JSON 导入 preview/import/issues
 - Banner/FAQ/公告/激活码/优惠券
+- 勋章：`GET/PUT /api/tenant-admin/badges`、`GET/POST /api/tenant-admin/badge-grants`
 - 考试日期：`GET/PUT /api/tenant-admin/exam-dates`
 - 题目反馈：`GET /api/tenant-admin/feedbacks`、`POST /api/tenant-admin/feedbacks/status`、`GET /api/tenant-admin/feedbacks/events`
 - 销售/代理/CRM 队列