feat: add mock exam reports

docs/refactor/backend-capability-status.md

@@ -57,7 +57,7 @@
 | 错题本 | 可联调 | `/api/learning/wrong-questions` |
 | 收藏夹 | 可联调 | `/api/learning/favorites/questions` |
 | 免费用户题量限制 | 可联调 | `practice_daily_usage` + `practice_access_events`；支持内容 accessRules、每日额度、session 截断、SVIP-only 拦截 |
-| 模考交卷报告 | 待补齐 | 已有 session/answer 基础，缺完整交卷、评分报告、错题解析汇总 |
+| 模考交卷报告 | 可联调 | `POST /api/learning/practice-sessions/submit`、`GET /api/learning/practice-sessions/report`、`GET /api/learning/practice-reports`；后端按 session 快照评分、分段统计、错题解析汇总，重复提交幂等 |
 
 ## 背单词、知识手册、分数线、视频
 

docs/refactor/legacy-feature-gap-matrix.md

@@ -22,7 +22,7 @@
 | 多级分类树 | 旧 module/subject/category 树 | 已覆盖 | 新后端支持任意深度和 `marker_type`；前端不要写死层级 |
 | 顺序刷题 | `pages/Quiz.tsx` | 已覆盖 | 免费额度/SVIP 校验已由后端强制；继续补断点续练、更多题型渲染 |
 | 随机刷题 | `pages/Quiz.tsx` | 已覆盖 | 已有 blueprint/session 快照和访问控制，前端需按 mode 调用 |
-| 全真模拟 | `components/AdminMockexam`、`MockExamConfigModal.tsx` | 部分覆盖 | 后端有 blueprint 基础；缺完整交卷报告、排名、复盘 |
+| 全真模拟 | `components/AdminMockexam`、`MockExamConfigModal.tsx` | 部分覆盖 | blueprint、session 快照、交卷评分、分段统计和错题解析汇总已覆盖；后续补排名、断点续练、复盘体验 |
 | 错题本 | 用户 stats/错题逻辑 | 已覆盖 | 后续补错题复习计划 |
 | 收藏夹 | `WordFavoritesPage.tsx`、题目收藏 | 已覆盖 | 题目和单词收藏已有 |
 | 题目视频 | `VideoPlayer.tsx` | 部分覆盖 | 题目视频查询、播放签名、SVIP/次数扣减、播放日志已有；缺深度防盗链、动态水印、播放统计报表 |

docs/refactor/next-development-todo.md

@@ -8,12 +8,13 @@
 
 - Supabase/PostgreSQL 多租户 schema、RLS、索引、触发器。
 - Node.js API 分层：`core/features`。
-- 学生端核心 API：题库、练习、答题、错题、收藏、背单词、知识手册、分数线、视频播放签名、资料、订单、权益、个人中心。
+- 学生端核心 API：题库、练习、答题、模考交卷报告、错题、收藏、背单词、知识手册、分数线、视频播放签名、资料、订单、权益、个人中心。
 - 租户后台 API：品牌、域名、设置、支付账户、登录 provider、私密密钥、活动、激活码、优惠券、成员权限、审计、内容管理。
 - 平台后台 API：租户、SaaS 套餐、订阅、账单、服务费收款、用量。
 - 销售/代理/CRM 增长链路：邀请码、扫码事件、首绑保护、团队、统计、CRM 队列。
 - 内容导航：`content_entries/content_nodes` 支持任意深度入口和分类。
 - 练习组卷：`question_collections/practice_blueprints` 支持顺序、随机、全真模拟快照。
+- 模考报告：`practice_session_reports/practice_session_report_sections` 支持交卷、评分、题型/小节统计、错题解析汇总和历史查询。
 - 练习访问控制：`practice_daily_usage/practice_access_events` 支持免费每日额度、SVIP 范围校验、SVIP-only 内容拦截和答题 session 快照保护。
 - 内容导入：题目、单词、知识手册 JSON 预览、校验、导入、幂等、审计。
 - 本地验证：`npm run check:refactor` 已通过。
@@ -77,10 +78,10 @@
    - 单题视频和通用知识视频混合推荐。
 
 6. 学习统计
