feat: render rich formulas and signed question media

docs/refactor/frontend-handoff-index.md

@@ -78,7 +78,7 @@
 | 资料 | `apps/taro/src/pages/student/assets/index.tsx` | `assets`、`assets/preview`、`assets/download`；已接短期签名、过期信息、可见水印覆盖、traceId 展示和强制水印资源外部预览限制 |
 | 个人中心 | `apps/taro/src/pages/student/profile/index.tsx` | `profile/me`、`check-in`、`badges`、`exam-countdowns`、`svip-plans`、`orders`、`entitlements`、`activation-codes`、`leaderboard`、`learning/stats`、`learning/trend`、`practice-sessions/history` |
 
-当前页面主要用于打通接口和路由。学生端第一版学习闭环已经覆盖“选地区 -> 进题库 -> 创建 session -> 答题卡/答题/主观题自评/复合题多小题/收藏/反馈/视频 -> 交卷报告逐题复盘 -> 错题/收藏复习”，背单词已经覆盖“单元 -> 今日计划/全单元/收藏练习 -> 卡片翻转 -> 发音 -> 认识/再记上报 -> 本地恢复”，资料页已经覆盖“列表 -> 申请预览/下载短签名 -> 展示水印 traceId -> H5 水印容器预览或确认下载”，个人中心已经覆盖“基础资料 -> 学习报告 -> 14 天趋势 -> 题型表现 -> 最近练习 -> 排名/勋章/签到 -> 会员/订单/激活码”，会员闭环已经覆盖“选套餐 -> 领优惠券 -> 下单 -> 创建支付参数 -> 状态轮询 -> 订单详情/售后入口”。`apps/taro/src/components/RichContent.tsx` 是学生端题干、选项、解析和知识手册的统一安全渲染组件：它只支持受控 Markdown 图片、基础表格、粗体、代码和公式占位，不执行任意 HTML/JS，也会拒绝 `javascript:`、`data:` 等危险图片地址。后续 UI 需要继续按旧题库视觉和 Taro H5/小程序限制优化，并重点补真正 KaTeX/小程序公式方案、私有题图签名资源映射、小程序分享/支付容器体验。
+当前页面主要用于打通接口和路由。学生端第一版学习闭环已经覆盖“选地区 -> 进题库 -> 创建 session -> 答题卡/答题/主观题自评/复合题多小题/收藏/反馈/视频 -> 交卷报告逐题复盘 -> 错题/收藏复习”，背单词已经覆盖“单元 -> 今日计划/全单元/收藏练习 -> 卡片翻转 -> 发音 -> 认识/再记上报 -> 本地恢复”，资料页已经覆盖“列表 -> 申请预览/下载短签名 -> 展示水印 traceId -> H5 水印容器预览或确认下载”，个人中心已经覆盖“基础资料 -> 学习报告 -> 14 天趋势 -> 题型表现 -> 最近练习 -> 排名/勋章/签到 -> 会员/订单/激活码”，会员闭环已经覆盖“选套餐 -> 领优惠券 -> 下单 -> 创建支付参数 -> 状态轮询 -> 订单详情/售后入口”。`apps/taro/src/components/RichContent.tsx` 是学生端题干、选项、解析和知识手册的统一安全渲染组件：它只支持受控 Markdown 图片、基础表格、粗体、代码和被 parser 识别出的公式 token；H5 端用 KaTeX 渲染 `$...$`、`$$...$$`、`\(...\)`、`\[...\]`，私有题图可用 `asset:<uuid>`、`content_asset:<uuid>` 或 `/asset/<uuid>` 资源引用向后端申请短期预览签名。组件不执行导入内容中的任意 HTML/JS，也会拒绝 `javascript:`、`data:` 等危险图片地址。后续 UI 需要继续按旧题库视觉和 Taro H5/小程序限制优化，并重点补小程序公式真机验收、题图资源字段化、小程序分享/支付容器体验。
 
 ## 已落地的 Taro 租户后台页面
 

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

@@ -21,14 +21,14 @@
 | 首页/学生看板 | `pages/StudentDashboardNew.tsx` | 部分覆盖 | 品牌、Banner、公告、FAQ、时间线、考试倒计时、入口、个人统计有基础；缺完整运营动态和学习任务聚合 |
 | 题库入口 | `pages/SubjectSelector.tsx`、`RegionArchitectureEditor.tsx` | 已覆盖 | 前端应改接 `content_entries/content_nodes` |
 | 多级分类树 | 旧 module/subject/category 树 | 已覆盖 | 新后端支持任意深度和 `marker_type`；前端不要写死层级 |
