forked from wangziqi/gongxue-base
188 lines
7.4 KiB
Markdown
188 lines
7.4 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
|
||
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、租户解析、主题配置、登录、支付、资料下载和刷题链路放在新工程内。
|