# OCDP Frontend

OCDP (Open Cloud Development Platform) Frontend - **Helm Chart 管理平台**

> 🎯 **专注于 Helm Charts**: 基于后端 OpenAPI 的前端应用，用于浏览、部署和管理 Helm Charts

---

## 🚀 快速开始

### 1. 安装依赖

```bash
npm install
```

### 2. 选择开发模式

本项目支持三种运行模式，通过 `Makefile` 命令启动：

#### **Mode 0** - Mock API，热重载（推荐快速开发）

```bash
make run-0
```

- ✅ 前端：`localhost:5173`（Vite 热重载）
- ✅ 后端：Mock/Stub 数据（不需要真实后端）
- ✅ 适用：快速 UI 开发和调试

#### **Mode 1** - Real API，热重载（集成测试）

```bash
make run-1
```

- ✅ 前端：`localhost:5173`（Vite 热重载）
- ✅ 后端：真实 API（`http://localhost:8080`）
- ⚠️ 需要后端服务运行

#### **Mode 2** - Docker Compose 部署（生产测试）

```bash
make run-2
```

- ✅ 前端：`localhost:3000`（Nginx + Docker 容器）
- ✅ 后端：容器化部署
- ✅ 适用：生产环境测试

### 3. 清理（Mode 2）

```bash
make clean-2
```

---

## 📋 命令列表

| 命令 | 说明 |
|------|------|
| `make run-0` | Mode 0 - Mock API，热重载前端 |
| `make run-1` | Mode 1 - Real API，热重载前端 |
| `make run-2` | Mode 2 - Docker Compose 部署 |
| `make clean-2` | 清理 Mode 2 容器 |

---

## 🔌 Backend OpenAPI 集成

### 架构

```
backend/docs/openapi.yaml
         ↓
   OpenAPI Generator
         ↓
  src/api/generated/  (自动生成的 API 客户端)
         ↓
  src/api/client.ts   (封装层，支持 Mode 切换)
         ↓
    React Components
```

### API 客户端使用

项目使用 OpenAPI Generator 生成的 TypeScript 客户端，根据运行模式自动切换：

- **Mode 0**: 使用 Mock 数据
- **Mode 1**: 调用真实后端 API（`localhost:8080`）
- **Mode 2**: Docker 环境，通过 Nginx 反向代理

### 使用示例

```typescript
import { api } from '@/api/client';

// 获取 Registries
const registries = await api.registries.list();

// 获取 Helm Chart 列表（自动过滤，只返回 Charts）
const charts = await api.artifacts.list('registry-id', 'repo-name');

// 获取 Chart 详情
const chart = await api.artifacts.get('registry-id', 'repo-name', 'version');

// 获取 Chart 的 values schema（用于部署配置）
const schema = await api.artifacts.getValuesSchema('registry-id', 'repo-name', 'version');

// 部署 Helm Chart
const instance = await api.instances.create({
  name: 'my-app',
  namespace: 'default',
  registry_id: 'registry-id',
  artifact_id: 'repo-name',
  version: '1.0.0',
  cluster_id: 'cluster-id'
});
```

### 重新生成 API Client

当后端 OpenAPI 规范更新时：

```bash
cd ..
make openapi-gen-frontend
```

---

## 🛠 技术栈

- **React 19** + **TypeScript** - UI 框架
- **Vite 7** - 构建工具和开发服务器
- **Tailwind CSS** - 样式框架
- **OpenAPI Generator** - API 客户端生成
- **Axios** - HTTP 客户端
- **React Router v7** - 路由管理

---

## 🎯 核心功能

- ✅ **Helm Chart 浏览**: 从 OCI Registry 浏览 Helm Charts（自动过滤）
- ✅ **Chart 部署**: 部署 Helm Chart 到 Kubernetes 集群
- ✅ **实例管理**: 管理已部署的 Helm Chart 实例
- ✅ **集群管理**: 管理 Kubernetes 集群连接
- ✅ **Registry 管理**: 管理 OCI Registry 配置
- ❌ **不支持**: 容器镜像管理（仅 Helm Charts）

---

## 📁 项目结构

```
frontend/
├── src/
│   ├── api/
│   │   ├── generated/        # 🤖 OpenAPI 自动生成的客户端
│   │   └── client.ts         # API 客户端封装（Mode 切换）
│   ├── features/             # 功能模块
│   │   ├── auth/             # 认证
│   │   ├── artifact/         # Helm Charts
│   │   ├── configuration/    # 配置管理
│   │   └── monitoring/       # 监控
│   ├── shared/               # 共享组件
│   ├── app/                  # 应用配置
│   └── main.tsx             # 入口文件
├── Makefile                 # 开发命令（三种模式）
├── package.json             # 依赖配置
├── vite.config.ts          # Vite 配置
├── docker-compose.dev.yml  # Docker Compose 配置
├── Dockerfile              # 生产构建
└── nginx.conf              # Nginx 配置
```

---

## 💡 开发工作流

### 日常开发（Mode 0）

```bash
make run-0
# 修改代码 → 自动热重载
```

### 集成测试（Mode 1）

```bash
# 1. 确保后端运行在 localhost:8080
cd ../backend
make run

# 2. 启动前端（Mode 1）
cd ../frontend
make run-1
```

### 生产测试（Mode 2）

```bash
make run-2
# 测试生产构建
# 完成后清理：
make clean-2
```

---

## 🐛 常见问题

### Mode 0 - 端口占用

```bash
lsof -ti:5173 | xargs kill -9
```

### Mode 1 - 后端连接失败

确保后端服务运行：

```bash
curl http://localhost:8080/health
```

### Mode 2 - 容器问题

```bash
# 查看日志
docker compose -f docker-compose.dev.yml logs -f

# 清理并重建
make clean-2
make run-2
```

### OpenAPI 客户端更新

```bash
# 在项目根目录执行
cd ..
make openapi-gen-frontend
```

---

## 📚 更多信息

- **后端项目**: `../backend`
- **OpenAPI 规范**: `../backend/docs/openapi.yaml`
- **查看所有命令**: `make help`

---

## 📄 License

MIT