-| 顺序刷题 | `pages/Quiz.tsx` | 部分覆盖 | 免费额度/SVIP 校验、session 快照、练习历史、趋势统计和题目反馈已由后端强制；Taro 已有答题卡、后端 session detail 续练、本地进度恢复、客观题自动提交、主观题后端自评、阅读理解/案例分析多小题作答、题干/选项/解析 RichContent 安全渲染和报告明细第一版；继续补真正 KaTeX/小程序公式方案、图片私有签名资源映射和更完整复盘体验 |
+| 顺序刷题 | `pages/Quiz.tsx` | 部分覆盖 | 免费额度/SVIP 校验、session 快照、练习历史、趋势统计和题目反馈已由后端强制；Taro 已有答题卡、后端 session detail 续练、本地进度恢复、客观题自动提交、主观题后端自评、阅读理解/案例分析多小题作答、题干/选项/解析 RichContent 安全渲染、H5 KaTeX 公式渲染、`content_assets` 私有题图短签名渲染地基和报告明细第一版；继续补小程序公式真机验收、题图资源字段化和更完整复盘体验 |
 | 随机刷题 | `pages/Quiz.tsx` | 部分覆盖 | 已有 blueprint/session 快照、访问控制和历史统计；Taro 已按 session 题目快照渲染第一版，并复用 RichContent 渲染长题干/图片/公式占位；继续补随机刷题状态管理和更完整复盘 |
 | 全真模拟 | `components/AdminMockexam`、`MockExamConfigModal.tsx` | 部分覆盖 | blueprint、session 快照、倒计时、交卷评分、分段统计、错题解析汇总、逐题复盘第一版和复合题子题部分得分已覆盖；后续补排行榜/排名、完整复盘体验 |
 | 错题本 | 用户 stats/错题逻辑 | 已覆盖 | 错题列表、移出错题、复习计划和 `wrong_review` 后端组卷已覆盖；后续补更细的间隔复习算法 |
 | 收藏夹 | `WordFavoritesPage.tsx`、题目收藏 | 已覆盖 | 题目和单词收藏已有 |
 | 题目视频 | `VideoPlayer.tsx` | 部分覆盖 | 题目视频查询、播放签名、SVIP/次数扣减、播放日志和动态水印上下文已有；缺深度防盗链、转码级水印、播放统计报表 |
 | 背单词 | `VocabularyPage.tsx`、`VocabularyQuiz.tsx` | 部分覆盖 | 单词列表、进度、收藏、统计、每日计划、后端复习调度、Taro 卡片翻转、上一个/下一个、跳转、发音、美/英音切换、收藏练习和本地进度恢复第一版已覆盖；后续补租户级发音源配置、收藏专项统计、排行榜运营看板和更精细的间隔算法参数 |
-| 知识手册 | `Handbook*.tsx` | 已覆盖 | Taro 已接手册科目/章节/条目和 RichContent 安全渲染第一版；后续补搜索、高亮、目录锚点、真正公式渲染和图片私有资源签名映射 |
+| 知识手册 | `Handbook*.tsx` | 已覆盖 | Taro 已接手册科目/章节/条目、RichContent 安全渲染、H5 KaTeX 公式渲染和私有资源 ID 短签名地基第一版；后续补搜索、高亮、目录锚点、小程序公式真机验收和图片资源字段化 |
 | 分数线 | `ScorelinePage.tsx` | 已覆盖 | 动态字段/趋势、后台维护和 JSON 批量导入已有；后续补复杂筛选优化和 AI 择校数据上下文 |
 | 商城/SVIP | `Store.tsx`、`SvipModal.tsx` | 部分覆盖 | 套餐、订单、订单详情/状态轮询、权益、激活码预检查/兑换、优惠券领取/下单抵扣、微信支付/支付宝 provider 主链路、内部退款状态机、微信/支付宝发起退款、退款查询确认、退款通知 webhook、支付/退款补偿 worker、全额退款权益撤销、资金对账手工/API 导入比对、微信/支付宝官方账单下载 worker、异常查询、差错工单和事件轨迹、异常订单运营台、人工调整凭证复核报表已有；Taro 学生收银台/订单详情和租户财务运营台第一版已接；仍缺更完整售后体验、真实生产账单抽样验收和生产账号联调 |
 | 个人中心 | `Profile.tsx` | 部分覆盖 | 基本资料、手机号绑定/换绑、权益、订单统计、练习历史、学习统计、签到积分、考试倒计时、趋势、勋章展示 API 已有；Taro 已接学习报告、14 天趋势、题型表现、最近练习、7 日答题榜当前排名、激活码和订单入口第一版；继续补任务系统、头像上传、账号合并和更细学习建议 |
@@ -95,7 +95,7 @@
 
 这些是旧项目中已经出现过、但新后端还没有完整业务闭环的功能：
 
