gongxue-base/docs/refactor/frontend-handoff-index.md

前端交接索引

更新时间：2026-06-30

这份文件是给 Taro/H5/小程序前端同事的入口。当前仓库的前端重构建议从 apps/taro 新建工程开始，不再把旧 React/Vite 前端搬回根目录继续开发。

必读顺序

1. docs/refactor/project-structure.md
   • 先确认新项目目录边界，避免把 参考/旧题库项目 当成新源码。
2. docs/refactor/ai-development-guardrails.md
   • 先看后续 AI/开发者必须遵守的 Supabase-first 架构、安全红线和功能落位判断树。
3. docs/refactor/backend-capability-status.md
   • 看哪些后端能力已经能联调，哪些只是迁移期可用。
4. docs/refactor/legacy-feature-gap-matrix.md
   • 对照旧题库功能，确认哪些页面能按新 API 重做，哪些后端还要补。
5. docs/refactor/supabase-frontend-access-strategy.md
   • 明确 Taro 什么时候可以用 Supabase client，什么时候必须走 apps/api。
6. docs/refactor/taro-frontend-integration.md
   • Taro 启动、租户解析、请求封装、页面/API 映射、跨端注意事项。
7. docs/refactor/taro-h5-deployment.md
   • H5 三域名部署、runtime-config.json、Nginx history fallback、缓存、CSP 和 CORS 边界。
8. docs/refactor/multitenant-auth-security-contract.md
   • 多租户、鉴权、权限、资源签名和生产安全红线。
9. docs/refactor/content-import-contract.md
   • 后台内容导入、题目 JSON、单词、知识手册、分数线、视频的后端校验契约。
10. docs/refactor/production-launch-evidence.template.json

• 上线前证据文件模板；真实生产验收结果填入 production-launch-evidence.json 后运行 npm run launch:gate，该真实证据文件不入 Git。

当前可进入的前端工作

• apps/taro 已经建立，且学生端第一批 H5 页面已经可构建：登录、首页、地区选择、题库、练习、错题/收藏、练习报告、视频解析、会员收银台、订单详情、背单词、知识手册、分数线、资料、个人中心。
• 租户后台第一批 H5 页面已经可构建：工作台、数据看板、学生/班级、题库内容、营销中心、财务运营、租户设置；工作台已接 /api/tenant-admin/permissions 做权限驱动模块入口；学生运营页已具备学生创建/更新、状态禁用/恢复、批量导入、批量分班、学生备注和跟进任务第一版；题库内容页已具备公共题库采纳/同步、同步通知、冲突查看、单条/批量采纳平台版本或保留本地版本、导入任务详情、异步轮询、导入问题查看、模板预览/下载、导入后复检详情、JSON/CSV/Excel 选择文件或粘贴内容、后端预览、字段别名覆盖和同步/异步执行导入的第一版操作能力；营销中心已具备 CRM 配置、CRM 队列查看、分佣规则、成员分佣比例、分佣订单、结算单生成/审核/标记打款、优惠券规则/核销报表和用户通知查看第一版；财务运营页已具备退款申请/审核/供应商提交与查询、官方账单下载任务、对账批次/异常明细、差错工单处理、人工调整凭证提交/复核和异常订单运营台第一版；租户设置页已具备主题模板、草稿预览/发布、角色模板新建、编辑、停用、成员搜索/新建、成员绑定模板、成员状态和额外权限覆盖第一版。
• 平台后台第一批 H5 页面已经可构建：工作台、租户管理、账务中心、公共题库授权；租户管理页已接租户详情、账务资料编辑和最近平台审计，工作台已展示最近平台审计摘要、支持导出最近平台审计 CSV，并可查看开放审计告警、确认或解决告警，也能查看审计告警外部通知渠道、催缴外部通知渠道和最近发送事件摘要；账务中心已接订阅账单候选预览、dry-run、批量生成、自动计费生成结果查看、逾期预览、内部催缴生成和催缴记录查看。
• 可以继续复刻旧题库学生端主要视觉和交互：勋章展示、小程序端分享/支付体验、背单词更细统计和更完整复盘体验。地区选择、刷题答题卡、后端权威断点续练、本地进度恢复、模拟倒计时、主观题后端自评、阅读理解/案例分析多小题、题干/选项/解析 RichContent 安全渲染、视频解析、题目反馈、模考/练习报告逐题复盘、错题复习、收藏复习、背单词卡片学习/发音/收藏练习、商城收银台、订单详情和售后入口已经有第一版页面。
• 可以按新后端主模型接入内容导航：
  • content_entries
  • content_nodes
  • question_collections
  • practice_blueprints