-   - 已完成免费额度和练习访问事件基础。
+   - 已完成免费额度、练习访问事件、模考交卷评分报告基础。
    - 继续补练习历史、正确率趋势、题型分布、错题复习计划。
    - 单词复习算法、每日计划、排行榜。
-   - 模考交卷、评分报告、错题解析汇总。
+   - 模考排名、断点续练、复盘体验。
 
 7. 数据看板
    - 收益、注册趋势、答题次数、收入趋势、题型分布、科目数量、题目总量。

docs/refactor/taro-frontend-integration.md

@@ -137,6 +137,7 @@ tenant:<tenantId>:theme
 | 题目列表 | `/api/catalog/question-collections`、`/api/catalog/question-collections/questions` |
 | 开始练习 | `POST /api/learning/practice-sessions` |
 | 提交答案 | `POST /api/learning/answers` |
+| 交卷/报告 | `POST /api/learning/practice-sessions/submit`、`GET /api/learning/practice-sessions/report`、`GET /api/learning/practice-reports` |
 | 错题本 | `GET /api/learning/wrong-questions`、`POST /api/learning/wrong-questions/resolve` |
 | 收藏夹 | `GET/POST /api/learning/favorites/questions` |
 | 题目视频 | `GET /api/questions/{questionId}/videos`、`POST /api/questions/videos/batch`、`POST /api/videos/play` |
@@ -197,6 +198,70 @@ tenant:<tenantId>:theme
 - `PRACTICE_SESSION_QUESTION_FORBIDDEN`：说明提交答案的题目不在本次 session 快照内，应清理本地异常进度并重新开始。
 - 提交答案必须传 `practiceSessionId`；后端会拒绝不属于本人有效 session 的题目。
 
+### 模考交卷与报告
+
+全真模拟、试卷模式、顺序练习的最终报告都走后端交卷接口。前端不得传分数、正确数或题目范围；后端只信任 `practice_sessions.question_ids` 快照和 `answer_records` 最新答题记录。
+
+交卷请求：
+
+```json
+{
+  "practiceSessionId": "00000000-0000-0000-0000-000000000000"
+}
+```
+
+响应关键字段：
+
+```json
+{
+  "item": {
+    "id": "...",
+    "practiceSessionId": "...",
+    "mode": "mock_exam",
+    "totalQuestions": 3,
+    "answeredCount": 2,
+    "correctCount": 1,
+    "wrongCount": 1,
+    "unansweredCount": 1,
+    "score": 2,
+    "totalScore": 100,
+    "accuracy": 0.3333,
+    "sectionStats": [
+      {
+        "key": "choice",
+        "title": "单选题",
+        "questionCount": 3,
+        "correctCount": 1,
+        "score": 2,
+        "totalScore": 6
+      }
+    ],
+    "wrongQuestionIds": ["..."],
+    "questionResults": [
+      {
+        "questionId": "...",
+        "sectionKey": "choice",
+        "answered": true,
+        "isCorrect": false,
+        "score": 0,
+        "totalScore": 2,
+        "selectedOptions": ["0"],
+        "correctOptionIndices": [1],
+        "explanation": "..."
+      }
+    ]
+  }
+}
+```
+
+前端处理规则：
+
+- 重复交卷是幂等的，后端会返回同一份报告。
+- 报告页刷新时调用 `GET /api/learning/practice-sessions/report?practiceSessionId=...`。
+- 个人中心/模考历史调用 `GET /api/learning/practice-reports?mode=mock_exam&limit=20`，也可以传 `blueprintId` 筛选某套模拟卷。
+- `score` 是逐题得分合计；`totalScore` 保留后台配置的卷面总分。测试或预发数据题量不足时，两者不一定按百分制等比换算，前端展示时不要自行重算。
+- 错题复盘优先使用 `wrongQuestionIds` 和 `questionResults`，题目详情仍可按现有题目接口或 session 快照加载。
+
 ## 视频播放契约
 
 题目视频分为 `free`、`svip`、`video_quota` 三种访问模式。列表接口只用于展示标题、封面、时长、访问模式和试看秒数；除免费公开视频外，列表和搜索接口不会返回可播放 URL。