# ADR-0001: 采用 Monorepo 架构

| 项目 | 内容 |
|------|------|
| **状态** | 已接受 |
| **创建日期** | 2026-05-25 |
| **决策者** | 架构师 |
| **最后更新** | 2026-05-25 |

## 上下文

在项目启动阶段，需要决定代码仓库的组织方式。现代软件开发中有两种主流方式：
- **Monorepo（单体仓库）**: 所有相关代码放在同一个仓库中
- **Polyrepo（多仓库）**: 每个模块/服务独立一个仓库

## 决策

决定采用 **Monorepo** 架构，使用 Turborepo 作为构建工具。

## 理由

### 为什么选择 Monorepo

| 优势 | 说明 |
|------|------|
| **代码共享** | 前后端可以共享类型定义、工具函数、常量等 |
| **依赖管理** | 统一管理依赖版本，避免版本冲突 |
| **原子提交** | 跨模块的修改可以在同一个提交中完成 |
| **重构方便** | 跨项目重构更容易，IDE 支持更好 |
| **统一工具链** | 统一的构建、测试、lint 配置 |
| **团队协作** | 团队成员可以方便地查看和修改所有代码 |

### 为什么选择 Turborepo

| 优势 | 说明 |
|------|------|
| **增量构建** | 只重新构建变更的包，提升构建速度 |
| **任务并行** | 并行执行独立任务，充分利用多核 CPU |
| **远程缓存** | 支持远程构建缓存，团队共享 |
| **简单易用** | 配置简单，开箱即用 |
| **生态完善** | 与 Next.js、NestJS 等框架集成良好 |

## 替代方案考虑

### 方案 1: Polyrepo（多仓库）

| 优势 | 劣势 |
|------|------|
| 权限控制更精细 | 代码共享困难 |
| 仓库体积小 | 依赖版本管理复杂 |
| 独立部署 | 跨模块修改困难 |
|  | 工具链配置重复 |

**不选择理由**: 项目初期模块间耦合度高，代码共享需求强烈，Polyrepo 会增加开发成本。

### 方案 2: Nx

| 优势 | 劣势 |
|------|------|
| 功能更强大 | 学习曲线陡峭 |
| 插件生态丰富 | 配置复杂 |
| 图形化界面 | 对于小型项目过于重型 |

**不选择理由**: Turborepo 更轻量，满足当前需求，Nx 对于当前项目过于复杂。

## 后果

### 正面后果

- 开发效率提升，代码共享方便
- 统一的代码规范和工具链
- 跨模块重构更容易
- 依赖版本统一管理

### 负面后果

- 仓库体积会逐渐增大
- 需要配置合理的代码组织方式
- 需要学习 Turborepo 的使用
- CI/CD 需要针对 Monorepo 优化

## 实现计划

1. 使用 `pnpm` 作为包管理器（已配置）
2. 使用 `turborepo` 作为构建工具（已配置）
3. 目录结构遵循：
   ```
   apps/          # 应用
     web/         # Web 应用
     admin/       # 管理后台
   packages/      # 共享包
     core/        # 核心业务逻辑
     ui/          # UI 组件库
     utils/       # 工具函数
     types/       # 类型定义
   services/      # 后端服务
     api/         # API 服务
   ```

## 相关决策

- ADR-0002: 采用 Next.js 作为前端框架
- ADR-0003: 采用 NestJS 作为后端框架

## 参考

- [Turborepo 官方文档](https://turbo.build/repo)
- [Monorepo vs Polyrepo](https://semaphoreci.com/blog/monorepo-vs-polyrepo)
- [pnpm workspaces](https://pnpm.io/workspaces)

---

> **变更记录**  
> 2026-05-25: 初始创建，状态设为已接受