ocdp v1

backend/DEVELOPMENT.md

@@ -0,0 +1,223 @@
+# 开发环境快速指南
+
+## 📋 前置要求
+
+- 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  # 清理生产环境
+```
+