fischerX/docs/development/project-structure.md

项目结构说明

> 文档版本: v1.0.0 > 创建日期: 2026-05-25 > 适用范围: FischerX 项目开发人员

目录

• 整体架构
• 目录结构详解
• Monorepo 工作流
• 包依赖关系

---

整体架构

FischerX 采用 Monorepo 架构，使用 Turborepo 作为构建工具，pnpm 作为包管理器。项目分为以下几个主要部分：

FischerX/
├── apps/          # 应用层 - 用户可访问的应用
├── packages/      # 共享包 - 可复用的代码和组件
├── services/      # 后端服务 - API 和业务逻辑
├── infra/         # 基础设施 - Docker、K8s 配置
├── docs/          # 文档 - 项目文档和架构文档
└── tools/         # 工具 - 开发工具和脚本

架构图

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 请求/响应类型
• 数据库模型类型
• 通用数据类型

使用示例:

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 提供了智能的缓存和并行构建功能。

常用命令：

# 运行所有包的 dev 命令
pnpm dev

# 构建所有包
pnpm build

# 运行所有包的 lint
pnpm lint

# 运行所有包的 test
pnpm test

# 清除所有缓存
pnpm clean

过滤特定包

使用 --filter 参数来运行特定包的命令：

# 只运行 web 应用的 dev
pnpm --filter web dev

# 只构建 api 服务
pnpm --filter api build

# 运行所有 packages 下的包
pnpm --filter "@fischerx/*" build

添加依赖

# 在特定包中添加依赖
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

---

添加新包

添加新应用

# 创建应用目录
mkdir -p apps/new-app

# 初始化 package.json
cd apps/new-app
pnpm init

# 编辑 package.json，添加必要的依赖和脚本

添加新共享包

# 创建包目录
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 中配置新包的构建管道。

---

下一步

• 开发规范 - 了解项目的编码规范
• 最佳实践 - 学习最佳实践
• 贡献指南 - 了解如何贡献代码

---

> 文档维护: 本文档由开发团队维护，如有问题或建议请提交 Issue。 > 最后更新: 2026-05-25