# 项目结构说明

> **文档版本**: 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