# Gitea集成方案设计

## 一、概述

本方案旨在将算法管理系统与Gitea代码仓库管理系统集成，实现通过算法管理页面直接操作Gitea仓库的功能，包括创建仓库、查看仓库、删除仓库等基本操作。

## 二、前端设计

### 2.1 界面修改

#### 2.1.1 算法管理页面

在现有的算法管理页面上添加以下元素：

1. **Gitea配置按钮**：在操作栏添加一个按钮，用于配置Gitea连接信息
2. **仓库操作按钮组**：在每个仓库的操作列中添加仓库操作按钮组，包括：
   - 编辑
   - 查看仓库（跳转到Gitea仓库页面）
   - 删除（同步删除系统数据和Gitea仓库）

#### 2.1.2 Gitea配置对话框

创建一个对话框用于配置Gitea连接信息：

- Gitea服务器URL
- 访问令牌
- 默认组织/用户
- 仓库前缀

#### 2.1.3 仓库操作对话框

为每个仓库操作创建相应的对话框：

- **添加仓库**：输入仓库名称、描述、类型、Git仓库名、分支等
- **编辑仓库**：修改仓库名称、描述、类型（Git仓库名、仓库地址、分支等字段为只读）

### 2.2 前端状态管理

添加Gitea相关的状态管理：

- Gitea配置信息
- 仓库列表
- 操作状态
- 错误信息

### 2.3 前端API调用

前端需要调用的后端API：

- `/api/v1/gitea/config`：获取和设置Gitea配置
- `/api/v1/gitea/repos/create`：创建仓库
- `/api/v1/gitea/repos/update`：更新仓库信息
- `/api/v1/repositories`：获取和管理仓库列表
- `/api/v1/repositories/{repo_id}`：获取、更新、删除单个仓库

## 三、后端设计

### 3.1 核心组件

#### 3.1.1 Gitea客户端

创建一个Gitea API客户端，封装与Gitea服务器的通信：

- 认证管理
- 仓库操作（创建、更新、删除）
- 错误处理

#### 3.1.2 仓库管理服务

实现仓库管理服务，处理与Gitea相关的业务逻辑：

- 仓库的CRUD操作
- 与算法管理的集成

#### 3.1.3 配置管理

管理Gitea连接配置：

- 配置的存储和读取
- 配置的验证
- 配置的加密（访问令牌）

### 3.2 数据库设计

#### 3.2.1 Gitea配置表

| 字段名 | 数据类型 | 描述 |
|-------|---------|------|
| id | UUID | 配置ID |
| server_url | String | Gitea服务器URL |
| access_token | String | 访问令牌（加密） |
| default_owner | String | 默认组织/用户 |
| repo_prefix | String | 仓库前缀 |
| created_at | Timestamp | 创建时间 |
| updated_at | Timestamp | 更新时间 |

#### 3.2.2 算法-仓库关联表

| 字段名 | 数据类型 | 描述 |
|-------|---------|------|
| id | UUID | 关联ID |
| algorithm_id | UUID | 算法ID |
| repo_id | String | Gitea仓库ID |
| repo_url | String | 仓库URL |
| branch | String | 默认分支 |
| created_at | Timestamp | 创建时间 |
| updated_at | Timestamp | 更新时间 |

### 3.3 API设计

#### 3.3.1 Gitea配置API

- **GET /api/gitea/config**
  - 功能：获取Gitea配置
  - 响应：Gitea配置信息

- **POST /api/gitea/config**
  - 功能：设置Gitea配置
  - 请求体：Gitea配置信息
  - 响应：操作结果

#### 3.3.2 仓库管理API

- **POST /api/gitea/repos/create**
  - 功能：创建仓库
  - 请求体：仓库信息（名称、描述、算法ID等）
  - 响应：创建结果

- **PATCH /api/gitea/repos/update**
  - 功能：更新仓库信息
  - 请求体：仓库信息（算法ID、描述等）
  - 响应：更新结果

#### 3.3.3 算法仓库管理API

- **GET /api/repositories**
  - 功能：获取算法仓库列表
  - 响应：仓库列表

- **GET /api/repositories/{repo_id}**
  - 功能：获取单个算法仓库详情
  - 响应：仓库详情

