# BowongTextVideoAgent 服务实现文档

## 概述

本文档描述了 BowongTextVideoAgent 服务在 Tauri 桌面应用中的完整实现。该实现遵循正确的 Tauri 架构模式：**Rust 后端处理 API 集成，TypeScript 前端通过 Tauri invoke 调用与后端通信**。

## 架构设计

### 正确的 Tauri 架构模式
```
Frontend (TypeScript/React) 
    ↓ (Tauri invoke calls)
Backend (Rust) 
    ↓ (HTTP requests)
External API (BowongTextVideoAgent)
```

### 四层架构实现

#### 1. 数据层 (Data Layer)
- **文件**: `apps/desktop/src-tauri/src/data/models/bowong_text_video_agent.rs`
- **内容**: 完整的数据模型定义 (300+ 行)
- **功能**: 
  - 所有 API 请求/响应结构体
  - 12 个主要模块的数据模型
  - Serde 序列化/反序列化支持

#### 2. 基础设施层 (Infrastructure Layer)
- **文件**: `apps/desktop/src-tauri/src/infrastructure/bowong_text_video_agent_service.rs`
- **内容**: HTTP 客户端服务实现 (600+ 行)
- **功能**:
  - 完整的 HTTP 客户端封装
  - 所有 12 个 API 模块的方法实现
  - 错误处理和重试机制
  - 任务轮询和状态管理

#### 3. 表示层 (Presentation Layer)
- **文件**: `apps/desktop/src-tauri/src/presentation/commands/bowong_text_video_agent_commands.rs`
- **内容**: Tauri 命令接口 (689+ 行)
- **功能**:
  - 45+ 个 Tauri 命令
  - 统一的命令命名规范 (`bowong_*`)
  - 完整的错误处理

#### 4. 前端服务层 (Frontend Service Layer)
- **文件**: `apps/desktop/src/services/bowongTextVideoAgentService.ts`
- **内容**: TypeScript 服务类 (750+ 行)
- **功能**:
  - 完整的前端 API 封装
  - Tauri invoke 调用集成
  - 类型安全的接口定义

## 主要功能模块

### 1. 提示词预处理模块
- 获取示例提示词
- 健康检查
- 提示词验证

### 2. 文件上传模块
- 通用文件上传
- S3 文件上传
- COS 文件上传
- 文件健康检查

### 3. 模板管理模块
- 获取模板列表
- 创建/更新/删除模板
- 任务类型检查
- 提示词检查

### 4. Midjourney 图像生成模块
- 同步图像生成
- 异步图像生成
- 任务状态查询
- 图像描述

### 5. 视频生成模块
- 异步视频生成
- 任务状态查询
- 批量状态查询

### 6. 任务管理模块
- 创建任务
- 查询任务状态
- 任务生命周期管理

### 7. 302AI 集成模块
- Midjourney 集成
- 极梦视频集成
- VEO 视频集成
- 任务取消和状态查询

### 8. 海螺语音模块
- 语音生成
- 语音列表获取
- 音频文件上传
- 语音克隆

### 9. 聚合接口模块
- 图像模型列表
- 视频模型列表
- 统一图像生成
- 统一视频生成

### 10. ComfyUI 集成模块
- 运行节点查询
- 任务提交
- 工作流执行
- 状态查询

### 11. Hedra 集成模块
- 文件上传
- 任务提交
- 状态查询

### 12. FFMPEG 处理模块
- 任务状态查询
- 媒体切片处理

## 技术特性

### Rust 后端特性
- **异步编程**: 使用 Tokio 进行异步 HTTP 请求
- **错误处理**: 使用 anyhow 和 thiserror 进行错误管理
- **序列化**: 使用 Serde 进行 JSON 序列化/反序列化
- **HTTP 客户端**: 使用 reqwest 进行 HTTP 通信
- **配置管理**: 灵活的配置系统
- **任务轮询**: 长时间运行任务的状态轮询机制

### TypeScript 前端特性
- **类型安全**: 完整的 TypeScript 类型定义
- **Tauri 集成**: 正确使用 Tauri invoke API
- **错误处理**: 统一的错误处理机制
- **重试机制**: 网络请求重试支持
- **缓存支持**: 可选的响应缓存

### 状态管理
- **AppState 集成**: 服务实例在应用状态中管理
- **线程安全**: 使用 Mutex 保证线程安全
- **生命周期管理**: 正确的服务初始化和清理

## 测试覆盖

### Rust 单元测试
- 服务创建和配置验证
- 数据模型序列化/反序列化
- 错误处理机制
- 任务轮询逻辑

### TypeScript 单元测试
- 服务初始化测试
- API 调用测试
- 错误处理测试
- 配置管理测试

### 集成测试
- 端到端架构验证
- 数据模型完整性测试
- 服务状态管理测试

## 使用示例

### 初始化服务
```rust
// Rust 后端
let config = BowongTextVideoAgentConfig {
    base_url: "https://api.bowong.com".to_string(),
    api_key: "your-api-key".to_string(),
    timeout: Some(30),
    retry_attempts: Some(3),
    enable_cache: Some(true),
    max_concurrency: Some(10),
};

state.initialize_bowong_service(config)?;
```

```typescript
// TypeScript 前端
const config = {
  baseUrl: 'https://api.bowong.com',
  apiKey: 'your-api-key',
  timeout: 30000,
  retryAttempts: 3,
  enableCache: true,
  maxConcurrency: 10
};

const service = new BowongTextVideoAgentService(config);
```

### 图像生成示例
```typescript
// 同步图像生成
const imageRequest = {
  prompt: 'A beautiful landscape',
  img_file: 'https://example.com/ref.jpg',
  max_wait_time: 120,
  poll_interval: 2
};

const result = await service.syncGenerateImage(imageRequest);
```

### 视频生成示例
```typescript
// 异步视频生成
const videoRequest = {
  prompt: 'A video of nature',
  img_url: 'https://example.com/ref.jpg',
  duration: 10,
  max_wait_time: 300,
  poll_interval: 5
};

const task = await service.asyncGenerateVideo(videoRequest);
const status = await service.queryVideoTaskStatus(task.task_id);
```

## 部署和配置

### 环境要求
- Rust 1.70+
- Node.js 18+
- Tauri 2.0+

### 配置文件
服务配置通过 `BowongTextVideoAgentConfig` 结构体管理，支持：
- API 基础 URL
- API 密钥
- 超时设置
- 重试次数
- 缓存启用
- 最大并发数

### 错误处理
- 网络错误自动重试
- 超时错误处理
- API 错误码映射
- 用户友好的错误消息

## 性能优化

### 并发控制
- 最大并发请求数限制
- 连接池管理
- 请求队列机制

### 缓存策略
- 可选的响应缓存
- 智能缓存失效
- 内存使用优化

### 资源管理
- 自动连接清理
- 内存泄漏防护
- 优雅的服务关闭

## 总结

BowongTextVideoAgent 服务的实现完全遵循了 Tauri 桌面应用的最佳实践：

1. **正确的架构模式**: Rust 后端处理业务逻辑，TypeScript 前端负责用户界面
2. **完整的功能覆盖**: 支持所有 12 个主要 API 模块，45+ 个具体功能
3. **类型安全**: 完整的类型定义和编译时检查
4. **错误处理**: 全面的错误处理和用户反馈机制
5. **测试覆盖**: 单元测试、集成测试和端到端测试
6. **性能优化**: 并发控制、缓存策略和资源管理

该实现为 Tauri 桌面应用提供了一个完整、可靠、高性能的 AI 服务集成解决方案。