# 开发环境快速指南

## 📋 前置要求

- Go 1.21+
- Docker & Docker Compose
- Air（热加载工具）: `go install github.com/cosmtrek/air@latest`

## 🎯 设计理念

本项目使用 **Docker Compose Profile** 机制，通过单一的 `docker-compose.yml` 文件支持三种运行模式，避免配置文件重复。

## 🚀 三种运行模式

### 模式 0: Mock 模式（最快）

纯本地运行，无需任何外部依赖，所有服务都是 Mock。

```bash
make run-0
```

**特点:**
- ✅ 启动最快（秒启动）
- ✅ 无需 Docker
- ✅ 支持热加载
- ✅ 适合快速功能开发

**停止:** `Ctrl+C`

---

### 模式 1: 开发模式（推荐）

Docker 提供真实的 PostgreSQL，后端在本地运行并支持热加载。

```bash
make run-1
```

**特点:**
- ✅ 真实的数据库
- ✅ 支持热加载
- ✅ 代码修改实时生效
- ✅ 适合日常开发

**停止:** `Ctrl+C` 停止后端（数据库容器继续运行）

**清理:** `make clean-1` 清理数据库和临时文件

---

### 模式 2: 生产模式

所有服务完全容器化，模拟生产环境。

```bash
make run-2
```

**特点:**
- ✅ 完全容器化
- ✅ 接近生产环境
- ✅ 后台运行
- ❌ 无热加载

**查看日志:**
```bash
docker compose --profile backend logs -f
```

**停止:**
```bash
docker compose --profile backend down
```

**清理:** `make clean-2` 清理所有容器和构建产物

---

## 🧹 清理命令

```bash
# 清理模式 1 的产物（依赖容器 + 临时文件）
make clean-1

# 清理模式 2 的产物（所有容器 + 构建产物）
make clean-2
```

---

## 📊 常用工作流

### 日常开发

```bash
# 启动开发环境
make run-1

# ... 编码、测试 ...
# 代码修改会自动重新编译

# 下班停止（Ctrl+C）
# 第二天继续（依赖容器还在运行，直接启动）
make run-1
```

### 重置数据库

```bash
# 清理并重新开始
make clean-1
make run-1
```

### 测试生产部署

```bash
# 启动生产模式
make run-2

# 查看日志
docker compose -f docker-compose.prod.yml logs -f

# 测试完成后清理
make clean-2
```

---

## 🔧 环境变量配置

复制并修改环境变量配置：

```bash
cp env.example .env
```

主要配置项：

- `ADAPTER_MODE`: 设置为 `mock` 启用 Mock 模式（模式 0）
- `POSTGRES_*`: 数据库配置（模式 1、2）
- `JWT_SECRET`: JWT 密钥（生产环境必须修改）
- `ENCRYPTION_KEY`: 加密密钥（必须 32 字节）

---

## 📂 文件说明

| 文件 | 用途 |
|------|------|
| `Makefile` | 开发命令入口（5个核心命令） |
| `.air.toml` | 热加载配置 |
| `docker-compose.yml` | 统一配置文件（使用 profile 区分模式） |
| `Dockerfile` | 生产镜像构建配置 |
| `DEVELOPMENT.md` | 本文档 |

### Docker Compose Profile 说明

- **无 profile**: 只启动 postgres（用于模式 1）
- **--profile backend**: 启动 postgres + backend（用于模式 2）
- **--profile mock**: 启动 backend-mock（独立的 mock 模式容器）

---

## ❓ 常见问题

### Q: 模式 1 启动失败，提示端口被占用？

A: 检查是否有其他 PostgreSQL 实例在运行：
```bash
docker ps | grep postgres
# 或者修改 .env 中的 POSTGRES_PORT
```

### Q: 如何查看依赖服务状态？

A: 
```bash
docker compose ps                      # 模式 1（只有 postgres）
docker compose --profile backend ps    # 模式 2（postgres + backend）
```

### Q: 模式 1 和模式 2 的数据库数据会互相影响吗？

A: 会共享同一个数据库容器和数据卷 `ocdp-postgres-data`。
- 模式 1: 使用本地 air 连接到 postgres 容器
- 模式 2: 使用 backend 容器连接到 postgres 容器
- 数据是持久化的，切换模式不会丢失数据

### Q: 如何完全清理所有 Docker 资源？

A: 
```bash
make clean-1
make clean-2
docker system prune -a --volumes
```

---

## 💡 提示

- **首次使用**: 推荐从 `make run-0` 开始，快速验证环境
- **日常开发**: 使用 `make run-1`，享受热加载和真实数据库
- **部署前测试**: 使用 `make run-2`，确保容器化部署没问题
- **数据持久化**: 模式 1 和 2 的数据库数据都会持久化，`Ctrl+C` 不会丢失数据
- **完全重置**: 使用 `clean-*` 命令会删除数据卷，数据会丢失

---

## 🎯 快速参考

```bash
make          # 显示帮助
make run-0    # Mock 模式
make run-1    # 开发模式
make run-2    # 生产模式
make clean-1  # 清理开发环境
make clean-2  # 清理生产环境
```