# 前端交接索引

更新时间：2026-07-12

这份文件是给 Taro/H5/小程序前端同事的入口。`apps/taro` 已经是唯一的新前端工程，后续应在该工程内重构，不要重新新建第二套 Taro 工程，也不要把旧 React/Vite 前端搬回根目录。

开始设计或改页面前先读 `production-foundation-baseline-20260712.md`。该文件冻结了当前 API、身份和状态机边界，并区分了“可以开始前端”与“已经可切生产流量”。浏览器现状证据见 `taro-h5-browser-qa-20260712.md`。

## 2026-07-12 接管重点

接管后先确认当前候选分支和工作区，不要依赖历史 commit 文案判断是否最新：

```bash
git status --short --branch
git log -3 --oneline
```

本轮前端变化的边界：

- 学生端不是营销 landing page，而是旧题库式学习应用：首页直接呈现学习状态、题库入口、模块入口和最近学习，不再用大 hero、大圆角卡片或紫蓝渐变。
- 租户后台和平台后台不是官网风格，而是旧后台式工作台：信息密度更高、控件更紧凑、侧边栏清晰、移动端保留可用导航。
- 登录/权限校验期间，受保护页面只显示校验态或跳转，不渲染真实业务列表、表格和操作按钮。
- 视觉守卫已经按旧题库风格改写，后续如果确实要新增渐变、超大圆角或特殊装饰，必须先更新 `docs/refactor/taro-visual-language.md` 并让守卫有明确例外。

接管后建议先跑这一组最小验证：

```bash
npm --workspace @tiku-saas/taro run check
node scripts/taro-route-contract-test.js
npm run guard:taro:visual
node scripts/taro-visual-guardrails-test.js
npm run build:taro:h5:student
npm run build:taro:h5:tenant
npm run build:taro:h5:platform
npm run smoke:taro:h5
```

准备上线或改动关键交互时，再补：

```bash
npm run smoke:taro:h5:interaction
node scripts/taro-h5-release-guardrails-test.js
```

