ocdp v1

frontend/README.md

@@ -0,0 +1,260 @@
+# 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