-1. 阅读理解/案例分析多小题：后端 `subAnswers` 判分、断点恢复、报告 `subResults`、Taro 作答 UI、RichContent 长题干/图片/公式占位渲染和逐题复盘第一版已完成；仍需补真正 KaTeX/小程序公式方案、私有题图签名映射和更细复盘交互。
+1. 阅读理解/案例分析多小题：后端 `subAnswers` 判分、断点恢复、报告 `subResults`、Taro 作答 UI、RichContent 长题干/图片/H5 KaTeX 公式渲染、私有资源 ID 短签名题图和逐题复盘第一版已完成；仍需补小程序公式真机验收、题图资源字段化和更细复盘交互。
 2. 排行榜增强：刷题、模考、背单词、积分排行榜主接口已有；还需防刷、日/周榜预聚合、运营后台排名看板。
 3. 账号设置完整流：绑定/更换手机号基础 API 已完成；仍缺头像上传、微信/QQ 账号合并、密码/邮箱能力。
 4. 题库导出：服务端 JSON/试卷 payload、PDF/Word 二进制生成、水印、资料发布路径、权限审计、答案脱敏、每日一练基础导出和图片 ZIP 素材包已补；仍缺更精细试卷模板和后台导出操作台体验。

docs/refactor/next-development-todo.md

@@ -178,7 +178,7 @@
 - H5 和小程序共用同一套业务 API client。
 - 租户通过域名、小程序配置或启动参数解析。
 - 页面主题、品牌、功能开关都从后端租户配置读取；学生端和后台只消费 `/api/tenant/resolve` 的已发布 `branding.theme/publicAssets`，租户后台草稿只通过 `/api/tenant-admin/theme` 查看。
-- 当前已完成 H5 学生端、租户后台、平台后台三套构建入口和统一 API client；学生端、租户后台、平台后台都有第一批真实 API 页面；学生端已补地区选择、刷题答题卡、后端权威断点续练、本地进度恢复、模拟倒计时、主观题后端自评、阅读理解/案例分析多小题、错题/收藏复习、题目反馈、视频解析、练习/模考报告、个人中心学习报告可视化、会员收银台、订单详情、售后入口、题干/选项/解析/知识手册 RichContent 安全渲染、逐题复盘、背单词卡片学习/发音/收藏练习第一版；平台后台已接入创建租户、状态变更、订阅、账单、收款、用量和公共题库授权第一版写操作；租户后台已接权限驱动工作台、学生运营操作台、主题模板预览/发布、角色模板、成员绑定和 CRM/分佣操作台第一版；下一步补真正 KaTeX/小程序公式方案、私有题图签名资源映射、个人中心任务系统、状态管理、更细数据范围 UI、学生批量运营增强和小程序兼容验证。
+- 当前已完成 H5 学生端、租户后台、平台后台三套构建入口和统一 API client；学生端、租户后台、平台后台都有第一批真实 API 页面；学生端已补地区选择、刷题答题卡、后端权威断点续练、本地进度恢复、模拟倒计时、主观题后端自评、阅读理解/案例分析多小题、错题/收藏复习、题目反馈、视频解析、练习/模考报告、个人中心学习报告可视化、会员收银台、订单详情、售后入口、题干/选项/解析/知识手册 RichContent 安全渲染、H5 KaTeX 公式渲染、私有资源 ID 题图短签名渲染、逐题复盘、背单词卡片学习/发音/收藏练习第一版；平台后台已接入创建租户、状态变更、订阅、账单、收款、用量和公共题库授权第一版写操作；租户后台已接权限驱动工作台、学生运营操作台、主题模板预览/发布、角色模板、成员绑定和 CRM/分佣操作台第一版；下一步补小程序公式真机验收、题图资源字段化、个人中心任务系统、状态管理、更细数据范围 UI、学生批量运营增强和小程序兼容验证。
 
 ### 第一批页面
 
@@ -205,7 +205,7 @@
 
 5. 知识手册
    - 手册入口、章节、小节、知识点阅读
-   - RichContent 已支持 Markdown 图片、基础表格、代码、加粗、公式占位和安全过滤；后续补搜索、高亮、目录锚点、真正公式渲染和私有资源签名映射
+   - RichContent 已支持 Markdown 图片、基础表格、代码、加粗、H5 KaTeX 公式渲染、私有资源 ID 短签名和安全过滤；后续补搜索、高亮、目录锚点、小程序公式真机验收和题图资源字段化
 
 6. 分数线
    - 院校、专业、年份、动态字段筛选
