# 前端交接索引

更新时间：2026-06-29

这份文件是给 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/multitenant-auth-security-contract.md`
   - 多租户、鉴权、权限、资源签名和生产安全红线。
8. `docs/refactor/content-import-contract.md`
   - 后台内容导入、题目 JSON、单词、知识手册、分数线、视频的后端校验契约。

## 当前可进入的前端工作

- `apps/taro` 已经建立，且学生端第一批 H5 页面已经可构建：登录、首页、题库、练习、背单词、知识手册、分数线、资料、个人中心。
- 租户后台第一批 H5 页面已经可构建：工作台、数据看板、学生/班级、题库内容、营销中心、租户设置。
- 平台后台第一批 H5 页面已经可构建：工作台、租户管理、账务中心、公共题库授权。
- 可以继续复刻旧题库学生端主要视觉和交互：选地区、刷题细节、视频解析、题目反馈、模考报告、错题复习、商城收银台、订单详情、勋章展示。
- 可以按新后端主模型接入内容导航：
  - `content_entries`
  - `content_nodes`
  - `question_collections`
  - `practice_blueprints`
- 可以接入迁移期短信登录和 `tk_` session，用于本地/内网联调。
- H5 可以直接用 Supabase Auth access token 调 `apps/api`；后端已支持 JWT 验签和业务用户映射。
- H5 可以优先验证 `@supabase/supabase-js` 管理 Auth session；微信小程序端先验证运行时兼容性，业务数据默认仍走 `apps/api`。
- 可以接入租户品牌、主题、功能开关和域名/小程序参数解析。
- 租户后台可以接入角色模板 API：`/api/tenant-admin/role-templates`，用于运营、教师、销售、代理等自定义菜单/模块/字段可见性。
- 租户后台可以接入勋章管理和手动发放：`GET/PUT /api/tenant-admin/badges`、`GET/POST /api/tenant-admin/badge-grants`；学生端用 `GET /api/profile/badges` 展示成就。

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

- 生产鉴权已具备 Supabase JWT API 入口，自定义角色模板基础 API 已可用；仍要做真实云端 Auth/JWKS 回归、RLS 深测和班级/学生范围权限细化，前端不要继续使用 `x-user-id`。
- 不要把“Supabase 支持前端 Data API”误解为“本项目所有业务表都由 Taro 直写”；订单、支付、权益、租户后台、导入、CRM、私有资源必须走 RPC、`apps/api`、Edge Function 或 worker 这类后端命令层。
- 短信、微信小程序/网页登录、QQ 登录、微信支付、支付宝支付 provider 已有本地 adapter 和测试覆盖；生产账号、回调域名、证书和商户资料仍需正式联调。
- 对象存储已完成签名 provider、上传后校验、PDF/图片预览和资源复检 worker，但 CDN 防盗链、视频水印和杀毒扫描还要补。
- 题目/单词/知识手册/分数线/视频 JSON/CSV/Excel 导入已可联调；大批量导入可传 `executionMode=async` 交给 imports worker；模板下载、字段映射 API 和导入后复检已可用，前端还要补上传预览、排队轮询、问题行展示、模板下载按钮、字段映射 UI 和复检结果面板。
- 数据看板、分佣结算和勋章手动发放基础 API 已可联调；勋章自动发放、分佣真实打款/导出/凭证、AI 择校、主题模板市场等仍是后续商用增强项。

## 前后端协作建议

- 前端先做页面骨架和 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/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` |
| 背单词 | `apps/taro/src/pages/student/vocabulary/index.tsx` | `vocabulary-units`、`vocabulary-words`、`vocabulary/review-plan`、`vocabulary/review` |
| 知识手册 | `apps/taro/src/pages/student/handbook/index.tsx` | `handbook-subjects`、`handbook-chapters`、`handbook-entries` |
| 分数线 | `apps/taro/src/pages/student/scoreline/index.tsx` | `scoreline/records` |
| 资料 | `apps/taro/src/pages/student/assets/index.tsx` | `assets`、`assets/preview`、`assets/download` |
| 个人中心 | `apps/taro/src/pages/student/profile/index.tsx` | `profile/me`、`check-in`、`badges`、`exam-countdowns`、`svip-plans`、`orders`、`entitlements`、`activation-codes`、`leaderboard` |

当前页面主要用于打通接口和路由，后续 UI 需要继续按旧题库视觉和 Taro H5/小程序限制优化。

## 已落地的 Taro 租户后台页面

| 页面 | 文件 | 已接接口 |
| --- | --- | --- |
| 工作台 | `apps/taro/src/pages/tenant-admin/workbench/index.tsx` | `tenant-admin/overview`、`tenant-admin/dashboard` |
| 数据看板 | `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/students` |
| 题库内容 | `apps/taro/src/pages/tenant-admin/content/index.tsx` | `tenant-content/content-entries`、`tenant-content/imports`、`tenant-content/public-question-banks` |
| 营销中心 | `apps/taro/src/pages/tenant-admin/marketing/index.tsx` | `tenant-admin/coupons`、`code-batches`、`activation-codes`、`crm/queue`、`commission/summary` |
| 租户设置 | `apps/taro/src/pages/tenant-admin/settings/index.tsx` | `tenant-admin/overview`、`domains`、`payment-accounts`、`auth-providers`、`role-templates` |

当前页面以运营看板和只读列表为主。下一批需要继续补后台写入表单、导入 preview/import/issue 操作台、公共题库采纳/同步按钮、学生批量导入、角色模板配置 UI 和权限驱动菜单。

## 已落地的 Taro 平台后台页面

| 页面 | 文件 | 已接接口 |
| --- | --- | --- |
| 工作台 | `apps/taro/src/pages/platform-admin/workbench/index.tsx` | `platform-admin/overview`、`tenants`、`invoices`、`question-banks`、`question-bank-grants` |
| 租户管理 | `apps/taro/src/pages/platform-admin/tenants/index.tsx` | `platform-admin/tenants`、`POST tenants`、`PATCH tenants/status` |
| 账务中心 | `apps/taro/src/pages/platform-admin/billing/index.tsx` | `platform-admin/plans`、`invoices`、`usage`、`subscriptions`、`invoices/from-subscription`、`invoices/payments/manual-confirm`、`POST usage` |
| 公共题库 | `apps/taro/src/pages/platform-admin/question-banks/index.tsx` | `platform-admin/question-banks`、`question-bank-grants`、`PUT question-bank-grants` |

当前平台后台已经具备第一批写操作台：创建租户、状态变更、订阅开通、账单生成、人工收款确认、用量录入、公共题库授权编辑；这些动作均经过前端基础校验和二次确认，后端继续执行真实权限和审计。下一批继续补租户详情页、编辑租户基础资料、平台审计报表、自动计费、账单批量操作和更细平台权限点。