# 项目结构说明

更新时间：2026-06-28

这份文档用于区分新 Supabase/PostgreSQL 重构项目和旧 PocketBase 题库参考项目，避免后续提交 Gitea 时把旧项目文件混入新仓库。

## 当前仓库原则

- Git 跟踪的新项目代码，是商用 SaaS 重构后的后端、数据库迁移、导入工具、测试脚本和重构文档。
- 旧 PocketBase/React 题库项目只作为功能对照、数据迁移参考和前端样式参考，不作为当前 Gitea 仓库的源码主体。
- 旧项目参考文件集中放在 `参考/旧题库项目/`、`参考/旧题库小程序前端文件/` 和 `参考/旧题库数据库文件/`，这些目录被 `.gitignore` 忽略，不会进入提交。
- 旧前端构建产物、临时打包结果和与新 Supabase 技术栈无关的材料，统一放入 `参考/` 或被 `.gitignore` 忽略，根目录只保留新 monorepo 的工程入口。

## 新重构项目目录

```text
F:\project
  apps/
    api/                         Node.js 业务 API
      src/
        core/                    配置、HTTP、路由、数据库访问
        features/                业务模块
          auth/                  迁移期登录、短信、微信小程序/网页登录、QQ 登录
          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
    worker/                      后台异步任务进程
      src/
        jobs/
          crm.ts                 CRM webhook 队列消费、签名、重试、日志
        config.ts                worker 环境变量
        db.ts                    worker 数据库连接
        index.ts                 worker CLI/常驻循环入口
      package.json
      tsconfig.json
    taro/                        Taro 4 React 跨端前端
      src/
        services/                统一 API client、Auth、Supabase client、缓存
        pages/
          bootstrap/             租户解析和三入口分流
          student/               学生学习端 H5/小程序页面
          tenant-admin/          租户后台工作台和运营页面
          platform-admin/        平台超级管理员后台页面
      config/                    Taro 构建配置，按 portal 输出三套 H5 产物
      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                   新 Supabase SaaS 工作区脚本入口
  README.md                      中文项目总览
```

根目录不再承载旧 React/Vite 前端源码和构建脚本。后续前端重构应新建 `apps/taro/`，由 Taro 同时服务 H5 和小程序，统一调用 `apps/api`。

## 旧项目参考目录

旧项目已经整理到：

```text
F:\project\参考\旧题库项目
```

旧构建产物已经整理到：

```text
F:\project\参考\旧构建产物
```

旧原生小程序前端参考位于：

```text
F:\project\参考\旧题库小程序前端文件
```

旧 PocketBase SQLite 数据和 storage 参考位于：

```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 配置
```

旧构建产物目录目前主要包含：

```text
参考/旧构建产物/
  dist-admin/                    旧后台构建输出
  dist-public/                   旧学生端构建输出
```

旧小程序前端只用于后续 Taro H5/小程序补齐微信登录、分享、支付容器、页面状态和刷题交互细节；不得继续沿用旧 PocketBase 直连、旧鉴权或旧本地权限判断。旧数据库文件目前包含 `data.db`、`auxiliary.db`、备份 SQLite 文件和 `storage/`，只用于本地只读导出、`scripts/import-pocketbase` dry-run、mapper 修复和抽样验收；不得提交到 Gitea，也不得在文档或日志中输出真实手机号、openid、支付单号等敏感数据。

## 后续提交规范

提交前建议先看：

```bash
git status --short --branch
```

正常情况下，后续提交应只包含这些路径：

- `apps/api/**`
- `apps/worker/**`
- `apps/taro/**`
- `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` 被改坏了，必须先修复再提交。

如果根目录重新出现这些文件或目录，一般应先确认是否属于旧栈残留，再移动到 `参考/` 或删除本地临时产物：

- `src/`
- `public/`
- `dist-admin/`
- `dist-public/`
- `index.html`
- `vite.config.ts`
- `tailwind.config.js`
- 旧 React/Vite/PocketBase 相关 package 入口

## 前端重构建议

后续 Taro 前端建议新建：

```text
apps/taro/
```

不要把旧 `src/` 重新搬回根目录继续开发。旧前端只作为视觉、页面、交互和字段迁移参考；新 Taro 应统一调用 `apps/api`，并把跨端 API client、租户解析、主题配置、登录、支付、资料下载和刷题链路放在新工程内。