forked from wangziqi/gongxue-base
174 lines
6.6 KiB
Markdown
174 lines
6.6 KiB
Markdown
# 项目结构说明
|
|
|
|
更新时间：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
|
|
参考/旧题库项目/
|
|
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/ 旧学生端构建输出
|
|
```
|
|
|
|
## 后续提交规范
|
|
|
|
提交前建议先看：
|
|
|
|
```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、租户解析、主题配置、登录、支付、资料下载和刷题链路放在新工程内。
|