• 可以接入迁移期短信登录和 tk_ session，用于本地/内网联调。
• H5 可以直接用 Supabase Auth access token 调 apps/api；后端已支持 JWT 验签和业务用户映射。
• apps/taro/src/services/api.ts 现在默认 Supabase JWT 优先、迁移期 tk_ 兜底；公共接口必须显式 authMode='none'。页面不要手写 Authorization、x-tenant-id 或 x-user-id。
• H5 可以优先验证 @supabase/supabase-js 管理 Auth session；微信小程序端先验证运行时兼容性，业务数据默认仍走 apps/api。
• H5 生产部署优先用每个静态目录自己的 runtime-config.json 配置 apiBaseUrl、supabaseUrl、supabasePublishableKey、tenantCode；不要为了换域名重打包，也不要把任何 service role、数据库、支付、短信、对象存储密钥放进该文件。
• 上线前需要把三套 H5 构建、runtime-config.json 人工复核、真实 Auth/RLS、迁移 dry-run、对象存储、支付对账和 @codex-security 结果写入 production-launch-evidence.json，并通过 npm run launch:gate。
• 可以接入租户品牌、已发布主题、公开素材、功能开关和域名/小程序参数解析；学生端只读 /api/tenant/resolve 的 branding.theme/publicAssets，租户后台草稿走 /api/tenant-admin/theme。
• 租户后台可以接入角色模板和成员 API：/api/tenant-admin/role-templates、/api/tenant-admin/members，用于运营、教师、销售、代理等自定义菜单/模块/字段可见性和成员模板绑定。
• 租户后台可以接入勋章管理、手动发放、积分任务和积分兑换：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/profile/badges 展示成就，并通过 GET /api/profile/activity-tasks、POST /api/profile/activity-tasks/claim、GET /api/profile/exchange-items、POST /api/profile/exchange-items/redeem 接积分活动和兑换。
• 学生消息中心可以接 GET /api/profile/notifications、POST /api/profile/notifications/status；租户后台可用 GET /api/tenant-admin/user-notifications 做用户通知查看。通知只做展示、跳转和已读/归档状态，业务权限和权益仍以后端源接口为准。

不能误认为已商用完成的部分

• 生产鉴权已具备 Supabase JWT API 入口，自定义角色模板基础 API 已可用；后端已提供 npm run smoke:auth:remote 用真实 Supabase access token 验收云端 Auth/JWKS 映射，已提供 npm run test:rls 做本地动态 RLS 深测；前端不要继续使用 x-user-id，真实 access token 也不要写入 runtime-config.json、页面代码或仓库。
• 不要把“Supabase 支持前端 Data API”误解为“本项目所有业务表都由 Taro 直写”；订单、支付、权益、租户后台、导入、CRM、私有资源必须走 RPC、apps/api、Edge Function 或 worker 这类后端命令层。
• 短信、微信小程序/网页登录、QQ 登录、微信支付、支付宝支付 provider 已有本地 adapter 和测试覆盖；生产账号、回调域名、证书和商户资料仍需正式联调。
• 对象存储已完成签名 provider、上传后校验、PDF/图片预览、动态水印上下文、资源复检 worker、内置安全扫描、外部 HTTP scanner 接入层和租户后台媒体运营报表；Taro 学生资料页已接短期签名、水印 traceId 展示和强制水印容器第一版；CDN 防盗链、转码级视频水印和真实 AV/内容安全服务联调还要补。
• 题目/单词/知识手册/分数线/视频 JSON/CSV/Excel 导入已可联调；大批量导入可传 executionMode=async 交给 imports worker；模板下载、字段映射 API、导入任务详情和导入后复检已可用。租户内容页已经可以选择文件或粘贴内容、下载模板、执行后端预览、编辑本次字段别名、同步/异步提交导入、轮询异步 job、查看问题行并触发/查看复检；后续还要补真实数据 dry-run 验收和更完整的目标入口/集合选择。
• 数据看板、分佣结算、财务运营、勋章手动发放、签到/积分/反馈/积分活动自动发放、积分任务/兑换第一阶段、用户站内通知第一版和主题模板发布基础 API 已可联调；Taro 学生个人中心已接积分任务/兑换/积分明细第一版，租户营销中心已接积分任务/兑换配置和记录查看第一版；练习/单词/模考触发勋章、积分风控报表、连续签到奖励配置、外部微信订阅消息/短信、真实打款 provider、发票、真实生产账单抽样验收、AI 择校真实 provider、主题素材库/模板市场等仍是后续商用增强项。

前后端协作建议

• 前端先做页面骨架和 API client，不要在页面里写死租户、地区、资源地址、商户号或 provider 密钥。
• 每个页面先接后端已有接口；缺接口时把页面期望的字段写到 issue/TODO，再由后端补聚合接口。
• 权限判断以后端结果为准，前端只做菜单和按钮可见性优化。
• 旧项目只作为样式、交互和字段含义参考；长期数据模型以新 API 为准。

已落地的 Taro 学生端页面