## 必读顺序

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/taro-visual-language.md`
   - 学生端、租户后台、平台后台的视觉语言、旧题库参考边界、旧题库圆润尺度/蓝色网格工作台规范和 CSS 守卫。
9. `docs/refactor/taro-production-integration-checklist.md`
   - 正式接 Supabase Auth、三套 H5、真实 provider、runtime-config 和上线门禁时逐项对照。
10. `docs/refactor/multitenant-auth-security-contract.md`
   - 多租户、鉴权、权限、资源签名和生产安全红线。
11. `docs/refactor/content-import-contract.md`
   - 后台内容导入、题目 JSON、单词、知识手册、分数线、视频的后端校验契约。
12. `docs/refactor/production-launch-evidence.template.json`
   - 上线前证据文件模板；真实生产验收结果填入 `production-launch-evidence.json` 后运行 `npm run launch:gate`，该真实证据文件不入 Git。

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

- `apps/taro` 已经建立，且学生端第一批 H5 页面已经可构建：登录、首页、地区选择、题库、练习、错题/收藏、练习报告、视频解析、会员收银台、订单详情、背单词、知识手册、分数线、资料、个人中心。
- 租户后台第一批 H5 页面已经可构建：工作台、数据看板、学生/班级、题库内容、营销中心、财务运营、租户设置；工作台已接 `/api/tenant-admin/permissions` 做权限驱动模块入口；学生运营页已具备学生创建/更新、状态禁用/恢复、批量导入、批量分班、学生备注、跟进任务、跟进看板、学习督导候选预览/生成、督导规则保存和 CRM 批量推送第一版；题库内容页已具备公共题库采纳/同步、同步通知、冲突查看、单条/批量采纳平台版本或保留本地版本、导入任务详情、异步轮询、导入问题查看、模板预览/下载、导入后复检详情、JSON/CSV/Excel 选择文件或粘贴内容、后端预览、字段别名覆盖和同步/异步执行导入的第一版操作能力；营销中心已具备 CRM 配置、CRM 队列查看、CRM 死信处理、销售/代理转化看板、分佣规则、成员分佣比例、分佣订单、结算单生成/审核/标记打款、优惠券规则/核销报表、积分任务/兑换、积分风控只读摘要和用户通知查看第一版；财务运营页已具备退款申请/审核/供应商提交与查询、官方账单下载任务、对账批次/异常明细、差错工单处理、人工调整凭证提交/复核和异常订单运营台第一版；租户设置页已具备主题模板、草稿预览/发布、角色模板新建、编辑、停用、成员搜索/新建、成员绑定模板、成员状态和额外权限覆盖第一版。
- 平台后台第一批 H5 页面已经可构建：工作台、租户管理、账务中心、公共题库授权、平台员工；启动时应先接 `GET /api/platform-admin/permissions` 获取 `effective` 权限用于菜单和按钮可见性；租户管理页已接租户详情、账务资料编辑和最近平台审计，平台员工页已接员工列表、搜索、创建/编辑、权限点勾选、禁用和恢复，工作台已展示最近平台审计摘要、支持导出最近平台审计 CSV，并可查看开放审计告警、确认或解决告警，也能查看审计告警外部通知渠道、催缴外部通知渠道和最近发送事件摘要；账务中心已接订阅账单候选预览、dry-run、批量生成、自动计费生成结果查看、用量超额账单候选预览/dry-run/生成/自动开票 worker、逾期预览、内部催缴生成、催缴记录查看和用量台账查看。平台用量由 `platform-usage` worker 从后端权威表采集，超额费用由后端按套餐额度统一计算，前端不要自行统计答题记录、资源大小、订单或视频播放后计算服务费。
- 可以继续复刻旧题库学生端主要视觉和交互：勋章展示、小程序端分享/支付体验和更完整复盘体验。地区选择、刷题答题卡、后端权威断点续练、本地进度恢复、模拟倒计时、主观题后端自评、阅读理解/案例分析多小题、题干/选项/解析 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`。
- 新增、删除或重命名 Taro 页面时必须同步 `apps/taro/src/app.config.ts`、启动页跳转、H5 静态烟测入口和本文页面清单，并运行 `node scripts/taro-route-contract-test.js`。该脚本会阻断“页面文件存在但未注册”“路由注册但文件缺失”“启动页或烟测跳到不存在页面”的漂移。
- 新增或修改 Taro API service 时必须运行 `node scripts/taro-api-contract-test.js`。该脚本会比对前端 `apiRequest('/api/...')` 与后端 `RouteDefinition[]` 注册表，阻断调用不存在的接口、method 写错或绕过统一 API client；动态路由只能通过脚本 allowlist 明确声明。
- 修改学生端、租户后台或平台后台关键页面时必须运行 `node scripts/taro-persona-contract-test.js`。该脚本按学生刷题/会员订单/错题收藏、租户学生运营/内容导入/营销财务/品牌权限、平台租户/账务/公共题库/员工权限三类角色旅程检查路由和服务调用，避免前端样式重做时误删核心业务入口。
- 修改 Taro CSS 或新建页面样式时必须运行 `npm run guard:taro:visual`。该脚本会阻断超过旧题库尺度的大圆角、视口字体、负字距、装饰性径向渐变、裸模糊背景和未登记线性渐变；视觉规范见 `docs/refactor/taro-visual-language.md`。
- H5 构建完成后必须运行 `npm run smoke:taro:h5:interaction` 做真实浏览器点击验证。它会覆盖学生首页到题库练习、答题、收藏、会员收银台下单/支付参数/订单状态，租户后台工作台到题库内容/财务运营，以及平台后台工作台到租户管理/账务中心；如果 Chrome/Edge 缺失，可设置 `TARO_H5_SMOKE_BROWSER` 指向 Chromium 浏览器。
- H5 可以优先验证 `@supabase/supabase-js` 管理 Auth session；微信小程序端先验证运行时兼容性，业务数据默认仍走 `apps/api`。
- H5 生产部署优先用每个静态目录自己的 `runtime-config.json` 配置 `apiBaseUrl`、`supabaseUrl`、`supabasePublishableKey`、`tenantCode`；不要为了换域名重打包，也不要把任何 service role、数据库、支付、短信、对象存储密钥放进该文件。
- 学生端当前 production 入口约 `500 KiB`，前端重构必须先建立路由拆包、延迟加载和资源预算；视觉组件不得无约束进入首包。
- 上线前需要把三套 H5 构建、`npm run smoke:taro:h5` 静态启动烟测、`npm run smoke:taro:h5:interaction` 真实浏览器交互烟测、严格 `taro-h5-release-guardrails-test --require-runtime-config`、`runtime-config.json` 人工复核、真实 Auth/RLS、迁移 dry-run、对象存储、支付对账、`security:repo` 和真实 `@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/tenant-admin/points-risk-report`、`GET /api/tenant-admin/feedbacks/report`；学生端用 `GET /api/profile/badges` 展示成就，通过 `POST /api/profile/check-in` 自动领取 `daily_check_in` 任务奖励，并通过 `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` 做用户通知查看。通知只做展示、站内安全跳转、已读、忽略和归档状态，业务权限和权益仍以后端源接口为准；前端不得按通知 payload 打开外链、后台路径或未知页面。
- 学生头像是产品级约束：学生端只展示男女预设头像，个人中心已接二选一保存 UI，前端不要做头像上传、裁剪、对象存储签名或微信/QQ 头像同步；排行榜也是可选活动能力，默认不请求、不展示，日常学习激励以后台配置勋章自动发放为主。

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