@@ -230,7 +230,7 @@
 ## 推荐下一步顺序
 
 1. 补租户后台写操作台：公共题库采纳/同步、冲突查看、单条/批量冲突采纳平台或保留本地、导入问题、模板预览/下载、上传/粘贴 preview/import、字段映射编辑、异步导入轮询、导入后复检详情、权限驱动工作台、学生创建/更新/批量导入/批量分班/备注/跟进、角色模板配置、成员绑定模板、CRM 配置/队列/跟进分配策略、分佣规则/成员比例/结算生成审核打款/导出/凭证复核已接第一版；继续补成员批量运营、更细数据范围 UI、真实打款 provider 和发票。
-2. 继续补 Taro 学生端旧体验：地区选择、刷题答题卡、后端权威断点续练、本地进度恢复、模拟倒计时、主观题后端自评、阅读理解/案例分析多小题、视频播放、反馈、模考报告、逐题复盘、错题/收藏专题、个人中心学习报告、收银台、订单详情、售后入口、题干/解析/知识手册 RichContent 安全渲染、背单词卡片学习/发音/收藏练习、资料短签名水印预览/下载确认已接第一版；继续补真正 KaTeX/小程序公式方案、私有题图签名资源映射、个人中心任务系统、背单词更细统计、小程序支付容器、分享场景和状态管理。
+2. 继续补 Taro 学生端旧体验：地区选择、刷题答题卡、后端权威断点续练、本地进度恢复、模拟倒计时、主观题后端自评、阅读理解/案例分析多小题、视频播放、反馈、模考报告、逐题复盘、错题/收藏专题、个人中心学习报告、收银台、订单详情、售后入口、题干/解析/知识手册 RichContent 安全渲染、H5 KaTeX 公式渲染、私有资源 ID 题图短签名、背单词卡片学习/发音/收藏练习、资料短签名水印预览/下载确认已接第一版；继续补小程序公式真机验收、题图资源字段化、个人中心任务系统、背单词更细统计、小程序支付容器、分享场景和状态管理。
 3. 补平台后台增强：租户详情/编辑、平台审计报表、自动计费、账单批量操作和更细平台权限点。
 4. 云服务器部署 Supabase/PostgreSQL 和 API，配置对象存储生产环境变量，跑 `check:refactor` 的远程等价测试。
 5. 导出现有 PocketBase 数据，做完整 dry-run 迁移。

docs/refactor/taro-frontend-integration.md

@@ -404,6 +404,11 @@ apps/taro/src/components/RichContent.tsx
 apps/taro/src/components/rich-content.css
 ```
 
+官方参考：
+
+- KaTeX options：`https://katex.org/docs/options`
+- Taro RichText：`https://docs.taro.zone/en/docs/components/base/rich-text`
+
 当前接入页面：
 
 ```text
@@ -415,18 +420,18 @@ pages/student/handbook/index      知识点摘要和正文
 第一版支持：
 
 - 纯文本和换行。
-- Markdown 图片 `![alt](https://...)` 或站内 `/...` 路径。
+- Markdown 图片 `![alt](https://...)`、站内 `/...` 路径，或私有资源引用 `asset:<uuid>`、`content_asset:<uuid>`、`/asset/<uuid>`。
 - 基础表格。
 - `**加粗**`、行内代码和代码块。
-- `$...$`、`$$...$$`、`\(...\)`、`\[...\]` 公式占位样式。
+- H5 端用 KaTeX 渲染 `$...$`、`$$...$$`、`\(...\)`、`\[...\]`；渲染失败时降级显示公式原文。
 - 长题干、长单词、长公式自动换行或横向滚动。
 
 安全边界：
 
 - 组件会剥离 `<script>`、`<style>` 和普通 HTML 标签，不执行后端或导入内容中的 HTML/JS。
-- 图片只允许 HTTPS、站内相对路径、本地开发 localhost HTTP；拒绝 `javascript:`、`data:`、协议相对 URL 等危险来源。
-- 私有题图、资料图、PDF 和视频仍必须走后端资源台账和签名接口；不要把私有 OSS/COS/Supabase Storage URL 直接塞进题干长期渲染。
-- 当前公式只是安全可读的占位样式，不等于完整 KaTeX/MathJax。后续小程序端要在同一组件内替换为跨端公式渲染或服务端公式图片方案。
+- 图片只允许 HTTPS、站内相对路径、本地开发 localhost HTTP，或明确的 `content_assets` 资源 ID 引用；拒绝 `javascript:`、`data:`、协议相对 URL 等危险来源。
+- 私有题图通过 `GET /api/catalog/assets/preview?assetId=...` 申请短期签名后展示，不把私有 OSS/COS/Supabase Storage URL 长期写进题干或本地缓存。
+- 公式 HTML 只来自 KaTeX `renderToString`，不要把题库导入的原始 HTML 直接交给 `RichText`。小程序端还要真机验收 KaTeX 生成 HTML 的兼容性；如兼容性不足，保持同一 parser，替换为服务端公式图片或小程序专用公式组件。
 
 ### 断点续练