forked from wangziqi/gongxue-base
57 lines
4.4 KiB
Markdown
57 lines
4.4 KiB
Markdown
# 前端交接索引
|
||
|
||
更新时间：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`。
|
||
- 可以复刻旧题库学生端主要视觉和交互：登录、选地区、首页、刷题、背单词、知识手册、分数线、资料、商城、个人中心、勋章。
|
||
- 可以按新后端主模型接入内容导航：
|
||
- `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 为准。
|