- 生产鉴权已具备 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`、`vocabulary/stats`；已接今日计划、单元学习、收藏练习、学习概览、掌握率、计划拆分、收藏数、卡片翻转、发音、美/英音切换、本地进度恢复和单词跳转 |
| 知识手册 | `apps/taro/src/pages/student/handbook/index.tsx` | `handbook-subjects`、`handbook-chapters`、`handbook-entries`；已接 RichContent 阅读渲染、章节内搜索、安全文本摘要高亮和目录定位第一版 |
| 分数线 | `apps/taro/src/pages/student/scoreline/index.tsx` | `scoreline/fields`、`scoreline/schools`、`scoreline/majors`、`scoreline/years`、`scoreline/records`、`scoreline/trend`；已接目标地区默认筛选、院校/专业/年份 chip、租户动态字段过滤、结果字段 chip 和趋势摘要第一版 |
| AI 择校 | `apps/taro/src/pages/student/ai-school/index.tsx` | `ai/school-recommendations/generate`、`ai/school-recommendations`、`ai/school-recommendations/detail`、`ai/school-recommendations/export`；已接 SVIP 报告生成、历史报告、Markdown/HTML 导出第一版 |
| 资料 | `apps/taro/src/pages/student/assets/index.tsx` | `assets`、`assets/preview`、`assets/download`；已接短期签名、过期信息、可见水印覆盖、traceId 展示和强制水印资源外部预览限制 |
| 消息中心 | `apps/taro/src/pages/student/notifications/index.tsx` | `profile/notifications`、`profile/notifications/status`；已接未读/已读/归档/全部筛选、类型筛选、批量已读、单条已读、归档、忽略和学生端站内路径白名单跳转 |
| 个人中心 | `apps/taro/src/pages/student/profile/index.tsx` | `profile/me`、`PATCH profile/me.avatarPreset`、`check-in`、`score-events`、`badges`、`exam-countdowns`、`svip-plans`、`orders`、`entitlements`、`activation-codes`、`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 -> 答题卡/答题/主观题自评/复合题多小题/收藏/反馈/视频 -> 交卷报告逐题复盘 -> 错题/收藏复习”，背单词已经覆盖“单元 -> 今日计划/全单元/收藏练习 -> 学习概览/掌握率/收藏数 -> 卡片翻转 -> 发音 -> 认识/再记上报 -> 本地恢复”，知识手册已经覆盖“科目 -> 章节 -> 章节内搜索 -> 目录定位 -> RichContent 阅读”，分数线已经覆盖“目标地区 -> 院校/专业/年份 -> 租户动态字段筛选 -> 结果字段 chip -> 趋势摘要”，AI 择校已经覆盖“SVIP 生成报告 -> 历史报告 -> Markdown/HTML 导出或小程序复制报告文本”，资料页已经覆盖“列表 -> 申请预览/下载短签名 -> 展示水印 traceId -> H5 水印容器预览或确认下载”，个人中心已经覆盖“基础资料 -> 学习报告 -> 14 天趋势 -> 题型表现 -> 最近练习 -> 勋章/签到 -> 会员/订单/激活码 -> 积分任务/兑换/明细 -> 消息摘要”，独立消息中心已经覆盖“筛选 -> 已读/归档/忽略 -> 站内安全跳转”，会员闭环已经覆盖“选套餐 -> 领优惠券 -> 下单 -> 创建支付参数 -> 状态轮询 -> 订单详情/售后入口”。`apps/taro/src/components/RichContent.tsx` 是学生端题干、选项、解析和知识手册的统一安全渲染组件：它只支持受控 Markdown 图片、基础表格、粗体、代码和被 parser 识别出的公式 token；H5 端用 KaTeX 渲染 `$...$`、`$$...$$`、`\(...\)`、`\[...\]`，私有题图可用 `asset:<uuid>`、`content_asset:<uuid>` 或 `/asset/<uuid>` 资源引用向后端申请短期预览签名。知识手册搜索摘要使用纯文本片段高亮，不把搜索词拼成 HTML 注入正文。组件不执行导入内容中的任意 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`、`students/followups/report`、`students/supervision/preview`、`students/supervision/generate`、`students/supervision/rules`、`students/crm-push` |
| 题库内容 | `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`、`crm/dead-letters`、`crm/queue/logs`、`crm/queue/action`、`referral/conversion-report`、`commission/settings`、`member-rate`、`summary`、`orders`、`settlements`、`settlements/generate`、`settlements/status`、`tenant-admin/feedbacks/report`、`tenant-admin/point-activity-tasks`、`tenant-admin/point-activity-claims`、`tenant-admin/point-exchange-items`、`tenant-admin/point-exchange-orders`、`tenant-admin/points-risk-report`、`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` |

当前租户后台已有第一批运营操作：工作台按权限矩阵隐藏不可见模块；学生运营页支持学生创建/更新、状态禁用/恢复、批量导入、批量分班、学生备注、跟进任务、完成跟进、跟进看板、学习督导候选预览/一键生成跟进任务、保存每日督导规则和 CRM 入队推送；题库内容页支持公共题库采纳/同步、同步通知查看与已读/忽略、同步冲突查看、单条/批量采纳平台版本或保留本地版本、导入任务详情、异步 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/permissions`、`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/usage-overage-candidates`、`invoices/from-usage-overage`、`invoices/payments/manual-confirm`、`usage`、`subscriptions`、`POST usage`；`GET usage` 会展示 `platform-usage` worker 生成的月度快照和手工调整记录，`POST usage` 仅用于人工补录/调整；超额账单只展示后端返回的候选、明细和金额，不在前端计算 |
| 公共题库 | `apps/taro/src/pages/platform-admin/question-banks/index.tsx` | `platform-admin/question-banks`、`question-bank-grants`、`PUT question-bank-grants` |
| 平台员工 | `apps/taro/src/pages/platform-admin/staff/index.tsx` | `platform-admin/permissions`、`platform-admin/staff`、`PUT platform-admin/staff`、`PATCH platform-admin/staff/status` |

