feat: scaffold taro h5 frontends

2026-06-29 11:40:32 +08:00
parent f74db433cc
commit c090008f52
40 changed files with 18033 additions and 16 deletions
--- a/docs/refactor/backend-capability-status.md
+++ b/docs/refactor/backend-capability-status.md
@@ -177,8 +177,12 @@

 ```bash
 npx supabase db reset
-npm audit --audit-level=high
+npm run audit:runtime
 npm run check:refactor
+npm run check:taro
+npm run build:taro:h5:student
+npm run build:taro:h5:tenant
+npm run build:taro:h5:platform
 npm run test:readiness
 npm run test:pb:dry-run
 npm run test:worker:imports
--- a/docs/refactor/backend-handoff-roadmap.md
+++ b/docs/refactor/backend-handoff-roadmap.md
@@ -35,7 +35,7 @@
 | 内容导入 | 可联调 | 题目、单词、知识手册、分数线、视频 JSON/CSV/Excel preview/import、issue、job、审计、幂等、`executionMode=async`、imports worker、导入后复检、模板下载、字段映射 API、PocketBase JSON dry-run 报告 | 字段映射 UI、真实数据 dry-run 执行验收和导入性能压测 |
 | 数据看板 | 可联调 | 租户 dashboard 聚合接口，收益、注册、学习、内容、激活码、反馈、趋势、24h 活跃、套餐销量和运营动态 | 预聚合 worker、缓存、慢 SQL 监控和销售转化看板 |
 | AI 择校推荐 | 未开始 | 暂无 | 数据上下文、AI JSON schema、报告渲染、PDF 生成 |
-| Taro 前端 | 未开始 | 旧 Web 已有新 API 适配雏形 | `apps/taro`、跨端 API client、H5/小程序页面和端到端测试 |
+| Taro 前端 | 地基已建 | `apps/taro` 已有 Taro 4 React 工程、H5 三入口、租户解析、统一 API client、Supabase Auth client 初始化和基础工作台壳 | 学生端完整页面、租户后台/平台后台业务页面、小程序兼容验证和端到端测试 |

 ## 前端接入建议

@@ -79,7 +79,7 @@
 - 对象存储：上传/下载签名已接入阿里云 OSS、腾讯云 COS、Supabase Storage；上传确认、PDF/图片预览签名和 assets worker 复检已完成，继续补 PDF 渲染、视频播放防盗链、杀毒扫描和水印。
 - 真实数据 dry-run：导出 PocketBase 用户、题库、单词、知识手册、分数线、订单、权益，先跑 `npm run pb:import:dry-run`，再跑迁移和校验报告。
 - 生产环境配置：`.env.example` 和 `npm run readiness:production` / `npm run readiness:production:db` 已补；继续补数据库迁移流程、备份恢复、日志、告警和 API 容器部署说明。
- Taro scaffold：建立 `apps/taro`，先完成租户解析、首页、题库、背单词、知识手册、个人中心主链路。
+- Taro scaffold：`apps/taro` 地基已建立；下一步补学生端首页、题库、背单词、知识手册、个人中心主链路和小程序兼容验证。

 ### P1：商用收费和运营能力

--- a/docs/refactor/multitenant-auth-security-contract.md
+++ b/docs/refactor/multitenant-auth-security-contract.md
@@ -171,7 +171,7 @@ provider event id 幂等

 ## 上线前安全验收清单

- `npm audit` 为 0 高危/严重漏洞。
+- `npm run audit:runtime` 为 0 high/critical 漏洞；Taro 构建工具链 audit 单独跟踪，不能用破坏性降级绕过。
 - `npm run check:refactor` 通过。
 - `npm run readiness:production` 没有 blocker。
 - `npm run readiness:production:db` 没有 blocker。
--- a/docs/refactor/next-development-todo.md
+++ b/docs/refactor/next-development-todo.md
@@ -158,10 +158,11 @@

 ### 架构目标

- 建议新建 `apps/taro`，不要继续在旧 React Web 上堆兼容。
+- 已新建 `apps/taro`，不要继续在旧 React Web 上堆兼容。
 - H5 和小程序共用同一套业务 API client。
 - 租户通过域名、小程序配置或启动参数解析。
 - 页面主题、品牌、功能开关都从后端租户配置读取。
+- 当前已完成 H5 学生端、租户后台、平台后台三套构建入口和统一 API client；下一步补完整页面、状态管理和小程序兼容验证。

 ### 第一批页面

--- a/docs/refactor/project-structure.md
+++ b/docs/refactor/project-structure.md
@@ -47,6 +47,17 @@ F:\project
        index.ts                 worker CLI/常驻循环入口
      package.json
      tsconfig.json
+    taro/                        Taro 4 React 跨端前端
+      src/
+        services/                统一 API client、Auth、Supabase client、缓存
+        pages/
+          bootstrap/             租户解析和三入口分流
+          student/               学生学习端 H5/小程序页面
+          tenant-admin/          租户后台工作台和运营页面
+          platform-admin/        平台超级管理员后台页面
+      config/                    Taro 构建配置，按 portal 输出三套 H5 产物
+      package.json
+      tsconfig.json

  packages/
    config/                      共享配置和 env 工具
@@ -127,6 +138,7 @@ git status --short --branch

 - `apps/api/**`
 - `apps/worker/**`
+- `apps/taro/**`
 - `packages/**`
 - `supabase/**`
 - `scripts/import-pocketbase/**`
--- a/docs/refactor/taro-h5-deployment.md
+++ b/docs/refactor/taro-h5-deployment.md
@@ -0,0 +1,129 @@
+# Taro H5 三入口部署说明
+
+更新时间：2026-06-29
+
+当前 `apps/taro` 按一个 Taro 工程、三套 H5 产物组织：
+
+- 学生学习端：刷题、背单词、知识手册、分数线、资料、会员和个人中心。
+- 租户后台：品牌、域名、题库、导入、学生、订单、营销、销售和数据看板。
+- 平台后台：租户、SaaS 套餐、订阅账单、公共题库授权和平台审计。
+
+## 构建命令
+
+```bash
+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
+```
+
+推荐部署：
+
+| 域名 | 目录 | 说明 |
+| --- | --- | --- |
+| `www.example.com` 或租户自有学生端域名 | `h5-student` | 面向学生和 C 端用户 |
+| `admin.example.com` | `h5-tenant-admin` | 面向租户公司运营、教师、销售、代理、管理员 |
+| `console.example.com` | `h5-platform-admin` | 面向平台超级管理员 |
+
+三个入口可以放在同一台服务器的三个静态目录，也可以放到 CDN/对象存储静态网站。API 推荐独立域名，例如 `api.example.com`。
+
+## 环境变量
+
+构建时只允许注入：
+
+```text
+TARO_APP_PORTAL=student | tenant-admin | platform-admin
+TARO_APP_API_BASE_URL=https://api.example.com
+TARO_APP_SUPABASE_URL=https://<supabase-auth-host>
+TARO_APP_SUPABASE_PUBLISHABLE_KEY=<publishable-key>
+TARO_APP_TENANT_CODE=<可选，小程序或预览环境使用>
+```
+
+禁止进入前端构建：
+
+```text
+SUPABASE_SERVICE_ROLE_KEY
+SUPABASE_SECRET_KEY
+DATABASE_URL
+ALIYUN_OSS_ACCESS_KEY_SECRET
+TENCENT_COS_SECRET_KEY
+WECHAT_PAY_PRIVATE_KEY
+ALIPAY_APP_PRIVATE_KEY
+AUTH_SESSION_SECRET
+PLATFORM_ADMIN_API_KEY
+```
+
+`apps/taro/src/env.ts` 会在启动时检查这些危险变量，防止误把服务端密钥打包到前端。
+
+## Nginx 建议
+
+H5 使用 history 路由时，静态服务器需要把未知路径回退到 `index.html`。
+
+```nginx
+server {
+  server_name www.example.com;
+  root /www/tiku/h5-student;
+
+  location / {
+    try_files $uri $uri/ /index.html;
+  }
+}
+
+server {
+  server_name admin.example.com;
+  root /www/tiku/h5-tenant-admin;
+
+  location / {
+    try_files $uri $uri/ /index.html;
+  }
+}
+
+server {
+  server_name console.example.com;
+  root /www/tiku/h5-platform-admin;
+
+  location / {
+    try_files $uri $uri/ /index.html;
+  }
+}
+```
+
+API CORS 必须只允许实际域名，不允许生产环境 `CORS=*`。生产前运行：
+
+```bash
+npm run readiness:production
+npm run readiness:production:db
+```
+
+## 前端请求边界
+
+- 所有页面统一通过 `apps/taro/src/services/api.ts` 调用后端。
+- H5 可以用 Supabase client 管理 Auth session，但业务数据默认走 `apps/api`。
+- `x-tenant-id` 只是租户上下文，不是身份来源。
+- 登录后禁止传 `x-user-id` 或 body/query `userId` 表示当前用户。
+- 订单、支付、权益、内容导入、后台配置、CRM、对象存储签名、视频播放签名必须走后端命令层。
+
+## 安全审计边界
+
+H5 线上只发布 `apps/taro/dist/**` 静态文件，不要把 `apps/taro/node_modules` 或源码目录部署到 Web 根目录。后端/API/worker 的生产依赖审计使用：
+
+```bash
+npm run audit:runtime
+```
+
+Taro 4.2.0 当前构建工具链仍会触发 `npm run audit:taro:toolchain` 的上游 high/critical 告警，主要来自构建期 CLI、webpack、swiper、lodash-es 等传递依赖。不要使用 `npm audit fix --force` 将 Taro 降级到 3.x；应等 Taro 官方升级后再处理，或者后续评估 Vite runner 替代方案。上线时以静态产物、前端密钥检查、CORS 域名白名单和 API runtime audit 作为阻断项。
+
+## 下一步页面顺序
+
+1. 学生端：租户启动、登录、首页、题库入口、练习、错题、收藏。
+2. 学生端：背单词、知识手册、分数线、资料、会员、个人中心。
+3. 租户后台：数据看板、内容导航、题目录入/导入、学生管理、营销中心。
+4. 平台后台：租户、套餐、账单、公共题库授权。
+5. 小程序：验证 storage/fetch/Auth 兼容性，复用同一套 API client。