feat: add point activities and exchange

docs/refactor/taro-frontend-integration.md

@@ -266,7 +266,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 /api/profile/badges` |
+| 个人中心 | `GET/PATCH /api/profile/me`、`POST /api/profile/check-in`、`GET /api/profile/score-events`、`GET /api/profile/exam-countdowns`、`GET /api/profile/badges`、`GET /api/profile/activity-tasks`、`POST /api/profile/activity-tasks/claim`、`GET /api/profile/exchange-items`、`POST /api/profile/exchange-items/redeem` |
 | 销售分享 | `/api/referral/resolve`、`track-event`、`bind` |
 | 租户数据看板 | `GET /api/tenant-admin/dashboard?timeRange=30d&regionId=...` |
 | 租户主题模板 | `GET /api/tenant-admin/theme-templates`、`GET /api/tenant-admin/theme`、`POST /api/tenant-admin/theme/preview`、`POST /api/tenant-admin/theme/publish` |
@@ -279,6 +279,7 @@ tenant:<tenantId>:theme
 | 租户考试日期 | `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/PUT /api/tenant-admin/point-activity-tasks`、`GET /api/tenant-admin/point-activity-claims`、`GET/PUT /api/tenant-admin/point-exchange-items`、`GET /api/tenant-admin/point-exchange-orders` |
 | 公共题库采纳/同步 | `GET /api/tenant-content/public-question-banks`、`POST /api/tenant-content/public-question-banks/adopt`、`POST /api/tenant-content/public-question-banks/sync`、`GET /api/tenant-content/public-question-banks/conflicts?adoptionId=...`、`POST /api/tenant-content/public-question-banks/conflicts/resolve`、`POST /api/tenant-content/public-question-banks/conflicts/resolve-batch` |
 | 题库导出 | `POST /api/tenant-content/exports/questions`、`GET /api/tenant-content/exports/jobs` |
 | 资料/视频运营审计 | `GET /api/tenant-content/media-analytics/summary`、`asset-events`、`video-events` |
@@ -654,8 +655,9 @@ POST /api/tenant-admin/badge-grants
 | unlockType | 推荐 conditionField | 触发时机 |
 | --- | --- | --- |
 | `check_in` | `checkInStreak` | `POST /api/profile/check-in` 真实签到成功后 |
-| `score` | `score` | 签到加分或反馈奖励积分成功后 |
+| `score` | `score` | 签到加分、反馈奖励或积分活动奖励成功后 |
 | `feedback_resolved` | `feedbackResolvedCount` | 租户后台把反馈处理为 `resolved` 后 |
+| `activity_reward` | `activityRewardCount` 或 `score` | 学生领取积分活动任务且后端证据校验通过后 |
 
 规则使用 `conditionOperator` 的合法值 `gte`、`gt`、`lte`、`lt`、`eq`；`conditionValue` 为数字。触发成功的接口会返回 `autoBadges`，前端可据此弹出“获得勋章”提示；如果是重复签到、重复处理反馈或已获得过同一勋章，后端不会重复返回同一发放记录。
 
@@ -1149,6 +1151,43 @@ POST /api/profile/check-in
 - 积分最终余额以后端 `score` 和流水为准，前端只做展示。
 - 如响应包含 `autoBadges`，可展示获得勋章弹层；不要在前端根据连续天数或积分自行判断勋章是否解锁。
 
+积分活动任务和积分兑换入口：
+
+```http
+GET  /api/profile/activity-tasks
+POST /api/profile/activity-tasks/claim
+GET  /api/profile/exchange-items
+POST /api/profile/exchange-items/redeem
+```
+
+`POST /api/profile/activity-tasks/claim` 示例：
+
+```json
+{
+  "taskId": "<taskId>",
+  "sourceId": "<practiceSessionId 或 vocabularyReviewId，可选>",
+  "idempotencyKey": "activity-claim-20260629-001"
+}
+```
+
+`POST /api/profile/exchange-items/redeem` 示例：
+
+```json
+{
+  "itemId": "<exchangeItemId>",
+  "quantity": 1,
+  "idempotencyKey": "exchange-20260629-001"
+}
+```
+
+前端处理规则：
+
+- 积分任务领取、积分扣减、库存扣减、个人限购、优惠券兑换履约都由后端事务处理。
+- `practice_complete`、`mock_exam_submit`、`vocabulary_review` 等任务需要传 `sourceId`，后端会校验证据属于当前学生当前租户。
+- `feedback_resolved` 等系统流程任务禁止学生自领，前端应展示为“系统发放”或不展示领取按钮。
+- 兑换返回 `order` 和最新积分余额后，再刷新 `profile/me`、`score-events` 和兑换列表；不要在本地先扣积分。
+- 如果响应包含 `autoBadges`，按获得勋章提示处理；重复领取、库存不足、积分不足、限购等错误按后端 `code` 展示业务提示。
+
 题目页、资料页或视频页可提交反馈：
 
 ```json
