xiongyuxing/gongxue-base

Fork 0

forked from wangziqi/gongxue-base

Files

Codex 2f0c3028b4 chore: clean root workspace structure

2026-06-28 20:28:27 +08:00

6.8 KiB

Raw Blame History

tiku-supabase

这是题库项目从 PocketBase/SQLite 重构到 Supabase/PostgreSQL 的新后端仓库。

当前仓库重点承载“商用 SaaS 版本”的新架构代码，包括多租户数据库、业务 API、PocketBase 数据导入器、本地验证脚本和重构进度文档。旧 PocketBase/React 项目仍保留在原工作区作为功能参照和迁移来源，但这个 Git 仓库不打算作为旧项目全量镜像。

当前状态

更新时间：2026-06-28

目前已经完成并在本地验证通过的内容：

Supabase/PostgreSQL 多租户数据库 schema、RLS、索引、触发器。
apps/api 独立业务 API，后续供 H5、Taro 小程序、管理后台统一调用。
租户后台能力：品牌、域名、公开设置、支付账户、登录配置、私密密钥掩码、活动内容、激活码、优惠券、成员权限、审计日志。
租户内容能力：可配置题库入口、任意深度分类树、考试意向标记、题目集合、顺序/随机/全真模拟蓝图、题目录入/更新、视频绑定、分数线、单词、知识手册、资料资源台账、题目/单词/知识手册 JSON 批量导入。
学生端能力：题库入口、分类树、题目集合、顺序/随机/模考 session 组卷快照、答题、错题本、收藏夹、背单词进度、个人中心、分数线、题目视频、订单、权益、激活码兑换、资料下载。
平台后台能力：租户管理、SaaS 套餐、订阅、账单、服务费收款、用量记录。
销售/代理/CRM 增长链路：邀请码、扫码/分享事件、首绑客资保护、销售统计、团队关系、CRM 配置和队列。
PocketBase schema/数据导入器雏形和导入后校验脚本。
本地 Supabase reset、烟测 seed、API 集成测试、完整重构检查命令。

还没有达到生产交付的部分：

正式 Supabase Auth/JWT 鉴权还没替换迁移期请求头。
真实短信、微信登录、QQ 登录、微信支付、支付宝等 provider adapter 还没接完。
OSS/COS/Supabase Storage 上传下载签名 provider 已接入；上传后校验、PDF 预览、防盗链和视频水印还没完成。
Excel/CSV 导入、分数线/视频批量导入和异步 worker 还没完成。
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/content-import-contract.md
docs/refactor/object-storage.md
docs/refactor/project-structure.md
docs/refactor/next-development-todo.md
docs/refactor/blueprint-coverage.md
docs/refactor/api-structure.md

目录结构

apps/api/                   Node.js 业务 API
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：

npm install
npm run supabase:start
npm run supabase:reset
npm run db:smoke-seed
npm run dev:api

默认本地数据库：

postgresql://postgres:postgres@127.0.0.1:54322/postgres

默认 API 地址：

http://127.0.0.1:8787

验证命令

完整后端重构检查：

npm run check:refactor

这个命令会依次执行：

API TypeScript 检查
PocketBase importer TypeScript 检查
PocketBase 导入后校验
本地 smoke seed
API 构建
本地 API 集成测试

常用单项命令：

npm run check:api
npm run check:importer
npm run pb:import:validate
npm run test:api

API 模块

当前 API 目录：

apps/api/src/features/
  auth/              短信登录、迁移期 session、OAuth 占位
  catalog/           学生端目录、内容入口、分类树、题目集合、资料、商城只读接口
  commerce/          订单、支付确认、激活码、权益
  health/            健康检查
  learning/          练习 session 组卷、答题、错题、收藏、学习进度
  platform-admin/    平台方租户、SaaS 套餐、订阅、账单、用量
  profile/           学生个人中心
  referral/          销售/代理客资追踪、CRM 队列
  scoreline/         分数线
  tenant/            租户解析
  tenant-admin/      租户后台配置、成员权限、活动和审计
  tenant-content/    租户内容导航、题库维护、资源管理、批量导入
  video/             题目视频讲解

迁移期 API 上下文目前使用：

x-tenant-id
x-user-id
x-platform-admin-key

生产环境必须替换为 Supabase Auth/JWT 或服务端 session。

重要安全约定

租户公开配置不能存放密钥。
商户密钥、短信密钥、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 必须先设计幂等键和验签流程，再进入生产使用。

下一步建议

优先继续补：

对象存储上传后校验、PDF 预览、防盗链和视频水印。
Excel/CSV 以及分数线、视频批量导入；把现有 JSON 导入升级为可排队异步执行。
Supabase Auth/JWT 正式鉴权和生产 RLS 验证。
微信/QQ 登录、短信、微信支付、支付宝支付 adapter。
Taro 前端 scaffold，让 H5 和小程序共用同一套 API。

6.8 KiB Raw Blame History Unescape Escape