forked from wangziqi/gongxue-base
197 lines
9.2 KiB
Markdown
197 lines
9.2 KiB
Markdown
# tiku-supabase
|
||
|
||
这是题库项目从 PocketBase/SQLite 重构到 Supabase/PostgreSQL 的新后端仓库。
|
||
|
||
当前仓库重点承载“商用 SaaS 版本”的新架构代码，包括多租户数据库、业务 API、PocketBase 数据导入器、本地验证脚本和重构进度文档。旧 PocketBase/React 项目仍保留在原工作区作为功能参照和迁移来源，但这个 Git 仓库不打算作为旧项目全量镜像。
|
||
|
||
## 当前状态
|
||
|
||
更新时间：2026-06-29
|
||
|
||
目前已经完成并在本地验证通过的内容：
|
||
|
||
- Supabase/PostgreSQL 多租户数据库 schema、RLS、索引、触发器。
|
||
- `apps/api` 独立业务 API，后续供 H5、Taro 小程序、管理后台统一调用；已支持 Supabase Auth JWT 和迁移期 `tk_` session 双入口。
|
||
- 租户后台能力：品牌、域名、公开设置、支付账户、登录配置、私密密钥掩码、活动内容、考试日期、题目反馈处理、激活码、优惠券、成员权限、自定义角色模板、班级/教师/学生范围权限、学生批量导入、批量分班、学生备注、跟进任务、审计日志。
|
||
- 租户内容能力：可配置题库入口、任意深度分类树、考试意向标记、题目集合、顺序/随机/全真模拟蓝图、题目录入/更新、视频绑定、分数线、单词、知识手册、资料资源台账、题目/单词/知识手册 JSON 批量导入。
|
||
- 学生端能力：题库入口、分类树、题目集合、顺序/随机/模考 session 组卷快照、答题、错题本、收藏夹、背单词进度、个人中心、考试倒计时、签到积分、题目反馈、排行榜、分数线、题目视频、订单详情/状态轮询、优惠券领取/抵扣、权益、激活码预检查/兑换、资料下载。
|
||
- 平台后台能力：租户管理、SaaS 套餐、订阅、账单、服务费收款、用量记录。
|
||
- 销售/代理/CRM 增长链路：邀请码、扫码/分享事件、首绑客资保护、销售统计、团队关系、CRM 配置和队列。
|
||
- `apps/worker` 后台任务进程：CRM webhook 队列消费、generic/钉钉/飞书/企微机器人发送、签名、失败重试和日志。
|
||
- 销售/代理分佣结算基础闭环：租户默认比例、成员比例、激活码批次比例、订单/激活码归因、结算单生成、审核、线下打款状态和权限隔离。
|
||
- 订单售后基础闭环：退款请求、审核、处理状态流、退款金额累计、部分/全额退款订单状态、全额退款权益撤销、退款事件和审计日志。
|
||
- PocketBase schema/数据导入器雏形和导入后校验脚本。
|
||
- 本地 Supabase reset、烟测 seed、API 集成测试、完整重构检查命令。
|
||
|
||
还没有达到生产交付的部分：
|
||
|
||
- Supabase Auth/JWT、租户角色模板、班级/教师/学生范围权限已可联调；生产前还要做真实云端 Auth/JWKS 回归和 RLS 深测。
|
||
- 阿里云/腾讯云短信、微信小程序登录、微信支付、支付宝主链路和微信/支付宝发起退款已完成本地适配；微信网页登录、QQ 登录、手机号换绑、退款通知/查询确认、对账、支付补偿和真实生产账号联调还没接完。
|
||
- OSS/COS/Supabase Storage 上传下载签名 provider 已接入；上传后校验、PDF 预览、防盗链和视频水印还没完成。
|
||
- Excel/CSV 导入、分数线/视频批量导入和异步 worker 还没完成。
|
||
- 分佣真实打款、结算导出、发票/凭证、CRM 轮询/定向分配、富卡片模板、失败告警和销售转化看板还没完成。
|
||
- Taro 跨端前端还没开始 scaffold。
|
||
- 根目录已清理为新 Supabase SaaS monorepo 编排层；旧 PocketBase/React 项目和旧构建产物仅保留在 `参考/` 目录作为迁移参考，不进入 Git 提交。
|
||
|
||
更完整的进度看这些文档：
|
||
|
||
- `docs/refactor/implementation-status.md`
|
||
- `docs/refactor/backend-progress.md`
|
||
- `docs/refactor/backend-handoff-roadmap.md`
|
||
- `docs/refactor/ai-development-guardrails.md`
|
||
- `docs/refactor/content-import-contract.md`
|
||
- `docs/refactor/object-storage.md`
|
||
- `docs/refactor/project-structure.md`
|
||
- `docs/refactor/frontend-handoff-index.md`
|
||
- `docs/refactor/backend-capability-status.md`
|
||
- `docs/refactor/legacy-feature-gap-matrix.md`
|
||
- `docs/refactor/supabase-frontend-access-strategy.md`
|
||
- `docs/refactor/taro-frontend-integration.md`
|
||
- `docs/refactor/multitenant-auth-security-contract.md`
|
||
- `docs/refactor/next-development-todo.md`
|
||
- `docs/refactor/blueprint-coverage.md`
|
||
- `docs/refactor/api-structure.md`
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
apps/api/ Node.js 业务 API
|
||
apps/worker/ 后台异步任务：CRM webhook、后续支付补偿/导入复检等
|
||
packages/config/ 共享配置
|
||
packages/db/ PostgreSQL 连接池和查询封装
|
||
packages/domain/ 领域常量和共享类型
|
||
supabase/migrations/ 数据库迁移：schema、RLS、索引、触发器
|
||
supabase/seed.sql 最小租户 seed
|
||
scripts/import-pocketbase/ PocketBase schema/数据导入器和校验器
|
||
scripts/smoke-seed.js 本地集成测试 seed 数据
|
||
scripts/api-integration-test.js
|
||
docs/refactor/ 重构架构、进度、治理文档
|
||
docker-compose.api.yml API 容器化运行配置
|
||
```
|
||
|
||
旧项目参考文件在本机 `F:\project\参考\旧题库项目`，旧前端构建产物在 `F:\project\参考\旧构建产物`。这两个目录都只用于对照和迁移，不作为当前新项目源码。
|
||
|
||
## 本地开发
|
||
|
||
前置要求：
|
||
|
||
- Node.js 20+
|
||
- Docker Desktop
|
||
- Supabase CLI
|
||
|
||
启动本地 Supabase 和 API：
|
||
|
||
```bash
|
||
npm install
|
||
npm run supabase:start
|
||
npm run supabase:reset
|
||
npm run db:smoke-seed
|
||
npm run dev:api
|
||
```
|
||
|
||
单次运行 CRM worker：
|
||
|
||
```bash
|
||
npm --workspace @tiku-saas/worker run crm:once
|
||
```
|
||
|
||
默认本地数据库：
|
||
|
||
```text
|
||
postgresql://postgres:postgres@127.0.0.1:54322/postgres
|
||
```
|
||
|
||
默认 API 地址：
|
||
|
||
```text
|
||
http://127.0.0.1:8787
|
||
```
|
||
|
||
## 验证命令
|
||
|
||
完整后端重构检查：
|
||
|
||
```bash
|
||
npm run check:refactor
|
||
```
|
||
|
||
这个命令会依次执行：
|
||
|
||
- API TypeScript 检查
|
||
- PocketBase importer TypeScript 检查
|
||
- PocketBase 导入后校验
|
||
- 本地 smoke seed
|
||
- API 构建
|
||
- 本地 API 集成测试
|
||
|
||
常用单项命令：
|
||
|
||
```bash
|
||
npm run check:api
|
||
npm run check:worker
|
||
npm run check:importer
|
||
npm run pb:import:validate
|
||
npm run test:api
|
||
npm run test:worker:crm
|
||
```
|
||
|
||
## API 模块
|
||
|
||
当前 API 目录：
|
||
|
||
```text
|
||
apps/api/src/features/
|
||
auth/ 短信登录、迁移期 session、OAuth 占位
|
||
catalog/ 学生端目录、内容入口、分类树、题目集合、资料、商城只读接口
|
||
commerce/ 订单、支付确认、激活码、优惠券、权益
|
||
health/ 健康检查
|
||
learning/ 练习 session 组卷、答题、错题、收藏、学习进度、排行榜
|
||
platform-admin/ 平台方租户、SaaS 套餐、订阅、账单、用量
|
||
profile/ 学生个人中心
|
||
referral/ 销售/代理客资追踪、CRM 队列
|
||
referral/commission.ts
|
||
分佣设置、汇总、来源明细、结算单、审核/打款状态
|
||
scoreline/ 分数线
|
||
tenant/ 租户解析
|
||
tenant-admin/ 租户后台配置、成员权限、班级学生、活动和审计
|
||
tenant-content/ 租户内容导航、题库维护、资源管理、批量导入
|
||
video/ 题目视频讲解
|
||
```
|
||
|
||
API 身份上下文：
|
||
|
||
- 推荐：`Authorization: Bearer <supabase_access_token>`，可配合 `x-tenant-id` 提供当前租户上下文。
|
||
- 本地/迁移期：`Authorization: Bearer <tk_session>`。
|
||
- 兼容旧测试：`x-user-id`、`x-platform-admin-key` 仅允许在 `ALLOW_LEGACY_AUTH_HEADERS=true`、`ALLOW_PLATFORM_ADMIN_KEY=true` 的非生产环境使用。
|
||
|
||
生产环境必须设置 `ALLOW_LEGACY_AUTH_HEADERS=false` 和 `ALLOW_PLATFORM_ADMIN_KEY=false`，前端不能再传 `x-user-id` 代表当前用户。
|
||
|
||
## 重要安全约定
|
||
|
||
- 租户公开配置不能存放密钥。
|
||
- 商户密钥、短信密钥、OAuth app secret 等必须进入 `app_private.tenant_secrets`，或后续生产 KMS/Vault。
|
||
- 资料、PDF、视频等资源必须先进入 `content_assets` 台账，再由 API 校验权限并下发签名 URL。
|
||
- 题库入口和分类使用 `content_entries/content_nodes`；题目列表和练习规则使用 `question_collections/practice_blueprints`，前端不要再把旧树字段当成唯一业务结构。
|
||
- 批量导入必须先写 `content_import_jobs/items/issues`，保留原始 payload、规范化 payload、逐行问题和审计记录。题目、单词、知识手册导入已走这套后台校验管线，前端只做预检查和预览展示。
|
||
- 支付 webhook 必须先设计幂等键和验签流程，再进入生产使用。
|
||
|
||
## 最近一次验证
|
||
|
||
最近本地验证命令：
|
||
|
||
```text
|
||
npm run check:refactor
|
||
```
|
||
|
||
结果：通过。
|
||
|
||
## 下一步建议
|
||
|
||
优先继续补：
|
||
|
||
1. 真实云端 Auth/JWKS 回归、RLS 深测和生产环境配置验收。
|
||
2. Taro 前端 scaffold，让 H5 和小程序共用同一套 API。
|
||
3. 对象存储上传后校验、PDF 预览、防盗链和视频水印。
|
||
4. Excel/CSV 以及分数线、视频批量导入；把现有 JSON 导入升级为可排队异步执行。
|
||
5. 微信网页/QQ 登录、退款通知/查询确认、支付对账、支付补偿、公共题库版本同步 worker、积分活动深化，以及排行榜防刷/预聚合。
|