Taro 前端工程
这是 SaaS 题库的新跨端前端地基。当前阶段已经提供 H5 多入口、租户解析、统一 API client、Supabase Auth client 初始化、安全环境变量边界、学生端第一批可联调页面、租户后台第一批运营页面，以及平台超管第一批 SaaS 运营页面。
三个 H5 入口
npm run dev:taro:h5
npm run build:taro:h5:student
npm run build:taro:h5:tenant
npm run build:taro:h5:platform
构建产物：
apps/taro/dist/h5-student
apps/taro/dist/h5-tenant-admin
apps/taro/dist/h5-platform-admin
可以分别部署到学生端域名、租户后台域名、平台后台域名。三个入口共用 src/services/api.ts，不得在页面中散写 Taro.request。
当前学生端页面
已接入第一批真实后端 API：
pages/student/login/index 短信登录
pages/student/home/index 首页与功能入口
pages/student/region/index 地区选择、目标地区保存
pages/student/catalog/index 题库入口、分类、集合、练习蓝图
pages/student/practice/index 创建练习 session、答题、收藏、反馈、视频入口、交卷报告
pages/student/review/index 错题本、收藏夹、错题/收藏复习
pages/student/reports/index 练习报告、模考报告、历史报告
pages/student/video/index 题目视频解析、播放签名
pages/student/checkout/index 会员收银台、优惠券领取、下单、支付参数
pages/student/order-detail/index 订单详情、状态轮询、继续支付、售后入口
pages/student/vocabulary/index 单词单元、复习计划、认识/再记、收藏
pages/student/handbook/index 手册科目、章节、知识点阅读
pages/student/scoreline/index 分数线列表
pages/student/assets/index 资料列表、预览签名、下载签名
pages/student/profile/index 个人中心、会员、订单、签到、激活码、勋章
这些页面是联调骨架，不是最终视觉稿。当前学生端已覆盖地区选择、刷题、题目反馈、视频解析、交卷报告、错题本、收藏夹、会员收银台、订单详情和售后入口第一版；后续应继续参照旧题库样式完善刷题细节、支付容器体验和小程序兼容。
学生端商城链路的安全边界：
checkout只提交套餐、地区、支付 provider 和优惠券信息，最终价格、折扣、订单状态和权益发放全部以后端/api/commerce/*为准。- H5 支付遇到支付宝 WAP 或 provider 返回的 URL 时可跳转；微信小程序支付通过
Taro.requestPayment适配 provider 返回参数。 - 普通学生端不直接调用退款命令。售后入口只复制订单与客服联系信息，退款申请、审核、供应商退款和权益撤销在租户后台权限流完成。
当前租户后台页面
已接入第一批真实后端 API：
pages/tenant-admin/workbench/index 租户后台工作台
pages/tenant-admin/dashboard/index 数据看板
pages/tenant-admin/students/index 学生与班级
pages/tenant-admin/content/index 内容入口、导入任务、字段模板、异步轮询、复检、公共题库采纳/同步/冲突处理
pages/tenant-admin/marketing/index 优惠券、激活码、CRM、分佣摘要
pages/tenant-admin/settings/index 品牌、域名、支付、登录、角色模板
当前后台页面已经从只读联调推进到第一批运营写操作。题库内容页已接入公共题库采纳、公共题库同步、同步冲突查看、单条采纳平台版本/保留本地版本、导入任务详情、异步任务轮询、导入问题查看、模板预览、导入后复检详情，以及 JSON/CSV/Excel 的 H5 选择文件或粘贴内容、后端预览、字段别名覆盖和同步/异步执行导入第一版；营销、设置和学生页仍以扫描和轻量操作为主。真正权限以后端 permission keys 为准，前端菜单隐藏只做体验优化。
当前平台后台页面
已接入第一批真实后端 API：
pages/platform-admin/workbench/index 平台工作台
pages/platform-admin/tenants/index 租户列表、创建租户、状态变更
pages/platform-admin/billing/index SaaS 套餐、订阅、服务费账单、收款、用量
pages/platform-admin/question-banks/index 平台公共题库、授权规则编辑
当前平台后台已接入创建租户、修改状态、开通订阅、生成订阅账单、确认线下收款、记录用量和公共题库授权编辑。页面会做基础表单校验和二次确认，真正权限、租户/套餐校验、幂等和审计以后端 platform-admin API 为准。后续继续补租户详情页、平台审计报表、自动计费和更细平台权限点。
前端环境变量
只允许使用：
TARO_APP_PORTAL=student | tenant-admin | platform-admin
TARO_APP_API_BASE_URL=https://api.example.com
TARO_APP_SUPABASE_URL=https://<supabase-host>
TARO_APP_SUPABASE_PUBLISHABLE_KEY=<publishable-key>
TARO_APP_TENANT_CODE=<可选，小程序/预览环境使用>
禁止把 service role、数据库连接串、支付私钥、对象存储密钥放进 Taro 构建环境。
接入原则
- H5 可用 Supabase client 管理 Auth session。
- 业务数据默认走
apps/api。 x-tenant-id只是租户上下文，不是身份凭证。- 登录后不要传
x-user-id或 body/queryuserId伪造当前用户。 - 题库练习、订单支付、内容导入、CRM、资料签名、后台配置必须走后端命令层。
H5 部署建议
当前保留三个独立构建目录，适合分别放到三个域名或同一服务器的三个静态目录：
student.example.com -> apps/taro/dist/h5-student
tenant-admin.example.com -> apps/taro/dist/h5-tenant-admin
platform-admin.example.com -> apps/taro/dist/h5-platform-admin
API 使用 TARO_APP_API_BASE_URL 指向统一后端。学生端通过域名解析租户；小程序或预览环境可用 TARO_APP_TENANT_CODE 指定租户。