docs: organize legacy reference project

2026-06-28 20:15:37 +08:00
parent 492706e24f
commit 02148c7b8b
3 changed files with 241 additions and 0 deletions
--- a/docs/refactor/project-structure.md
+++ b/docs/refactor/project-structure.md
@@ -0,0 +1,123 @@
+# 项目结构说明
+
+更新时间：2026-06-28
+
+这份文档用于区分新 Supabase/PostgreSQL 重构项目和旧 PocketBase 题库参考项目，避免后续提交 Gitea 时把旧项目文件混入新仓库。
+
+## 当前仓库原则
+
+- Git 跟踪的新项目代码，是商用 SaaS 重构后的后端、数据库迁移、导入工具、测试脚本和重构文档。
+- 旧 PocketBase/React 题库项目只作为功能对照、数据迁移参考和前端样式参考，不作为当前 Gitea 仓库的源码主体。
+- 旧项目参考文件集中放在 `参考/旧题库项目/`，该目录被 `.gitignore` 忽略，不会进入提交。
+
+## 新重构项目目录
+
+```text
+F:\project
+  apps/
+    api/                         Node.js 业务 API
+      src/
+        core/                    配置、HTTP、路由、数据库访问
+        features/                业务模块
+          auth/                  迁移期登录、短信 mock、OAuth 占位
+          catalog/               学生端目录、题库、资料、商品只读接口
+          commerce/              订单、支付确认、激活码、权益
+          health/                健康检查
+          learning/              练习、答题、错题、收藏、单词进度
+          platform-admin/        平台租户、套餐、账单、用量
+          profile/               学生个人中心
+          referral/              销售/代理/CRM 增长链路
+          scoreline/             分数线
+          storage/               对象存储签名 provider
+          tenant/                租户解析
+          tenant-admin/          租户后台配置、成员权限、审计
+          tenant-content/        租户内容后台、导入、资源台账
+          video/                 题目视频讲解
+        types/                   第三方 SDK 窄类型声明
+      Dockerfile
+      package.json
+      tsconfig.json
+
+  packages/
+    config/                      共享配置和 env 工具
+    db/                          PostgreSQL 连接池和查询封装
+    domain/                      领域常量和共享类型
+
+  supabase/
+    migrations/                  PostgreSQL schema、RLS、索引、触发器
+    seed.sql                     本地最小 seed
+    config.toml                  Supabase local 配置
+
+  scripts/
+    import-pocketbase/           PocketBase schema/数据导入器和校验器
+    api-integration-test.js      API 集成测试
+    smoke-seed.js                本地 smoke seed
+    smoke-core-api.js            轻量核心 API 烟测
+
+  docs/
+    pb_schema.json               旧 PocketBase schema 输入文件
+    refactor/                    新架构、进度、交付和 TODO 文档
+
+  docker-compose.api.yml         API 容器运行配置
+  package.json                   工作区脚本入口
+  README.md                      中文项目总览
+```
+
+## 旧项目参考目录
+
+旧项目已经整理到：
+
+```text
+F:\project\参考\旧题库项目
+```
+
+其中主要内容：
+
+```text
+参考/旧题库项目/
+  src/                           旧 React/Vite 前端
+  pb_hooks/                      旧 PocketBase hooks
+  pb_migrations/                 旧 PocketBase migrations
+  docs/                          旧项目功能、导入、对接、部署文档
+  public/                        旧前端静态资源
+  scripts/                       旧项目迁移、部署、统计、卫星站脚本
+  setup/                         旧项目安装配置
+  DEPLOY.md                      旧宝塔/PocketBase 部署说明
+  index.html                     旧 Vite 入口
+  vite.config.ts                 旧 Vite 配置
+  tailwind.config.js             旧 Tailwind 配置
+  tsconfig.json                  旧前端 TS 配置
+```
+
+## 后续提交规范
+
+提交前建议先看：
+
+```bash
+git status --short --branch
+```
+
+正常情况下，后续提交应只包含这些路径：
+
+- `apps/api/**`
+- `packages/**`
+- `supabase/**`
+- `scripts/import-pocketbase/**`
+- `scripts/api-integration-test.js`
+- `scripts/smoke-seed.js`
+- `scripts/smoke-core-api.js`
+- `docs/refactor/**`
+- `docs/pb_schema.json`
+- 根目录的 `.env.example`、`.gitignore`、`README.md`、`package.json`、`package-lock.json`、`docker-compose.api.yml`
+
+如果看到 `参考/旧题库项目/**`，说明 `.gitignore` 被改坏了，必须先修复再提交。
+
+## 前端重构建议
+
+后续 Taro 前端建议新建：
+
+```text
+apps/taro/
+```
+
+不要把旧 `src/` 重新搬回根目录继续开发。旧前端只作为视觉、页面、交互和字段迁移参考；新 Taro 应统一调用 `apps/api`，并把跨端 API client、租户解析、主题配置、登录、支付、资料下载和刷题链路放在新工程内。