diff --git a/README.md b/README.md index 8d916f5a..5ecd1d79 100644 --- a/README.md +++ b/README.md @@ -1,64 +1,66 @@ # tiku-supabase -PocketBase/SQLite question-bank product rebuilt as a Supabase/PostgreSQL multi-tenant SaaS backend. +这是题库项目从 PocketBase/SQLite 重构到 Supabase/PostgreSQL 的新后端仓库。 -This repository is the new reconstruction workspace for the commercial SaaS version. The old PocketBase/React project remains as the migration reference in the original workspace, but this Git repository should focus on the new backend, database schema, importer, and delivery documentation. +当前仓库重点承载“商用 SaaS 版本”的新架构代码，包括多租户数据库、业务 API、PocketBase 数据导入器、本地验证脚本和重构进度文档。旧 PocketBase/React 项目仍保留在原工作区作为功能参照和迁移来源，但这个 Git 仓库不打算作为旧项目全量镜像。 -## Current Status +## 当前状态 -Updated: 2026-06-21 +更新时间：2026-06-21 -Implemented and locally verified: +目前已经完成并在本地验证通过的内容： -- Supabase/PostgreSQL multi-tenant schema, RLS policies, indexes, and triggers. -- Node.js business API under `apps/api`, shared by future H5, Taro mini program, and admin clients. -- Tenant admin APIs for branding, domain, settings, payment accounts, login providers, secrets, marketing content, activation codes, coupons, members, permissions, and audit logs. -- Tenant content APIs for questions, videos, scorelines, vocabulary, handbook content, content assets, and question JSON import. -- Student APIs for catalog, practice sessions, answers, wrong questions, favorites, vocabulary progress, profile, scorelines, question videos, orders, entitlements, activation-code redemption, and content asset download. -- Platform admin APIs for tenants, SaaS plans, subscriptions, invoices, payments, usage records, and billing profiles. -- Referral/CRM growth APIs for invite codes, first-binding lead protection, sales/agent teams, CRM config, and CRM queue. -- PocketBase schema/data importer scaffold with validation. -- Local Supabase reset, smoke seed, API integration tests, and refactor check command. +- Supabase/PostgreSQL 多租户数据库 schema、RLS、索引、触发器。 +- `apps/api` 独立业务 API，后续供 H5、Taro 小程序、管理后台统一调用。 +- 租户后台能力：品牌、域名、公开设置、支付账户、登录配置、私密密钥掩码、活动内容、激活码、优惠券、成员权限、审计日志。 +- 租户内容能力：题目录入/更新、视频绑定、分数线、单词、知识手册、资料资源台账、题目 JSON 批量导入。 +- 学生端能力：题库目录、刷题 session、答题、错题本、收藏夹、背单词进度、个人中心、分数线、题目视频、订单、权益、激活码兑换、资料下载。 +- 平台后台能力：租户管理、SaaS 套餐、订阅、账单、服务费收款、用量记录。 +- 销售/代理/CRM 增长链路：邀请码、扫码/分享事件、首绑客资保护、销售统计、团队关系、CRM 配置和队列。 +- PocketBase schema/数据导入器雏形和导入后校验脚本。 +- 本地 Supabase reset、烟测 seed、API 集成测试、完整重构检查命令。 -Still not production complete: +还没有达到生产交付的部分： -- Supabase Auth/JWT and full production RLS validation must replace migration-period headers. -- Real SMS/OAuth/payment provider adapters are still pending. -- Real OSS/COS/Supabase Storage signed upload/download adapters are still pending. -- Excel/CSV import, vocabulary/handbook/scoreline/video import, and async import worker are pending. -- Taro frontend scaffold is pending. +- 正式 Supabase Auth/JWT 鉴权还没替换迁移期请求头。 +- 真实短信、微信登录、QQ 登录、微信支付、支付宝等 provider adapter 还没接完。 +- 真实 OSS/COS/Supabase Storage 上传下载签名还没接完。 +- Excel/CSV 导入、单词/手册/分数线/视频批量导入和异步 worker 还没完成。 +- Taro 跨端前端还没开始 scaffold。 -See: +更完整的进度看这些文档： - `docs/refactor/implementation-status.md` - `docs/refactor/backend-progress.md` - `docs/refactor/blueprint-coverage.md` - `docs/refactor/api-structure.md` -## Repository Layout +## 目录结构 ```text -apps/api/ Node.js business API -packages/config/ Shared config defaults -packages/db/ PostgreSQL pool/query helpers -packages/domain/ Domain constants and shared types -supabase/migrations/ PostgreSQL schema, RLS, indexes, triggers -supabase/seed.sql Minimal tenant seed -scripts/import-pocketbase/ PocketBase schema/data importer and validator -scripts/smoke-seed.js Local integration-test seed data +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/ Reconstruction architecture and progress docs -docker-compose.api.yml API container compose file +docs/refactor/ 重构架构、进度、治理文档 +docker-compose.api.yml API 容器化运行配置 ``` -## Local Development +## 本地开发 -Prerequisites: +前置要求： - Node.js 20+ - Docker Desktop - Supabase CLI +启动本地 Supabase 和 API： + ```bash npm install npm run supabase:start @@ -67,36 +69,36 @@ npm run db:smoke-seed npm run dev:api ``` -Default local database: +默认本地数据库： ```text postgresql://postgres:postgres@127.0.0.1:54322/postgres ``` -API defaults to: +默认 API 地址： ```text http://127.0.0.1:8787 ``` -## Verification +## 验证命令 -Run the full backend reconstruction check: +完整后端重构检查： ```bash npm run check:refactor ``` -This runs: +这个命令会依次执行： -- API TypeScript check -- PocketBase importer TypeScript check -- PocketBase import validation -- smoke seed -- API build -- local API integration test +- API TypeScript 检查 +- PocketBase importer TypeScript 检查 +- PocketBase 导入后校验 +- 本地 smoke seed +- API 构建 +- 本地 API 集成测试 -Useful individual commands: +常用单项命令： ```bash npm run check:api @@ -105,50 +107,60 @@ npm run pb:import:validate npm run test:api ``` -## API Modules +## API 模块 -Current API feature folders: +当前 API 目录： ```text apps/api/src/features/ - auth/ - catalog/ - commerce/ - health/ - learning/ - platform-admin/ - profile/ - referral/ - scoreline/ - tenant/ - tenant-admin/ - tenant-content/ - video/ + auth/ 短信登录、迁移期 session、OAuth 占位 + catalog/ 学生端目录、题库、资料、商城只读接口 + commerce/ 订单、支付确认、激活码、权益 + health/ 健康检查 + learning/ 答题、错题、收藏、学习进度 + platform-admin/ 平台方租户、SaaS 套餐、订阅、账单、用量 + profile/ 学生个人中心 + referral/ 销售/代理客资追踪、CRM 队列 + scoreline/ 分数线 + tenant/ 租户解析 + tenant-admin/ 租户后台配置、成员权限、活动和审计 + tenant-content/ 租户内容维护、资源管理、批量导入 + video/ 题目视频讲解 ``` -Migration-period API context: +迁移期 API 上下文目前使用： - `x-tenant-id` - `x-user-id` - `x-platform-admin-key` -Production must replace these with Supabase Auth/JWT/server-side sessions. +生产环境必须替换为 Supabase Auth/JWT 或服务端 session。 -## Security Notes +## 重要安全约定 -- Tenant public payment/login config must not contain secrets. -- Secrets go to `app_private.tenant_secrets` or future production KMS/Vault. -- Asset download must go through API authorization and signed URL generation. -- Content import must write job/item/issue records before final import. -- Payment webhooks must be idempotent before production use. +- 租户公开配置不能存放密钥。 +- 商户密钥、短信密钥、OAuth app secret 等必须进入 `app_private.tenant_secrets`，或后续生产 KMS/Vault。 +- 资料、PDF、视频等资源必须先进入 `content_assets` 台账，再由 API 校验权限并下发签名 URL。 +- 批量导入必须先写 `content_import_jobs/items/issues`，保留原始 payload、规范化 payload、逐行问题和审计记录。 +- 支付 webhook 必须先设计幂等键和验签流程，再进入生产使用。 -## Latest Verified Check +## 最近一次验证 -Last local verification: +最近本地验证命令： ```text npm run supabase:reset npm run check:refactor ``` -Result: passed. +结果：通过。 + +## 下一步建议 + +优先继续补： + +1. 真实对象存储 adapter：阿里云 OSS、腾讯云 COS 或 Supabase Storage。 +2. Excel/CSV 以及单词、知识手册、分数线、视频批量导入。 +3. Supabase Auth/JWT 正式鉴权和生产 RLS 验证。 +4. 微信/QQ 登录、短信、微信支付、支付宝支付 adapter。 +5. Taro 前端 scaffold，让 H5 和小程序共用同一套 API。