ocdp v1

backend/QUICK-REFERENCE.md

@@ -0,0 +1,133 @@
+# 快速参考卡片
+
+## 🚀 五个核心命令
+
+```bash
+make run-0     # Mock 模式（秒启动，无需 Docker）
+make run-1     # 开发模式（Docker 依赖 + 本地热加载）
+make run-2     # 生产模式（全部容器化）
+make clean-1   # 清理开发环境
+make clean-2   # 清理生产环境
+```
+
+---
+
+## 📋 模式对比
+
+| 特性 | run-0 | run-1 | run-2 |
+|------|-------|-------|-------|
+| **后端位置** | 本地 | 本地 | 容器 |
+| **数据库** | Mock | 容器 | 容器 |
+| **热加载** | ✅ | ✅ | ❌ |
+| **启动速度** | ⚡ 秒启 | 🔥 5秒 | 🐳 30秒 |
+| **适用场景** | 快速开发 | 日常开发 | 部署测试 |
+| **依赖 Docker** | ❌ | ✅ | ✅ |
+
+---
+
+## 🎯 使用场景
+
+### 场景 1: 快速功能开发
+```bash
+make run-0
+# 修改代码，自动重新编译
+# Ctrl+C 停止
+```
+
+### 场景 2: 日常开发（推荐）
+```bash
+make run-1
+# 修改代码，自动重新编译
+# Ctrl+C 停止后端（数据库继续运行）
+
+# 第二天继续
+make run-1  # 数据库还在，直接启动
+
+# 重置数据库
+make clean-1
+make run-1
+```
+
+### 场景 3: 部署前测试
+```bash
+make run-2
+# 查看日志
+docker compose --profile backend logs -f
+
+# 测试完成
+make clean-2
+```
+
+---
+
+## 🔧 Docker Compose 直接使用
+
+### 启动依赖（run-1 等价）
+```bash
+docker compose up -d postgres
+go run cmd/api/main.go
+```
+
+### 启动完整环境（run-2 等价）
+```bash
+docker compose --profile backend up -d
+```
+
+### 查看状态
+```bash
+docker compose ps                      # run-1
+docker compose --profile backend ps    # run-2
+```
+
+### 停止
+```bash
+docker compose down                    # run-1
+docker compose --profile backend down  # run-2
+```
+
+---
+
+## 📂 关键文件
+
+| 文件 | 说明 |
+|------|------|
+| `Makefile` | 5个核心命令 |
+| `docker-compose.yml` | 使用 profile 的统一配置 |
+| `.air.toml` | 热加载配置 |
+| `env.example` | 环境变量模板 |
+
+---
+
+## 🐳 Docker Compose Profile 原理
+
+```yaml
+# docker-compose.yml
+services:
+  postgres:
+    # 默认启动（无需 profile）
+    
+  backend:
+    profiles: [backend]  # 需要 --profile backend
+```
+
+**使用方式**:
+```bash
+docker compose up -d               # 只启动 postgres
+docker compose --profile backend up -d  # 启动 postgres + backend
+```
+
+---
+
+## 💡 快速提示
+
+- 首次使用运行: `go install github.com/cosmtrek/air@latest`
+- 查看帮助: `make` 或 `make help`
+- 完整文档: 查看 `DEVELOPMENT.md`
+- 审查报告: 查看 `REVIEW.md`
+
+---
+
+## 🎯 一句话总结
+
+**三种模式，五个命令，一个 Docker Compose 文件。**
+