页面	文件	已接接口
启动页	apps/taro/src/pages/bootstrap/index.tsx	GET /api/tenant/resolve
短信登录	apps/taro/src/pages/student/login/index.tsx	POST /api/auth/sms/send、POST /api/auth/sms/verify
首页	apps/taro/src/pages/student/home/index.tsx	content-entries、banners、announcements、profile/me
地区选择	apps/taro/src/pages/student/region/index.tsx	catalog/regions、profile/me、PATCH profile/me
题库	apps/taro/src/pages/student/catalog/index.tsx	content-entries、content-nodes、question-collections、practice-blueprints
练习	apps/taro/src/pages/student/practice/index.tsx	practice-sessions、questions、answers、favorites/questions、practice-sessions/submit、profile/feedbacks；已接答题卡、后端 session detail 恢复、本地进度恢复、倒计时、主观题 selfJudgedCorrect、阅读理解/案例分析 subAnswers 多小题、题干/选项/解析 RichContent 安全渲染
错题/收藏	apps/taro/src/pages/student/review/index.tsx	wrong-questions/review-plan、wrong-questions/resolve、favorites/questions、practice-sessions
练习报告	apps/taro/src/pages/student/reports/index.tsx	practice-sessions/report、practice-reports；已接逐题复盘、复合题子题明细和 RichContent 解析渲染
视频解析	apps/taro/src/pages/student/video/index.tsx	questions/videos、videos/play
会员收银台	apps/taro/src/pages/student/checkout/index.tsx	svip-plans、coupons/claim、commerce/orders、payments/create、orders/status
订单详情	apps/taro/src/pages/student/order-detail/index.tsx	commerce/orders/detail、commerce/orders/status、payments/create
背单词	apps/taro/src/pages/student/vocabulary/index.tsx	vocabulary-units、vocabulary-words、vocabulary/review-plan、vocabulary/review、vocabulary/favorites；已接今日计划、单元学习、收藏练习、卡片翻转、发音、美/英音切换、本地进度恢复和单词跳转
知识手册	apps/taro/src/pages/student/handbook/index.tsx	handbook-subjects、handbook-chapters、handbook-entries；已接 RichContent 阅读渲染第一版
分数线	apps/taro/src/pages/student/scoreline/index.tsx	scoreline/records
资料	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、score-events、badges、exam-countdowns、svip-plans、orders、entitlements、activation-codes、leaderboard、learning/stats、learning/trend、practice-sessions/history、profile/activity-tasks、profile/activity-tasks/claim、profile/exchange-items、profile/exchange-items/redeem、profile/notifications、profile/notifications/status；已接学习报告、练习趋势、最近练习、会员订单、激活码、积分任务/兑换/积分明细和消息中心第一版

当前页面主要用于打通接口和路由。学生端第一版学习闭环已经覆盖“选地区 -> 进题库 -> 创建 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 租户后台页面

页面	文件	已接接口
工作台	apps/taro/src/pages/tenant-admin/workbench/index.tsx	tenant-admin/overview、tenant-admin/dashboard、tenant-admin/permissions
数据看板	apps/taro/src/pages/tenant-admin/dashboard/index.tsx	tenant-admin/dashboard
学生运营	apps/taro/src/pages/tenant-admin/students/index.tsx	tenant-admin/classes、tenant-admin/teachers、tenant-admin/students、students/bulk-upsert、students/status、classes/members/bulk-assign、students/notes、students/followups
题库内容	apps/taro/src/pages/tenant-admin/content/index.tsx	tenant-content/content-entries、tenant-content/imports、imports/detail、imports/issues、imports/field-mapping、imports/templates、imports/post-check、tenant-content/exports/questions、tenant-content/exports/jobs、tenant-content/assets/sign-download、tenant-content/assets/sign-preview、tenant-content/assets/security-scan-events、tenant-content/public-question-banks、public-question-banks/adopt、public-question-banks/sync、public-question-banks/conflicts、public-question-banks/conflicts/resolve、public-question-banks/conflicts/resolve-batch、tenant-content/notifications、tenant-content/notifications/status
营销中心	apps/taro/src/pages/tenant-admin/marketing/index.tsx	tenant-admin/coupons、code-batches、activation-codes、crm/config、crm/queue、commission/settings、member-rate、summary、orders、settlements、settlements/generate、settlements/status、tenant-admin/point-activity-tasks、tenant-admin/point-activity-claims、tenant-admin/point-exchange-items、tenant-admin/point-exchange-orders、tenant-admin/user-notifications；已接 CRM、分佣、优惠券规则/核销报表、积分任务/兑换配置与记录查看、用户通知查看第一版
财务运营	apps/taro/src/pages/tenant-admin/finance/index.tsx	commerce/refunds、commerce/refunds/status、commerce/operations/anomalies、commerce/reconciliation/batches、commerce/reconciliation/items、commerce/reconciliation/issues/create、commerce/reconciliation/issues、commerce/reconciliation/issues/status、commerce/reconciliation/provider-bills/request、commerce/reconciliation/provider-bills/jobs、commerce/adjustment-vouchers、commerce/adjustment-vouchers/status、commerce/adjustment-vouchers/report
租户设置	apps/taro/src/pages/tenant-admin/settings/index.tsx	tenant-admin/overview、domains、payment-accounts、auth-providers、theme-templates、theme、theme/preview、theme/publish、permissions、GET/PUT role-templates、POST role-templates/disable、GET/PUT members、POST members/disable