@@ -2393,11 +2432,11 @@ src/components/RichContent.tsx 安全富文本渲染：题干、选项、解析
 src/services/catalog.ts    目录、题库、单词、手册、分数线、资料
 src/services/learning.ts   练习 session、答题、收藏、错题/收藏复习、交卷报告、单词复习和单词收藏列表
 src/services/commerce.ts   套餐、优惠券、下单、支付参数、订单详情、权益、激活码
-src/services/profile.ts    个人中心、地区目标、签到、反馈、勋章、倒计时
+src/services/profile.ts    个人中心、地区目标、签到、反馈、勋章、倒计时、积分活动任务、积分兑换
 src/services/video.ts      题目视频列表、播放签名
 src/services/ai.ts         AI 择校推荐生成、报告列表、报告详情
 src/services/pronunciation.ts H5/小程序单词发音适配
-src/services/tenantAdmin.ts 租户后台看板、权限矩阵、成员、学生创建/批量导入/分班/备注/跟进、内容、营销、设置、角色模板写操作、公共题库采纳/同步/单条和批量冲突处理、导入详情/复检、CRM 配置/队列、分佣规则/成员比例/订单/结算、优惠券规则/核销报表
+src/services/tenantAdmin.ts 租户后台看板、权限矩阵、成员、学生创建/批量导入/分班/备注/跟进、内容、营销、设置、角色模板写操作、公共题库采纳/同步/单条和批量冲突处理、导入详情/复检、CRM 配置/队列、分佣规则/成员比例/订单/结算、优惠券规则/核销报表、积分任务/兑换配置和记录
 src/services/tenantFinance.ts 租户财务运营：退款状态机、官方账单任务、对账批次/明细、差错工单、异常订单和人工调整凭证
 src/services/platformAdmin.ts 平台后台租户、套餐账单、用量、公共题库授权
 ```
@@ -2415,8 +2454,8 @@ npm run build:taro:h5:platform
 
 下一批前端开发重点：
 
-- 学生端：地区选择、题目视频播放、题目反馈、错题/收藏专题页、模考交卷报告、收银台、订单详情、售后入口、题干/解析/知识手册 RichContent 安全渲染、逐题复盘、背单词卡片学习/发音/收藏练习、资料短签名水印预览/下载确认已接第一版；下一批继续补真正 KaTeX/小程序公式方案、私有题图签名资源映射、背单词更细统计、小程序支付容器和分享场景。
-- 租户后台：工作台已接权限驱动模块入口；学生运营页已接学生创建/更新、禁用/恢复、批量导入、批量分班、学生备注、跟进任务和完成跟进第一版；题库内容页已接公共题库采纳/同步、冲突查看、单条/批量采纳平台或保留本地、导入问题、模板预览/下载、异步任务轮询和导入后复检第一版；营销中心已接 CRM 配置保存、CRM 队列按状态查看、分佣默认规则、成员分佣比例、分佣订单明细、结算单生成、审核通过/驳回、标记线下打款、优惠券规则表单、筛选、核销明细和核销报表第一版；财务运营页已接退款申请/审核/供应商提交与查询、官方账单任务、对账批次/异常明细、差错工单处理、人工调整凭证提交/复核和异常订单运营台第一版；租户设置页已接主题模板、草稿预览、发布、角色模板创建、编辑、停用、权限点、菜单、模块、字段、基础数据范围、成员搜索/新建、成员绑定模板、成员状态和额外权限覆盖第一版；下一批继续补更精细的学生导入模板体验、真实生产账单抽样验收、真实打款 provider、发票、更细数据范围 UI 和主题素材库。
+- 学生端：地区选择、题目视频播放、题目反馈、错题/收藏专题页、模考交卷报告、收银台、订单详情、售后入口、题干/解析/知识手册 RichContent 安全渲染、逐题复盘、背单词卡片学习/发音/收藏练习、资料短签名水印预览/下载确认和积分任务/兑换 service 已接第一版；下一批继续补积分任务/兑换页面 UI、真正 KaTeX/小程序公式方案、私有题图签名资源映射、背单词更细统计、小程序支付容器和分享场景。
+- 租户后台：工作台已接权限驱动模块入口；学生运营页已接学生创建/更新、禁用/恢复、批量导入、批量分班、学生备注、跟进任务和完成跟进第一版；题库内容页已接公共题库采纳/同步、冲突查看、单条/批量采纳平台或保留本地、导入问题、模板预览/下载、异步任务轮询和导入后复检第一版；营销中心已接 CRM 配置保存、CRM 队列按状态查看、分佣默认规则、成员分佣比例、分佣订单明细、结算单生成、审核通过/驳回、标记线下打款、优惠券规则表单、筛选、核销明细、核销报表、积分任务和积分兑换 service 第一版；财务运营页已接退款申请/审核/供应商提交与查询、官方账单任务、对账批次/异常明细、差错工单处理、人工调整凭证提交/复核和异常订单运营台第一版；租户设置页已接主题模板、草稿预览、发布、角色模板创建、编辑、停用、权限点、菜单、模块、字段、基础数据范围、成员搜索/新建、成员绑定模板、成员状态和额外权限覆盖第一版；下一批继续补积分任务/兑换操作台页面、更精细的学生导入模板体验、真实生产账单抽样验收、真实打款 provider、发票、更细数据范围 UI 和主题素材库。
 - 平台后台：租户创建、状态变更、订阅开通、账单生成、人工收款确认、用量录入、公共题库授权编辑已接第一版；继续补租户详情/编辑、平台审计、自动计费和批量账单操作。
 - 小程序：验证 `Taro.login`、微信支付、分享 scene/referral、Supabase client 兼容性；如不稳定，保留 `apps/api/auth/*` 作为小程序登录适配层。
 
@@ -2516,7 +2555,7 @@ GET /api/ai/school-recommendations/detail?reportId=<reportId>
 - 内容入口/分类树/题目集合/练习蓝图
 - 题目/单词/知识手册/分数线/视频维护
 - 题目/单词/知识手册/分数线/视频 JSON/CSV/Excel 导入 preview/import/issues、字段映射、模板下载和导入后复检
-- Banner/FAQ/公告/激活码/优惠券，当前 Taro 租户营销中心已接 `GET/PUT /api/tenant-admin/coupons`、`GET /api/tenant-admin/coupons/redemptions`、`GET /api/tenant-admin/coupons/report`，用于配置复杂规则、查看核销明细和活动效果。
+- Banner/FAQ/公告/激活码/优惠券/积分任务/积分兑换，当前 Taro 租户营销中心已接 `GET/PUT /api/tenant-admin/coupons`、`GET /api/tenant-admin/coupons/redemptions`、`GET /api/tenant-admin/coupons/report` 以及积分任务/兑换 service 方法，用于配置复杂规则、查看核销明细、活动效果、任务领取和兑换记录。
 - 勋章：`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`