docs: translate readme to chinese

2026-06-21 21:59:43 +08:00
parent c9c767c7bd
commit efce192844
1 changed files with 84 additions and 72 deletions
--- 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。