当前租户后台已有第一批运营操作：工作台按权限矩阵隐藏不可见模块；学生运营页支持学生创建/更新、状态禁用/恢复、批量导入、批量分班、学生备注、跟进任务和完成跟进；题库内容页支持公共题库采纳/同步、同步通知查看与已读/忽略、同步冲突查看、单条/批量采纳平台版本或保留本地版本、导入任务详情、异步 job 轮询、导入问题查看、字段映射/模板预览/下载、JSON/CSV/Excel 导入预览和执行、字段别名覆盖和导入后复检详情，也可接 JSON/试卷 payload 同步导出与 PDF/Word 异步导出 job 轮询，完成后用 assetId 走后台资源签名下载/预览；营销中心支持 CRM 配置保存、队列按状态查看、分佣规则、成员分佣比例、分佣订单明细、结算单生成、审核通过/驳回、标记线下打款、优惠券规则/核销报表、积分任务/兑换配置、领取/兑换记录查看和用户通知查看第一版；财务运营页支持退款状态流、官方账单任务、对账异常、差错工单和调整凭证，且只通过后端命令层写审计与状态；租户设置页支持主题模板选择、草稿预览、发布、角色模板创建、编辑、停用、权限点、菜单、模块、字段、基础数据范围配置、成员搜索/新建、成员绑定模板、成员状态和额外权限覆盖。下一批需要继续补更精细的学生导入模板体验、更细数据范围 UI、主题素材库、真实打款 provider、发票、真实生产账单抽样验收和小程序端兼容。

已落地的 Taro 平台后台页面

页面	文件	已接接口
工作台	apps/taro/src/pages/platform-admin/workbench/index.tsx	platform-admin/overview、tenants、invoices、question-banks、question-bank-grants、audit-logs、audit-logs/export、audit-alerts、audit-alerts/status、audit-notification-channels/events、dunning-notification-channels/events
租户管理	apps/taro/src/pages/platform-admin/tenants/index.tsx	platform-admin/tenants、POST tenants、tenants/detail、PATCH tenants/status、PUT tenants/billing-profile、audit-logs
账务中心	apps/taro/src/pages/platform-admin/billing/index.tsx	platform-admin/plans、invoices、invoices/subscription-candidates、invoices/from-subscription、invoices/from-subscriptions-batch、invoices/payments/manual-confirm、usage、subscriptions、POST usage
公共题库	apps/taro/src/pages/platform-admin/question-banks/index.tsx	platform-admin/question-banks、question-bank-grants、PUT question-bank-grants

当前平台后台已经具备第一批写操作台：创建租户、租户详情查看、状态变更、账务资料维护、最近平台审计查询、最近平台审计 CSV 导出、开放审计告警确认/解决、审计告警外部通知渠道/事件摘要、催缴外部通知渠道/事件摘要、订阅开通、账单生成、订阅账单候选预览、dry-run、批量生成、自动计费生成结果查看、人工收款确认、逾期预览、内部催缴生成、催缴记录查看、用量录入、公共题库授权编辑；这些动作均经过前端基础校验和二次确认，后端继续执行真实权限、重复开票保护和审计。平台审计导出只开放给平台管理员，后端会对导出 details 中的 token/secret/password/key 等敏感字段脱敏，并返回 contentBase64 + sha256，H5 可直接下载，小程序端建议先展示“已生成，需在 H5 管理台下载”。平台审计告警由 platform-audit-alerts worker 从高风险平台审计动作生成，外部通知由 platform-audit-notifications worker 根据平台渠道配置发送；平台催缴外部通知由 platform-dunning-notifications worker 根据 tenant_invoice_reminders 和平台渠道配置发送。前端只能调用告警查询、状态更新、通知渠道和发送事件 API，不要直接写 platform_audit_alerts、platform_audit_notification_channels、platform_audit_notification_events、platform_dunning_notification_channels 或 platform_dunning_notification_events 表。后端会对告警 details、通知 payload 和催缴 payload 递归脱敏，渠道 API 只回显 secretRef 和 webhook host/path。下一批继续补租户基础资料编辑增强、平台审计告警升级策略、平台催缴通知配置操作台细节、平台在线收款和更细平台权限点。