ocdp-go/QUICK_START.md

# 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! 🚀