项目结构说明

更新时间：2026-06-28

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

当前仓库原则

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

新重构项目目录

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。

旧项目参考目录

旧项目已经整理到：

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

旧构建产物已经整理到：

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

其中主要内容：

参考/旧题库项目/
  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 配置

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

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

后续提交规范

提交前建议先看：

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 前端建议新建：

apps/taro/

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

6.6 KiB Raw Blame History Unescape Escape