- **POST /api/repositories**
  - 功能：添加算法仓库
  - 请求体：仓库信息（名称、描述、类型、仓库URL、分支等）
  - 响应：添加结果

- **PUT /api/repositories/{repo_id}**
  - 功能：更新算法仓库信息
  - 请求体：仓库信息（名称、描述、类型等）
  - 响应：更新结果

- **DELETE /api/repositories/{repo_id}**
  - 功能：删除算法仓库
  - 响应：删除结果

## 四、实现流程

### 4.1 配置流程

1. 用户点击"Gitea配置"按钮
2. 在对话框中输入Gitea服务器URL、访问令牌、默认组织/用户和仓库前缀
3. 系统验证配置信息并保存

### 4.2 仓库添加流程

1. 用户点击"添加算法仓库"按钮
2. 在对话框中输入仓库名称、描述、仓库类型、Git仓库名和分支
3. 系统自动计算仓库URL
4. 用户可以选择本地存储路径
5. 系统调用Gitea API创建仓库
6. 系统将仓库信息保存到数据库

### 4.3 仓库编辑流程

1. 用户选择一个仓库，点击"编辑"按钮
2. 在对话框中修改仓库名称、描述和类型
3. 系统更新本地数据库中的仓库信息
4. 系统调用Gitea API更新远程仓库信息

### 4.4 仓库查看流程

1. 用户选择一个仓库，点击"查看仓库"按钮
2. 系统根据Gitea配置和仓库信息构建仓库URL
3. 系统在新窗口中打开Gitea仓库页面

### 4.5 仓库删除流程

1. 用户选择一个仓库，点击"删除"按钮
2. 系统弹出确认对话框
3. 用户确认删除
4. 系统调用Gitea API删除远程仓库
5. 系统删除本地数据库中的仓库信息

## 五、技术实现要点

### 5.1 前端实现

- **框架**：Vue 3 + TypeScript
- **构建工具**：Vite
- **状态管理**：Pinia
- **UI组件库**：Element Plus
- **HTTP客户端**：Axios
- **路由**：Vue Router
- **核心功能**：
  - Gitea配置管理
  - 算法仓库列表展示
  - 仓库添加、编辑、查看、删除操作
  - 本地路径选择功能

### 5.2 后端实现

- **框架**：FastAPI
- **数据库**：SQLite (或 PostgreSQL)
- **ORM**：SQLAlchemy
- **Gitea API**：直接调用Gitea REST API
- **核心功能**：
  - Gitea客户端封装
  - 仓库创建、更新、删除操作
  - 算法仓库管理
  - 错误处理和日志记录

### 5.3 安全考虑

- 访问令牌的加密存储
- API调用的权限控制
- 输入验证和错误处理
- 防止代码注入和恶意操作

### 5.4 性能考虑

- 异步处理Git操作
- 缓存仓库信息
- 分批处理大量数据
- 优化API响应时间

## 六、集成测试

### 6.1 测试场景

1. **Gitea配置测试**：测试配置的保存和验证
2. **仓库添加测试**：测试添加算法仓库并在Gitea上创建仓库
3. **仓库编辑测试**：测试更新算法仓库信息并同步到Gitea
4. **仓库查看测试**：测试打开Gitea仓库页面
5. **仓库删除测试**：测试删除算法仓库并同步删除Gitea仓库
6. **本地路径选择测试**：测试选择本地存储路径

### 6.2 测试环境

- **Gitea服务器**：本地或测试环境
- **算法管理系统**：本地开发环境
- **测试仓库**：在Gitea上创建的测试仓库

## 七、结论

本方案通过将算法管理系统与Gitea代码仓库管理系统集成，实现了算法仓库的可视化管理和操作，提高了算法开发和部署的效率。系统支持Gitea配置管理、算法仓库的添加、编辑、查看和删除操作，以及本地路径选择功能，为用户提供了便捷的算法仓库管理体验。

该方案具有以下优点：

1. **操作简便**：通过统一的界面管理算法仓库，无需切换工具
2. **功能完整**：支持基本的仓库操作，满足日常管理需求
3. **集成紧密**：与现有算法管理流程无缝集成
4. **可扩展性**：可以根据需要添加更多高级功能

通过实施本方案，算法管理系统将成为一个更加完整和强大的平台，为算法开发和部署提供更好的支持。