ocdp v1

QUICK_START.md

@@ -0,0 +1,413 @@
+# OCDP 快速开始指南
+
+## 🚀 5分钟快速体验
+
+### 前置要求
+
+- Docker 20.10+
+- Docker Compose 2.0+
+- (可选) Make 工具
+
+### 第一步：克隆项目
+
+```bash
+git clone <repository-url>
+cd ocdp-go
+```
+
+### 第二步：选择运行模式
+
+#### 方式 1: 开发模式（推荐用于日常开发）
+
+**特点**：
+- ✅ 后端 Mock 模式（无需数据库）
+- ✅ 热重载（代码修改自动生效）
+- ✅ 快速启动
+- ✅ 适合快速迭代开发
+
+```bash
+# 使用 Make
+make docker-dev
+
+# 或直接使用 Docker Compose
+docker compose --profile dev up
+```
+
+**访问服务**：
+- 前端：http://localhost:5173
+- 后端：http://localhost:8080
+- API 文档：http://localhost:8080/api/v1
+
+**默认账号**：
+- 用户名：`admin`
+- 密码：`admin123`
+
+#### 方式 2: 生产模式（用于完整功能测试）
+
+**特点**：
+- ✅ 真实数据库
+- ✅ 完整功能
+- ✅ 生产环境配置
+
+```bash
+# 使用 Make
+make docker-prod
+
+# 或直接使用 Docker Compose
+docker compose up -d
+```
+
+**访问服务**：
+- 前端：http://localhost:3000
+- 后端：http://localhost:8080
+- 数据库：localhost:5432
+
+#### 方式 3: 独立测试单个服务
+
+**测试后端**：
+```bash
+make docker-test-backend
+# 访问：http://localhost:8080
+```
+
+**测试前端**：
+```bash
+make docker-test-frontend
+# 访问：http://localhost:3000
+```
+
+### 第三步：验证服务
+
+```bash
+# 检查后端健康状态
+curl http://localhost:8080/health
+
+# 登录获取 token
+curl -X POST http://localhost:8080/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"admin123"}'
+
+# 获取 registries 列表
+curl http://localhost:8080/api/v1/registries
+```
+
+### 第四步：开始开发
+
+#### 修改后端代码
+
+```bash
+# 编辑任意 Go 文件
+vim backend/cmd/api/main.go
+
+# Air 会自动检测变化并重新编译（开发模式）
+# 查看日志确认重载
+docker compose -f docker-compose.yml -f docker-compose.dev.yml logs -f backend
+```
+
+#### 修改前端代码
+
+```bash
+# 编辑任意 React 组件
+vim frontend/src/App.tsx
+
+# Vite HMR 会自动更新浏览器（开发模式）
+# 无需手动刷新页面
+```
+
+### 停止服务
+
+```bash
+# 停止并删除容器
+make docker-down
+
+# 或
+docker compose down
+
+# 完全清理（包括数据卷）
+docker compose down -v
+```
+
+---
+
+## 📚 常用命令速查
+
+### Docker 命令
+
+| 命令 | 说明 |
+|------|------|
+| `make docker-dev` | 启动开发环境 |
+| `make docker-prod` | 启动生产环境 |
+| `make docker-test-backend` | 测试后端 |
+| `make docker-test-frontend` | 测试前端 |
+| `make docker-logs` | 查看所有日志 |
+| `make docker-down` | 停止所有服务 |
+| `make docker-build` | 重新构建镜像 |
+
+### 查看日志
+
+```bash
+# 所有服务
+docker compose logs -f
+
+# 只看后端
+docker compose logs -f backend
+
+# 只看前端
+docker compose logs -f frontend
+
+# 只看最后 100 行
+docker compose logs --tail=100
+```
+
+### 进入容器
+
+```bash
+# 进入后端容器
+docker compose exec backend sh
+
+# 进入前端容器
+docker compose exec frontend sh
+
+# 进入数据库容器
+docker compose exec postgres psql -U postgres -d ocdp
+```
+
+### 重启服务
+
+```bash
+# 重启所有
+docker compose restart
+
+# 重启后端
+docker compose restart backend
+
+# 重启前端
+docker compose restart frontend
+```
+
+---
+
+## 🎯 使用场景指南
+
+### 场景 1: 我要开发新功能
+
+```bash
+# 1. 启动开发环境
+make docker-dev
+
+# 2. 修改代码（自动热重载）
+
+# 3. 查看日志
+make docker-logs
+
+# 4. 测试功能
+# 访问 http://localhost:5173
+
+# 5. 停止
+make docker-down
+```
+
+### 场景 2: 我要测试完整功能
+
+```bash
+# 1. 启动生产环境（包含数据库）
+make docker-prod
+
+# 2. 访问前端
+# http://localhost:3000
+
+# 3. 停止
+make docker-down
+```
+
+### 场景 3: 我只想测试后端 API
+
+```bash
+# 1. 启动后端 Mock
+make docker-test-backend-bg
+
+# 2. 测试 API
+curl http://localhost:8080/health
+curl http://localhost:8080/api/v1/registries
+
+# 3. 停止
+docker compose -f docker-compose.mock.yml down
+```
+
+### 场景 4: 我只想测试前端界面
+
+```bash
+# 1. 启动前端 Mock
+make docker-test-frontend-bg
+
+# 2. 访问前端
+# http://localhost:3000
+
+# 3. 停止
+docker compose -f docker-compose.mock.yml down
+```
+
+### 场景 5: 代码修改不生效
+
+```bash
+# 1. 停止所有服务
+make docker-down
+
+# 2. 重新构建镜像
+make docker-build --no-cache
+
+# 3. 重新启动
+make docker-dev
+```
+
+---
+
+## 🔍 常见问题
+
+### Q1: 端口被占用怎么办？
+
+**问题**：启动时报错 "port is already allocated"
+
+**解决方案**：
+```bash
+# 查看占用端口的进程
+sudo lsof -i :8080
+sudo lsof -i :5173
+sudo lsof -i :3000
+
+# 杀掉进程或修改 docker-compose.yml 中的端口映射
+```
+
+### Q2: 容器启动失败
+
+**查看详细错误**：
+```bash
+docker compose logs backend
+docker compose logs frontend
+```
+
+**常见原因**：
+- 端口冲突
+- 依赖服务未就绪
+- 配置错误
+
+**解决方案**：
+```bash
+# 清理并重新启动
+docker compose down -v
+docker compose build --no-cache
+docker compose up
+```
+
+### Q3: 热重载不工作
+
+**后端**：
+```bash
+# 确认 Air 是否运行
+docker compose logs backend | grep "air"
+
+# 检查文件挂载
+docker compose exec backend ls -la /app
+```
+
+**前端**：
+```bash
+# 确认 Vite 是否运行
+docker compose logs frontend | grep "VITE"
+
+# 重启前端
+docker compose restart frontend
+```
+
+### Q4: 数据库连接失败
+
+**检查**：
+```bash
+# 数据库是否运行
+docker compose ps postgres
+
+# 健康检查
+docker compose exec postgres pg_isready
+```
+
+**解决方案**：
+- 确保使用生产模式（`docker compose up`）
+- 等待数据库健康检查通过（约 10-20 秒）
+- 检查 `DATABASE_URL` 环境变量
+
+### Q5: 前端无法连接后端
+
+**检查**：
+```bash
+# 后端是否运行
+curl http://localhost:8080/health
+
+# 网络连接
+docker network inspect ocdp-network
+```
+
+**解决方案**：
+- 确认后端服务运行正常
+- 检查 `VITE_API_BASE_URL` 环境变量
+- 检查浏览器控制台错误
+
+---
+
+## 📖 进一步学习
+
+### 详细文档
+
+- [Docker 服务架构](./DOCKER_SERVICES.md) - 完整的服务说明
+- [开发指南](./docs/development/specification.md) - 开发规范
+- [API 文档](./backend/docs/openapi.yaml) - OpenAPI 规范
+- [部署指南](./docs/deployment/docker-guide.md) - 生产部署
+
+### 项目结构
+
+```
+ocdp-go/
+├── backend/          # Go 后端服务
+├── frontend/         # React 前端应用
+├── api/              # OpenAPI 规范
+├── docs/             # 项目文档
+├── docker-compose.yml           # 生产模式
+├── docker-compose.dev.yml       # 开发模式
+├── docker-compose.mock.yml      # Mock 模式
+└── Makefile          # 便捷命令
+```
+
+### 架构说明
+
+```
+┌─────────────┐     ┌─────────────┐
+│  Frontend   │────▶│   Backend   │
+│  (React)    │◀────│   (Go API)  │
+└─────────────┘     └─────────────┘
+                           │
+                           ▼
+                    ┌─────────────┐
+                    │  PostgreSQL │
+                    │   Database  │
+                    └─────────────┘
+```
+
+---
+
+## 🎉 开始使用
+
+现在你已经准备好开始使用 OCDP 了！
+
+**推荐的开发流程**：
+1. ✅ 使用 `make docker-dev` 启动开发环境
+2. ✅ 修改代码（自动热重载）
+3. ✅ 使用浏览器测试功能
+4. ✅ 使用 `make docker-test-backend` 测试后端 API
+5. ✅ 使用 `make docker-prod` 进行完整测试
+
+**需要帮助？**
+- 查看 [DOCKER_SERVICES.md](./DOCKER_SERVICES.md) 了解详细配置
+- 查看 [GitHub Issues](https://github.com/your-repo/issues) 报告问题
+- 查看项目文档获取更多信息
+
+Happy Coding! 🚀
+