forked from wangziqi/gongxue-base
154 lines
10 KiB
Markdown
154 lines
10 KiB
Markdown
# Taro 前端工程
|
||
|
||
这是 SaaS 题库的新跨端前端地基。当前阶段已经提供 H5 多入口、租户解析、统一 API client、Supabase Auth client 初始化、安全环境变量边界、学生端第一批可联调页面、租户后台第一批运营页面，以及平台超管第一批 SaaS 运营页面。
|
||
|
||
## 三个 H5 入口
|
||
|
||
```bash
|
||
npm run dev:taro:h5
|
||
npm run build:taro:h5:student
|
||
npm run build:taro:h5:tenant
|
||
npm run build:taro:h5:platform
|
||
```
|
||
|
||
构建产物：
|
||
|
||
```text
|
||
apps/taro/dist/h5-student
|
||
apps/taro/dist/h5-tenant-admin
|
||
apps/taro/dist/h5-platform-admin
|
||
```
|
||
|
||
可以分别部署到学生端域名、租户后台域名、平台后台域名。三个入口共用 `src/services/api.ts`，不得在页面中散写 `Taro.request`。
|
||
|
||
Taro 固定稳定版 `4.2.0`。安装时 workspace postinstall 会对精确版本和源码 hash 应用两项 H5-only runtime patch：Input watcher 在 ref 未就绪时安全退出，Button loading 始终保留同一 loading 节点并只切换显示状态。所有 H5 build/dev 命令都会先运行 fail-closed 检查；不要使用 `npm ci --ignore-scripts`。微信小程序使用原生组件，不依赖这两项 H5 patch。
|
||
|
||
H5 入口模板在 `src/index.html`。构建后每个目录都必须有 `index.html`，否则静态 Web 不能上线。发布前从仓库根目录运行：
|
||
|
||
```bash
|
||
npm run smoke:taro:h5
|
||
npm run smoke:taro:h5:interaction
|
||
npm run manifest:taro:h5
|
||
node scripts/taro-h5-release-guardrails-test.js --require-dist
|
||
```
|
||
|
||
`smoke:taro:h5` 会用临时静态服务器验证三套 H5 的 `index.html`、JS/CSS 资源、history fallback、公开 `runtime-config.json` 和 `/api/tenant/resolve` 契约。`manifest:taro:h5` 会输出三套 H5 的部署清单，包含构建命令、发布目录、入口路由、资源数量、`index.html` hash 和 runtime-config 状态，方便上线前核对 Web 根目录。发布守卫会扫描三套 H5 产物和运行配置边界，阻断旧 PocketBase 引用、`x-user-id`、平台本地 key、数据库连接串和服务端密钥形态进入前端产物。正式部署时仍需要在每个 H5 目录根部放置对应的 `runtime-config.json`。
|
||
|
||
## 当前学生端页面
|
||
|
||
已接入第一批真实后端 API：
|
||
|
||
```text
|
||
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/notifications/index 独立消息中心、筛选、已读、归档
|
||
pages/student/profile/index 个人中心、男女预设头像、会员、订单、签到、激活码、勋章
|
||
```
|
||
|
||
这些页面是联调骨架，不是最终视觉稿。当前学生端已覆盖地区选择、刷题、答题卡、后端权威断点续练、本地恢复、模拟倒计时、主观题后端自评、阅读理解/案例分析多小题作答、题目反馈、视频解析、交卷报告、错题本、收藏夹、男女预设头像选择、独立消息中心、会员收银台、订单详情和售后入口第一版；后续应继续参照旧题库样式完善长题干排版、公式图片混排、支付容器体验和小程序兼容。学生头像不做上传、裁剪或第三方头像同步，个人中心只保存 `avatarPreset=male/female`。消息中心只允许打开已登记的学生端站内路径，不根据通知 payload 跳外链或后台页面。
|
||
|
||
学生端商城链路的安全边界：
|
||
|
||
- `checkout` 只提交套餐、地区、支付 provider 和优惠券信息，最终价格、折扣、订单状态和权益发放全部以后端 `/api/commerce/*` 为准。
|
||
- H5 支付遇到支付宝 WAP 或 provider 返回的 URL 时可跳转；微信小程序支付通过 `Taro.requestPayment` 适配 provider 返回参数。
|
||
- 普通学生端不直接调用退款命令。售后入口只复制订单与客服联系信息，退款申请、审核、供应商退款和权益撤销在租户后台权限流完成。
|
||
|
||
## 当前租户后台页面
|
||
|
||
已接入第一批真实后端 API：
|
||
|
||
```text
|
||
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 选择文件或粘贴内容、后端预览、字段别名覆盖和同步/异步执行导入第一版；营销中心已接入 CRM 配置保存、CRM 队列按状态查看、分佣默认规则、成员分佣比例、分佣订单明细、生成结算单、审核通过/驳回和标记线下打款第一版。真正权限以后端 permission keys 为准，前端菜单隐藏只做体验优化。
|
||
|
||
租户工作台会读取 `/api/tenant-admin/permissions`，按菜单权限和有效权限隐藏不可见模块。租户设置页已接入角色模板与成员绑定写操作第一版：可新建、编辑、停用非系统模板，配置权限点、菜单可见、模块可见、字段可见和基础数据范围，也可以搜索/新建成员、绑定角色模板、设置成员状态和额外权限覆盖。前端只负责操作体验，`tenant_owner`、`tenant_admin`、通配权限、系统模板保护和最后一名 owner 保护仍以后端校验与审计为准。
|
||
|
||
## 当前平台后台页面
|
||
|
||
已接入第一批真实后端 API：
|
||
|
||
```text
|
||
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 为准。后续继续补租户详情页、平台审计报表、自动计费和更细平台权限点。
|
||
|
||
## 前端环境变量
|
||
|
||
只允许使用：
|
||
|
||
```text
|
||
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=<可选，小程序/预览环境使用>
|
||
```
|
||
|
||
微信小程序本地预览使用 `npm run build:taro:weapp:student`。正式上传前必须使用严格命令，并注入公开的 HTTPS API、固定租户码和真实 AppID：
|
||
|
||
```bash
|
||
TARO_APP_API_BASE_URL=https://api.example.com \
|
||
TARO_APP_TENANT_CODE=tenant-code \
|
||
WECHAT_MINIAPP_APP_ID=wx0000000000000000 \
|
||
npm run build:taro:weapp:student:production
|
||
```
|
||
|
||
共享 SaaS 小程序可改用 `TARO_APP_WEAPP_TENANT_MODE=launch`，由小程序码 query/scene 或 `referrerInfo.extraData.tenantCode` 传入租户码，无需为每个租户重新打包。严格构建会启用微信合法域名检查，并拒绝本地 API、测试 AppID、固定模式缺失 tenantCode 或超出包体预算的产物；launch 模式启动时缺少租户码会明确报错，不会回退默认租户。
|
||
|
||
禁止把 service role、数据库连接串、支付私钥、对象存储密钥放进 Taro 构建环境。
|
||
|
||
## 视觉规范
|
||
|
||
学生端、租户后台和平台后台的视觉语言见 `docs/refactor/taro-visual-language.md`。旧题库小程序/旧 Web 只作为学习流程、页面状态和运营信息密度参考，不继承旧 PocketBase 直连、旧鉴权或旧字段模型。修改 CSS 后运行：
|
||
|
||
```bash
|
||
npm run guard:taro:visual
|
||
```
|
||
|
||
该守卫会阻断大圆角卡片、视口字体、负字距、装饰性渐变/模糊背景和未登记线性渐变，避免 H5 首发页面视觉漂移。
|
||
|
||
## 接入原则
|
||
|
||
- H5 可用 Supabase client 管理 Auth session。
|
||
- 业务数据默认走 `apps/api`。
|
||
- `x-tenant-id` 只是租户上下文，不是身份凭证。
|
||
- 登录后不要传 `x-user-id` 或 body/query `userId` 伪造当前用户。
|
||
- 题库练习、答案判分、主观题自评、订单支付、内容导入、CRM、资料签名、后台配置必须走后端命令层。
|
||
|
||
## H5 部署建议
|
||
|
||
当前保留三个独立构建目录，适合分别放到三个域名或同一服务器的三个静态目录：
|
||
|
||
```text
|
||
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` 指定租户。
|
||
|
||
更完整的部署、安全头、CORS、CSP 和运行时配置说明见 `docs/refactor/taro-h5-deployment.md`。
|