569 lines
12 KiB
Markdown
569 lines
12 KiB
Markdown
# 项目结构说明
|
||
|
||
> **文档版本**: v1.0.0
|
||
> **创建日期**: 2026-05-25
|
||
> **适用范围**: FischerX 项目开发人员
|
||
|
||
## 目录
|
||
|
||
- [整体架构](#整体架构)
|
||
- [目录结构详解](#目录结构详解)
|
||
- [Monorepo 工作流](#monorepo-工作流)
|
||
- [包依赖关系](#包依赖关系)
|
||
|
||
---
|
||
|
||
## 整体架构
|
||
|
||
FischerX 采用 **Monorepo** 架构，使用 **Turborepo** 作为构建工具，**pnpm** 作为包管理器。项目分为以下几个主要部分：
|
||
|
||
```
|
||
FischerX/
|
||
├── apps/ # 应用层 - 用户可访问的应用
|
||
├── packages/ # 共享包 - 可复用的代码和组件
|
||
├── services/ # 后端服务 - API 和业务逻辑
|
||
├── infra/ # 基础设施 - Docker、K8s 配置
|
||
├── docs/ # 文档 - 项目文档和架构文档
|
||
└── tools/ # 工具 - 开发工具和脚本
|
||
```
|
||
|
||
### 架构图
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "应用层 (apps)"
|
||
Web[Web 应用 (Next.js)]
|
||
Admin[管理后台 (Next.js)]
|
||
Mobile[移动应用 (React Native)]
|
||
MiniApp[小程序]
|
||
end
|
||
|
||
subgraph "共享层 (packages)"
|
||
Types[类型定义 @fischerx/types]
|
||
Constants[常量 @fischerx/constants]
|
||
Utils[工具函数 @fischerx/utils]
|
||
Config[配置管理 @fischerx/config]
|
||
UI[UI 组件库 @fischerx/ui]
|
||
Core[核心业务 @fischerx/core]
|
||
end
|
||
|
||
subgraph "服务层 (services)"
|
||
API[API 服务 (NestJS)]
|
||
Worker[后台任务 Worker]
|
||
Realtime[实时通信服务]
|
||
end
|
||
|
||
subgraph "数据层"
|
||
PostgreSQL[(PostgreSQL)]
|
||
Redis[(Redis)]
|
||
Storage[对象存储]
|
||
end
|
||
|
||
Web --> Types
|
||
Web --> UI
|
||
Web --> Utils
|
||
Web --> API
|
||
|
||
Admin --> Types
|
||
Admin --> UI
|
||
Admin --> Utils
|
||
Admin --> API
|
||
|
||
API --> Types
|
||
API --> Core
|
||
API --> PostgreSQL
|
||
API --> Redis
|
||
API --> Storage
|
||
```
|
||
|
||
---
|
||
|
||
## 目录结构详解
|
||
|
||
### apps/ - 应用层
|
||
|
||
包含所有可独立部署的应用程序。
|
||
|
||
```
|
||
apps/
|
||
├── web/ # Web 应用 - 面向用户的主应用
|
||
│ ├── src/
|
||
│ │ ├── app/ # Next.js App Router 页面
|
||
│ │ ├── components/ # 应用专属组件
|
||
│ │ ├── hooks/ # 应用专属 Hooks
|
||
│ │ ├── lib/ # 工具函数
|
||
│ │ └── styles/ # 样式文件
|
||
│ ├── public/ # 静态资源
|
||
│ └── package.json
|
||
│
|
||
└── admin/ # 管理后台 - 内部管理系统
|
||
├── src/
|
||
│ ├── app/
|
||
│ ├── components/
|
||
│ └── ...
|
||
└── package.json
|
||
```
|
||
|
||
#### apps/web/ - Web 应用
|
||
|
||
基于 Next.js 的 Web 应用，提供用户界面。
|
||
|
||
**主要技术栈：**
|
||
- Next.js 16 (App Router)
|
||
- React 18
|
||
- TypeScript
|
||
- Tailwind CSS
|
||
- Shadcn UI
|
||
- Zustand (状态管理)
|
||
- React Query (数据获取)
|
||
- React Hook Form (表单)
|
||
|
||
**端口配置：**
|
||
- 开发: 3000
|
||
- 生产: 3000
|
||
|
||
#### apps/admin/ - 管理后台
|
||
|
||
基于 Next.js 的管理后台，提供内部管理功能。
|
||
|
||
**端口配置：**
|
||
- 开发: 3001
|
||
- 生产: 3001
|
||
|
||
---
|
||
|
||
### packages/ - 共享包
|
||
|
||
包含可在多个应用和服务之间共享的代码。
|
||
|
||
```
|
||
packages/
|
||
├── types/ # 类型定义
|
||
│ ├── src/
|
||
│ │ └── index.ts
|
||
│ └── package.json
|
||
│
|
||
├── constants/ # 常量定义
|
||
│ ├── src/
|
||
│ │ └── index.ts
|
||
│ └── package.json
|
||
│
|
||
├── utils/ # 工具函数
|
||
│ ├── src/
|
||
│ │ └── index.ts
|
||
│ └── package.json
|
||
│
|
||
├── config/ # 配置管理
|
||
│ ├── src/
|
||
│ │ └── index.ts
|
||
│ └── package.json
|
||
│
|
||
├── ui/ # UI 组件库
|
||
│ ├── src/
|
||
│ │ ├── components/
|
||
│ │ └── index.ts
|
||
│ └── package.json
|
||
│
|
||
└── core/ # 核心业务逻辑
|
||
├── src/
|
||
│ ├── auth/
|
||
│ ├── user/
|
||
│ ├── payment/
|
||
│ └── index.ts
|
||
└── package.json
|
||
```
|
||
|
||
#### packages/types/ - 类型定义
|
||
|
||
**包名:** `@fischerx/types`
|
||
|
||
共享的 TypeScript 类型定义，包括：
|
||
- API 请求/响应类型
|
||
- 数据库模型类型
|
||
- 通用数据类型
|
||
|
||
**使用示例:**
|
||
```typescript
|
||
import type { User, CreateUserInput } from '@fischerx/types';
|
||
```
|
||
|
||
#### packages/constants/ - 常量定义
|
||
|
||
**包名:** `@fischerx/constants`
|
||
|
||
共享的常量定义，包括：
|
||
- 路由常量
|
||
- 环境变量键名
|
||
- 错误码
|
||
- 配置默认值
|
||
|
||
#### packages/utils/ - 工具函数
|
||
|
||
**包名:** `@fischerx/utils`
|
||
|
||
共享的工具函数，包括：
|
||
- 日期处理
|
||
- 字符串处理
|
||
- 数字处理
|
||
- 验证函数
|
||
|
||
#### packages/config/ - 配置管理
|
||
|
||
**包名:** `@fischerx/config`
|
||
|
||
共享的配置管理，包括：
|
||
- 环境配置
|
||
- 应用配置
|
||
- 服务配置
|
||
|
||
#### packages/ui/ - UI 组件库
|
||
|
||
**包名:** `@fischerx/ui`
|
||
|
||
共享的 UI 组件库，基于 Shadcn UI，包括：
|
||
- 基础组件 (Button, Input, Card 等)
|
||
- 复合组件 (Form, Table, Modal 等)
|
||
- 布局组件
|
||
|
||
#### packages/core/ - 核心业务逻辑
|
||
|
||
**包名:** `@fischerx/core`
|
||
|
||
共享的核心业务逻辑，包括：
|
||
- 认证授权
|
||
- 用户管理
|
||
- 支付逻辑
|
||
- 权限控制
|
||
|
||
---
|
||
|
||
### services/ - 后端服务
|
||
|
||
包含后端服务和 API。
|
||
|
||
```
|
||
services/
|
||
├── api/ # API 服务 - 主 API 服务
|
||
│ ├── src/
|
||
│ │ ├── controllers/ # 控制器
|
||
│ │ ├── services/ # 业务服务
|
||
│ │ ├── models/ # 数据模型
|
||
│ │ ├── middleware/ # 中间件
|
||
│ │ ├── guards/ # 守卫
|
||
│ │ ├── filters/ # 过滤器
|
||
│ │ ├── interceptors/ # 拦截器
|
||
│ │ ├── pipes/ # 管道
|
||
│ │ ├── modules/ # 模块
|
||
│ │ └── main.ts
|
||
│ ├── prisma/ # Prisma Schema
|
||
│ │ └── schema.prisma
|
||
│ ├── test/ # 测试文件
|
||
│ └── package.json
|
||
│
|
||
├── worker/ # 后台任务 Worker
|
||
│ ├── src/
|
||
│ │ ├── jobs/ # 任务定义
|
||
│ │ └── main.ts
|
||
│ └── package.json
|
||
│
|
||
└── realtime/ # 实时通信服务
|
||
├── src/
|
||
│ └── main.ts
|
||
└── package.json
|
||
```
|
||
|
||
#### services/api/ - API 服务
|
||
|
||
基于 NestJS 的 RESTful API 服务。
|
||
|
||
**主要技术栈：**
|
||
- NestJS 11
|
||
- Prisma 6 (ORM)
|
||
- PostgreSQL (数据库)
|
||
- Redis (缓存)
|
||
- Passport.js (认证)
|
||
- JWT (Token)
|
||
- Class Validator (验证)
|
||
- Swagger (API 文档)
|
||
|
||
**端口配置：**
|
||
- 开发: 4000
|
||
- 生产: 4000
|
||
|
||
**API 文档地址：**
|
||
- 开发: http://localhost:4000/api/docs
|
||
- 生产: https://api.your-domain.com/api/docs
|
||
|
||
#### services/worker/ - 后台任务
|
||
|
||
处理异步任务和定时任务。
|
||
|
||
**技术栈：**
|
||
- NestJS
|
||
- Bull (队列)
|
||
- Redis
|
||
|
||
---
|
||
|
||
### infra/ - 基础设施
|
||
|
||
包含基础设施配置。
|
||
|
||
```
|
||
infra/
|
||
├── docker/ # Docker 配置
|
||
│ ├── docker-compose.yml
|
||
│ ├── Dockerfile.api
|
||
│ ├── Dockerfile.web
|
||
│ └── Dockerfile.admin
|
||
│
|
||
├── k8s/ # Kubernetes 配置
|
||
│ ├── deployments/
|
||
│ ├── services/
|
||
│ ├── ingresses/
|
||
│ └── configmaps/
|
||
│
|
||
├── terraform/ # Terraform 配置
|
||
│ ├── main.tf
|
||
│ ├── variables.tf
|
||
│ └── outputs.tf
|
||
│
|
||
└── scripts/ # 脚本
|
||
├── deploy.sh
|
||
├── backup.sh
|
||
└── migrate.sh
|
||
```
|
||
|
||
---
|
||
|
||
### docs/ - 文档
|
||
|
||
包含项目文档。
|
||
|
||
```
|
||
docs/
|
||
├── architecture/ # 架构文档
|
||
│ ├── overview.md
|
||
│ ├── tech-stack.md
|
||
│ ├── module-design.md
|
||
│ └── design-decisions/ # ADR
|
||
│
|
||
├── development/ # 开发文档
|
||
│ ├── quick-start.md
|
||
│ ├── project-structure.md
|
||
│ ├── coding-standards.md
|
||
│ ├── best-practices.md
|
||
│ ├── troubleshooting.md
|
||
│ ├── contributing.md
|
||
│ ├── migration-guide.md
|
||
│ ├── standards/
|
||
│ ├── best-practices/
|
||
│ └── guides/
|
||
│
|
||
├── api/ # API 文档
|
||
│ ├── README.md
|
||
│ ├── authentication/
|
||
│ ├── user/
|
||
│ ├── payment/
|
||
│ └── error-codes.md
|
||
│
|
||
├── deployment/ # 部署文档
|
||
│ ├── environment-setup.md
|
||
│ ├── docker-guide.md
|
||
│ ├── kubernetes-guide.md
|
||
│ ├── aliyun-guide.md
|
||
│ └── ci-cd-pipeline.md
|
||
│
|
||
├── operations/ # 运维文档
|
||
│ ├── monitoring/
|
||
│ ├── logging/
|
||
│ ├── troubleshooting/
|
||
│ └── backup-restore/
|
||
│
|
||
├── user/ # 用户文档
|
||
│ ├── getting-started.md
|
||
│ ├── user-manual.md
|
||
│ ├── usage-guide/
|
||
│ └── faq.md
|
||
│
|
||
└── templates/ # 文档模板
|
||
```
|
||
|
||
---
|
||
|
||
### 根目录文件
|
||
|
||
```
|
||
FischerX/
|
||
├── package.json # 根 package.json
|
||
├── pnpm-workspace.yaml # pnpm workspace 配置
|
||
├── turbo.json # Turborepo 配置
|
||
├── tsconfig.json # TypeScript 配置
|
||
├── .eslintrc.js # ESLint 配置
|
||
├── .prettierrc # Prettier 配置
|
||
├── .editorconfig # EditorConfig
|
||
├── .gitignore # Git 忽略
|
||
├── .env.example # 环境变量示例
|
||
├── README.md # 项目说明
|
||
├── CHANGELOG.md # 变更日志
|
||
├── LICENSE # 许可证
|
||
└── .github/ # GitHub 配置
|
||
├── workflows/ # GitHub Actions
|
||
└── ISSUE_TEMPLATE/ # Issue 模板
|
||
```
|
||
|
||
---
|
||
|
||
## Monorepo 工作流
|
||
|
||
### 使用 Turborepo
|
||
|
||
Turborepo 提供了智能的缓存和并行构建功能。
|
||
|
||
**常用命令：**
|
||
|
||
```bash
|
||
# 运行所有包的 dev 命令
|
||
pnpm dev
|
||
|
||
# 构建所有包
|
||
pnpm build
|
||
|
||
# 运行所有包的 lint
|
||
pnpm lint
|
||
|
||
# 运行所有包的 test
|
||
pnpm test
|
||
|
||
# 清除所有缓存
|
||
pnpm clean
|
||
```
|
||
|
||
### 过滤特定包
|
||
|
||
使用 `--filter` 参数来运行特定包的命令：
|
||
|
||
```bash
|
||
# 只运行 web 应用的 dev
|
||
pnpm --filter web dev
|
||
|
||
# 只构建 api 服务
|
||
pnpm --filter api build
|
||
|
||
# 运行所有 packages 下的包
|
||
pnpm --filter "@fischerx/*" build
|
||
```
|
||
|
||
### 添加依赖
|
||
|
||
```bash
|
||
# 在特定包中添加依赖
|
||
pnpm --filter web add lodash
|
||
|
||
# 在特定包中添加开发依赖
|
||
pnpm --filter web add -D @types/lodash
|
||
|
||
# 在工作区根目录添加依赖（所有包共享）
|
||
pnpm add -w typescript
|
||
|
||
# 在包之间添加内部依赖
|
||
pnpm --filter web add @fischerx/ui@workspace:*
|
||
pnpm --filter api add @fischerx/types@workspace:*
|
||
```
|
||
|
||
---
|
||
|
||
## 包依赖关系
|
||
|
||
### 依赖规则
|
||
|
||
1. **应用层 (apps/)** 可以依赖所有共享包和后端服务 API
|
||
2. **共享包 (packages/)** 之间可以相互依赖，但要避免循环依赖
|
||
3. **服务层 (services/)** 可以依赖共享包，但不能依赖应用层
|
||
4. **所有包** 都应该使用 `workspace:*` 来引用内部包
|
||
|
||
### 依赖图
|
||
|
||
```
|
||
apps/web
|
||
├── @fischerx/types
|
||
├── @fischerx/constants
|
||
├── @fischerx/utils
|
||
├── @fischerx/config
|
||
├── @fischerx/ui
|
||
└── @fischerx/core
|
||
|
||
apps/admin
|
||
├── @fischerx/types
|
||
├── @fischerx/constants
|
||
├── @fischerx/utils
|
||
├── @fischerx/config
|
||
├── @fischerx/ui
|
||
└── @fischerx/core
|
||
|
||
services/api
|
||
├── @fischerx/types
|
||
├── @fischerx/constants
|
||
├── @fischerx/utils
|
||
├── @fischerx/config
|
||
└── @fischerx/core
|
||
|
||
packages/ui
|
||
├── @fischerx/types
|
||
├── @fischerx/constants
|
||
└── @fischerx/utils
|
||
|
||
packages/core
|
||
├── @fischerx/types
|
||
├── @fischerx/constants
|
||
└── @fischerx/utils
|
||
```
|
||
|
||
---
|
||
|
||
## 添加新包
|
||
|
||
### 添加新应用
|
||
|
||
```bash
|
||
# 创建应用目录
|
||
mkdir -p apps/new-app
|
||
|
||
# 初始化 package.json
|
||
cd apps/new-app
|
||
pnpm init
|
||
|
||
# 编辑 package.json，添加必要的依赖和脚本
|
||
```
|
||
|
||
### 添加新共享包
|
||
|
||
```bash
|
||
# 创建包目录
|
||
mkdir -p packages/new-package/src
|
||
|
||
# 初始化 package.json
|
||
cd packages/new-package
|
||
pnpm init
|
||
|
||
# 设置包名（使用 @fischerx 前缀）
|
||
# package.json: "name": "@fischerx/new-package"
|
||
```
|
||
|
||
### 更新 turbo.json
|
||
|
||
如果需要，在 `turbo.json` 中配置新包的构建管道。
|
||
|
||
---
|
||
|
||
## 下一步
|
||
|
||
- [开发规范](./coding-standards.md) - 了解项目的编码规范
|
||
- [最佳实践](./best-practices.md) - 学习最佳实践
|
||
- [贡献指南](./contributing.md) - 了解如何贡献代码
|
||
|
||
---
|
||
|
||
> **文档维护**: 本文档由开发团队维护，如有问题或建议请提交 Issue。
|
||
> **最后更新**: 2026-05-25
|