当前平台后台已经具备第一批写操作台：创建租户、租户详情查看、状态变更、账务资料维护、平台员工创建/编辑/禁用恢复、平台员工权限点勾选、最近平台审计查询、最近平台审计 CSV 导出、开放审计告警确认/解决、审计告警外部通知渠道/事件摘要、催缴外部通知渠道/事件摘要、订阅开通、账单生成、订阅账单候选预览、dry-run、批量生成、自动计费生成结果查看、用量超额账单候选预览、超额 dry-run、超额账单生成、人工收款确认、逾期预览、内部催缴生成、催缴记录查看、用量录入、公共题库授权编辑；这些动作均经过前端基础校验和二次确认，后端继续执行真实权限、重复开票保护和审计。平台后台的菜单和按钮必须用 `platform-admin/permissions` 返回的 `effective` 做可见性控制，但安全边界仍以后端 `PLATFORM_PERMISSION_REQUIRED` 为准。平台员工创建必须绑定 Supabase Auth 用户 ID，前端只提交公开资料和权限点，不创建密码账号、不接触 service role；禁用员工时应调用 `PATCH /api/platform-admin/staff/status` 并默认 `revokeSessions=true`。平台审计导出只开放给具备 `platform:audit:export` 的平台账号，后端会对导出 `details` 中的 token/secret/password/key 等敏感字段脱敏，并返回 `contentBase64 + sha256`，H5 可直接下载，小程序端建议先展示“已生成，需在 H5 管理台下载”。平台审计告警由 `platform-audit-alerts` worker 从高风险平台审计动作和自动化失败生成，用量超额开票 worker 失败会先写入 `platform.invoice.usage_overage_worker_failed` 脱敏审计再进入告警；外部通知由 `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。下一批继续补租户基础资料编辑增强、平台审计告警升级策略、平台催缴通知配置操作台细节和平台在线收款。