# 👨‍💻 AutoClip Desktop 开发者指南

## 📋 目录

- [项目架构](#项目架构)
- [开发环境设置](#开发环境设置)
- [代码结构](#代码结构)
- [核心模块](#核心模块)
- [API接口](#api接口)
- [前端开发](#前端开发)
- [后端开发](#后端开发)
- [Tauri集成](#tauri集成)
- [构建和部署](#构建和部署)
- [测试](#测试)
- [贡献指南](#贡献指南)

## 🏗️ 项目架构

### 整体架构

```
AutoClip Desktop
├── Frontend (React + TypeScript + Ant Design)
├── Backend (Python + FastAPI + Celery)
├── Tauri (Rust + WebView)
└── Resources (FFmpeg + 模型文件)
```

### 技术栈

- **前端**: React 18, TypeScript, Ant Design, Vite
- **后端**: Python 3.9+, FastAPI, Celery, SQLAlchemy
- **桌面**: Tauri 2.0, Rust
- **数据库**: SQLite (桌面模式)
- **任务队列**: Celery with SQLite transport
- **AI服务**: OpenAI, DashScope, Google Gemini
- **语音识别**: Whisper, 云端API

## 🛠️ 开发环境设置

### 系统要求

- **Node.js**: 18.0+
- **Python**: 3.9+
- **Rust**: 1.70+
- **Git**: 2.0+

### 安装步骤

1. **克隆项目**
```bash
git clone https://github.com/your-org/autoclip-desktop.git
cd autoclip-desktop
```

2. **安装前端依赖**
```bash
cd frontend
npm install
```

3. **安装后端依赖**
```bash
cd ../backend
pip install -r requirements.txt
```

4. **安装Tauri依赖**
```bash
cd ../src-tauri
cargo install tauri-cli
```

5. **设置环境变量**
```bash
# 复制环境变量模板
cp .env.example .env

# 编辑环境变量
nano .env
```

### 开发环境配置

```bash
# 启动开发环境
npm run dev

# 启动后端服务
python backend/desktop_main.py

# 构建Tauri应用
npm run tauri build
```

## 📁 代码结构

### 前端结构

```
frontend/
├── src/
│   ├── components/          # 通用组件
│   │   ├── ErrorBoundary.tsx
│   │   ├── OfflineIndicator.tsx
│   │   └── ...
│   ├── pages/              # 页面组件
│   │   ├── HomePage.tsx
│   │   ├── SettingsPage.tsx
│   │   ├── OnboardingPage.tsx
│   │   └── ...
│   ├── hooks/              # 自定义Hooks
│   │   ├── useFirstRun.ts
│   │   ├── useDesktopConfig.ts
│   │   └── ...
│   ├── services/           # API服务
│   │   ├── api.ts
│   │   ├── projectApi.ts
│   │   └── ...
│   ├── store/              # 状态管理
│   │   ├── useProjectStore.ts
│   │   ├── useConfigStore.ts
│   │   └── ...
│   ├── utils/              # 工具函数
│   │   ├── apiUtils.ts
│   │   ├── errorHandler.ts
│   │   └── ...
│   └── types/              # 类型定义
│       ├── api.ts
│       ├── project.ts
│       └── ...
├── public/                 # 静态资源
└── package.json
```

### 后端结构

```
backend/
├── api/                    # API路由
│   └── v1/
│       ├── projects.py
│       ├── settings.py
│       ├── health.py
│       └── ...
├── core/                   # 核心模块
│   ├── desktop_config.py
│   ├── llm_providers.py
│   ├── speech_recognition.py
│   └── ...
├── services/               # 业务服务
│   ├── project_service.py
│   ├── video_service.py
│   ├── ai_service.py
│   └── ...
├── models/                 # 数据模型
│   ├── project.py
│   ├── clip.py
│   └── ...
├── utils/                  # 工具模块
│   ├── error_handler.py
│   ├── performance_config.py
│   ├── chunked_upload.py
│   └── ...
├── tasks/                  # Celery任务
│   ├── __init__.py
│   ├── video_tasks.py
│   └── ...
├── desktop_main.py         # 桌面应用入口
├── desktop_celery.py       # 桌面Celery配置
└── requirements.txt
```

### Tauri结构

```
src-tauri/
├── src/
│   ├── lib.rs              # 主入口
│   ├── commands.rs         # Tauri命令
│   ├── backend_manager.rs  # 后端管理
│   └── tray.rs             # 系统托盘
├── Cargo.toml              # Rust依赖
├── tauri.conf.json         # Tauri配置
└── resources/              # 资源文件
    └── ffmpeg/             # FFmpeg二进制
```

## 🔧 核心模块

### 1. 桌面配置管理

**文件**: `backend/core/desktop_config.py`

```python
class DesktopConfig:
    """桌面应用配置管理"""
    
    def __init__(self):
        self.data_dir = self._get_desktop_data_dir()
        self.config_file = self.data_dir / "config.json"
        self.settings_file = self.data_dir / "settings.json"
    
    def save_desktop_config(self, config: 'DesktopConfig') -> bool:
        """保存桌面配置"""
        try:
            config_dict = config.dict()
            # 递归转换Path对象为字符串
            config_dict = self._convert_paths_to_strings(config_dict)
            
            with open(self.config_file, 'w', encoding='utf-8') as f:
                json.dump(config_dict, f, ensure_ascii=False, indent=2)
            
            return True
        except Exception as e:
            logger.error(f"保存桌面配置失败: {e}")
            return False
```

### 2. 语音识别服务

**文件**: `backend/core/speech_recognition.py`

```python
class SpeechRecognizer:
    """语音识别服务"""
    
    def __init__(self, config: SpeechRecognitionConfig):
        self.config = config
        self.recognizer = self._create_recognizer()
    
    def transcribe_audio(self, audio_path: str) -> str:
        """转写音频文件"""
        if self.config.provider == "whisper_local":
            return self._transcribe_with_whisper(audio_path)
        elif self.config.provider == "openai":
            return self._transcribe_with_openai(audio_path)
        # ... 其他服务
```

### 3. 性能优化

**文件**: `backend/utils/performance_config.py`

```python
class PerformanceConfig:
    """性能配置管理"""
    
    def __init__(self, level: str = "medium"):
        self.level = level
        self.settings = self._get_settings_for_level(level)
    
    def _get_settings_for_level(self, level: str) -> PerformanceSettings:
        """根据级别获取性能设置"""
        levels = {
            "low": PerformanceSettings(
                max_concurrent_tasks=1,
                chunk_size_mb=5,
                upload_timeout_seconds=300
            ),
            "medium": PerformanceSettings(
                max_concurrent_tasks=2,
                chunk_size_mb=10,
                upload_timeout_seconds=600
            ),
            "high": PerformanceSettings(
                max_concurrent_tasks=4,
                chunk_size_mb=20,
                upload_timeout_seconds=1200
            )
        }
        return levels.get(level, levels["medium"])
```

## 🔌 API接口

### 项目管理API

```python
# 创建项目
@router.post("/projects", response_model=ProjectResponse)
async def create_project(project: ProjectCreate):
    """创建新项目"""
    return await project_service.create_project(project)

# 获取项目列表
@router.get("/projects", response_model=List[ProjectResponse])
async def get_projects():
    """获取项目列表"""
    return await project_service.get_projects()

# 获取项目详情
@router.get("/projects/{project_id}", response_model=ProjectDetailResponse)
async def get_project(project_id: int):
    """获取项目详情"""
    return await project_service.get_project(project_id)
```

### 设置管理API

```python
# 更新设置
@router.put("/settings", response_model=SettingsResponse)
async def update_settings(settings: DesktopSettings):
    """更新应用设置"""
    config = get_desktop_config()
    config.settings = settings
    save_desktop_config(config)
    return SettingsResponse(success=True)

# 测试API连接
@router.post("/settings/test-api", response_model=ApiTestResponse)
async def test_api_connection(request: TestApiRequest):
    """测试API连接"""
    provider = create_llm_provider(request.provider, request.api_key)
    success = provider.test_connection()
    return ApiTestResponse(success=success)
```

## 🎨 前端开发

### 状态管理

**文件**: `frontend/src/store/useProjectStore.ts`

```typescript
interface ProjectStore {
  projects: Project[]
  currentProject: Project | null
  loading: boolean
  error: string | null
  
  // Actions
  fetchProjects: () => Promise<void>
  createProject: (project: ProjectCreate) => Promise<void>
  updateProject: (id: number, updates: Partial<Project>) => Promise<void>
  deleteProject: (id: number) => Promise<void>
}

export const useProjectStore = create<ProjectStore>((set, get) => ({
  projects: [],
  currentProject: null,
  loading: false,
  error: null,
  
  fetchProjects: async () => {
    set({ loading: true, error: null })
    try {
      const projects = await projectApi.getProjects()
      set({ projects, loading: false })
    } catch (error) {
      set({ error: error.message, loading: false })
    }
  },
  
  // ... 其他actions
}))
```

### 自定义Hooks

**文件**: `frontend/src/hooks/useFirstRun.ts`

```typescript
export const useFirstRun = () => {
  const [isFirstRun, setIsFirstRun] = useState<boolean | null>(null)
  const [loading, setLoading] = useState(true)
  
  const checkFirstRun = async () => {
    try {
      const config = await configApi.getConfig()
      const hasApiKey = !!(config.settings?.llm?.api_key)
      setIsFirstRun(!hasApiKey)
    } catch (error) {
      console.error('检查首次运行状态失败:', error)
      setIsFirstRun(true)
    } finally {
      setLoading(false)
    }
  }
  
  useEffect(() => {
    checkFirstRun()
  }, [])
  
  return { isFirstRun, loading, refresh: checkFirstRun }
}
```

### 错误处理

**文件**: `frontend/src/utils/errorHandler.ts`

```typescript
class ErrorHandler {
  private static instance: ErrorHandler
  
  public static getInstance(): ErrorHandler {
    if (!ErrorHandler.instance) {
      ErrorHandler.instance = new ErrorHandler()
    }
    return ErrorHandler.instance
  }
  
  public handleError(error: any, category: ErrorCategory = 'SYSTEM', context?: string) {
    let errorMessage = '发生未知错误，请重试'
    let errorLevel: 'error' | 'warning' | 'info' = 'error'
    
    if (error.response) {
      // 处理HTTP错误
      errorMessage = error.response.data?.message || `服务器错误: ${error.response.status}`
      if (error.response.status === 429) {
        errorMessage = '系统正在处理其他项目，请稍后再试'
        errorLevel = 'warning'
      }
    } else if (error.request) {
      // 处理网络错误
      errorMessage = '网络连接失败，请检查网络或后端服务是否运行'
    } else if (error.message) {
      // 处理其他错误
      errorMessage = error.message
    }
    
    const finalMessage = context ? `[${context}] ${errorMessage}` : errorMessage
    console.error(`[${category} Error] ${finalMessage}`, error)
    
    if (errorLevel === 'warning') {
      message.warning(finalMessage)
    } else {
      message.error(finalMessage)
    }
  }
}
```

## 🐍 后端开发

### 服务管理

**文件**: `backend/desktop_main.py`

```python
class DesktopServiceManager:
    """桌面服务管理器"""
    
    def __init__(self, config: DesktopConfig):
        self.config = config
        self.is_running = False
        self.server_thread = None
        self.celery_worker_process = None
    
    def start(self):
        """启动所有服务"""
        if self.is_running:
            return
        
        try:
            # 启动FastAPI服务器
            self._start_fastapi_server()
            
            # 启动Celery Worker
            self._start_celery_worker()
            
            self.is_running = True
            self.start_time = time.time()
            logger.info("✅ 所有服务启动成功")
            
        except Exception as e:
            logger.error(f"❌ 服务启动失败: {e}")
            self.stop()
            raise
    
    def stop(self):
        """停止所有服务"""
        if not self.is_running:
            return
        
        try:
            # 停止Celery Worker进程
            if hasattr(self, 'celery_worker_process') and self.celery_worker_process:
                self.celery_worker_process.terminate()
                self.celery_worker_process.wait(timeout=5)
            
            # 停止FastAPI服务器
            if self.server_thread and self.server_thread.is_alive():
                self.server_thread.join(timeout=5)
            
            self.is_running = False
            logger.info("✅ 服务已停止")
            
        except Exception as e:
            logger.error(f"❌ 停止服务失败: {e}")
```

### 任务处理

**文件**: `backend/tasks/video_tasks.py`

```python
@celery_app.task(bind=True)
def process_video_task(self, project_id: int, video_path: str):
    """处理视频任务"""
    try:
        # 更新任务状态
        self.update_state(state='PROGRESS', meta={'status': '开始处理视频'})
        
        # 提取音频
        audio_path = extract_audio(video_path)
        self.update_state(state='PROGRESS', meta={'status': '音频提取完成'})
        
        # 语音识别
        transcript = transcribe_audio(audio_path)
        self.update_state(state='PROGRESS', meta={'status': '语音识别完成'})
        
        # 生成切片
        clips = generate_clips(transcript, video_path)
        self.update_state(state='PROGRESS', meta={'status': '切片生成完成'})
        
        # 保存结果
        save_project_results(project_id, clips)
        
        return {'status': '处理完成', 'clips_count': len(clips)}
        
    except Exception as e:
        logger.error(f"视频处理失败: {e}")
        raise self.retry(exc=e, countdown=60, max_retries=3)
```

### 错误处理

**文件**: `backend/utils/error_handler.py`

```python
class AutoClipsException(Exception):
    """AutoClip自定义异常"""
    
    def __init__(self, 
                 message: str, 
                 category: ErrorCategory = ErrorCategory.SYSTEM,
                 error_code: ErrorCode = ErrorCode.UNKNOWN_ERROR,
                 details: dict = None):
        self.message = message
        self.category = category
        self.error_code = error_code
        self.details = details or {}
        super().__init__(self.message)

def handle_autoclips_exception(exc: AutoClipsException, request_id: str = None) -> JSONResponse:
    """处理AutoClip异常"""
    status_code = 500
    if exc.category == ErrorCategory.VALIDATION:
        status_code = 422
    elif exc.category == ErrorCategory.CONFIGURATION:
        status_code = 400
    elif exc.category == ErrorCategory.NETWORK:
        status_code = 503
    
    return JSONResponse(
        status_code=status_code,
        content={
            "success": False,
            "error_code": exc.error_code.value,
            "message": exc.message,
            "details": exc.details,
            "request_id": request_id,
            "timestamp": time.time()
        }
    )
```

## 🦀 Tauri集成

### 命令定义

**文件**: `src-tauri/src/commands.rs`

```rust
#[tauri::command]
pub async fn start_backend_service(
    manager: State<'_, BackendManager>
) -> Result<BackendStatus, String> {
    match manager.start().await {
        Ok(_) => Ok(BackendStatus::Running),
        Err(e) => Err(format!("启动后端服务失败: {}", e)),
    }
}

#[tauri::command]
pub async fn stop_backend_service(
    manager: State<'_, BackendManager>
) -> Result<BackendStatus, String> {
    match manager.stop().await {
        Ok(_) => Ok(BackendStatus::Stopped),
        Err(e) => Err(format!("停止后端服务失败: {}", e)),
    }
}

#[tauri::command]
pub async fn get_service_status(
    manager: State<'_, BackendManager>
) -> Result<BackendStatus, String> {
    Ok(manager.get_status().await)
}
```

### 后端管理

**文件**: `src-tauri/src/backend_manager.rs`

```rust
pub struct BackendManager {
    status: BackendStatus,
    process: Option<Child>,
}

impl BackendManager {
    pub fn new() -> Self {
        Self {
            status: BackendStatus::Stopped,
            process: None,
        }
    }
    
    pub async fn start(&mut self) -> Result<(), String> {
        if self.status == BackendStatus::Running {
            return Ok(());
        }
        
        // 启动后端进程
        let mut cmd = Command::new("python")
            .arg("backend/desktop_main.py")
            .current_dir(std::env::current_dir().unwrap())
            .spawn()
            .map_err(|e| format!("启动后端进程失败: {}", e))?;
        
        self.process = Some(cmd);
        self.status = BackendStatus::Running;
        
        Ok(())
    }
    
    pub async fn stop(&mut self) -> Result<(), String> {
        if let Some(mut process) = self.process.take() {
            process.kill().map_err(|e| format!("停止后端进程失败: {}", e))?;
        }
        
        self.status = BackendStatus::Stopped;
        Ok(())
    }
}
```

### 系统托盘

**文件**: `src-tauri/src/tray.rs`

```rust
pub fn setup_system_tray(app_handle: &AppHandle) -> Result<(), Box<dyn std::error::Error>> {
    let tray_menu = MenuBuilder::new()
        .item(&MenuItem::new("显示主窗口", "show_main_window"))
        .separator()
        .item(&MenuItem::new("启动服务", "start_service"))
        .item(&MenuItem::new("停止服务", "stop_service"))
        .separator()
        .item(&MenuItem::new("退出", "quit_app"))
        .build()?;
    
    let _tray = TrayIconBuilder::new()
        .icon(app_handle.default_window_icon().unwrap().clone())
        .menu(&tray_menu)
        .on_menu_event(move |app, event| {
            match event.id.as_ref() {
                "show_main_window" => {
                    if let Some(window) = app.get_window("main") {
                        let _ = window.show();
                        let _ = window.set_focus();
                    }
                }
                "start_service" => {
                    // 启动服务逻辑
                }
                "stop_service" => {
                    // 停止服务逻辑
                }
                "quit_app" => {
                    app.exit(0);
                }
                _ => {}
            }
        })
        .build(app_handle)?;
    
    Ok(())
}
```

## 🏗️ 构建和部署

### 前端构建

```bash
# 开发环境
npm run dev

# 生产构建
npm run build

# 预览构建结果
npm run preview
```

### 后端构建

```bash
# 安装依赖
pip install -r requirements.txt

# 运行测试
pytest

# 代码检查
flake8 backend/
black backend/
```

### Tauri构建

```bash
# 开发模式
npm run tauri dev

# 生产构建
npm run tauri build

# 构建特定平台
npm run tauri build -- --target x86_64-apple-darwin  # macOS Intel
npm run tauri build -- --target aarch64-apple-darwin # macOS ARM
npm run tauri build -- --target x86_64-pc-windows-msvc # Windows
npm run tauri build -- --target x86_64-unknown-linux-gnu # Linux
```

### 跨平台构建

```bash
# 构建所有平台
npm run build:all

# 构建特定平台
npm run build:macos
npm run build:windows
npm run build:linux
```

## 🧪 测试

### 前端测试

```bash
# 运行测试
npm test

# 运行测试并生成覆盖率报告
npm run test:coverage

# 运行E2E测试
npm run test:e2e
```

### 后端测试

```bash
# 运行所有测试
pytest

# 运行特定测试
pytest tests/test_project_service.py

# 运行测试并生成覆盖率报告
pytest --cov=backend tests/

# 运行性能测试
pytest tests/performance/
```

### 集成测试

```bash
# 启动测试环境
docker-compose -f docker-compose.test.yml up -d

# 运行集成测试
pytest tests/integration/

# 清理测试环境
docker-compose -f docker-compose.test.yml down
```

## 🤝 贡献指南

### 开发流程

1. **Fork项目**
   ```bash
   git clone https://github.com/your-username/autoclip-desktop.git
   cd autoclip-desktop
   ```

2. **创建分支**
   ```bash
   git checkout -b feature/your-feature-name
   ```

3. **开发功能**
   - 编写代码
   - 添加测试
   - 更新文档

4. **提交代码**
   ```bash
   git add .
   git commit -m "feat: add your feature"
   git push origin feature/your-feature-name
   ```

5. **创建Pull Request**
   - 在GitHub上创建PR
   - 填写详细的描述
   - 等待代码审查

### 代码规范

#### 前端规范

- 使用TypeScript
- 遵循ESLint规则
- 使用Prettier格式化
- 组件使用函数式组件
- 使用Hooks进行状态管理

#### 后端规范

- 使用Python 3.9+
- 遵循PEP 8规范
- 使用类型注解
- 编写文档字符串
- 使用Pydantic进行数据验证

#### Rust规范

- 使用Rust 1.70+
- 遵循Clippy建议
- 使用rustfmt格式化
- 编写文档注释
- 使用Result处理错误

### 提交信息规范

```
<type>(<scope>): <subject>

<body>

<footer>
```

**类型**:
- `feat`: 新功能
- `fix`: 修复bug
- `docs`: 文档更新
- `style`: 代码格式
- `refactor`: 重构
- `test`: 测试
- `chore`: 构建/工具

**示例**:
```
feat(api): add project creation endpoint

Add new API endpoint for creating projects with validation
and error handling.

Closes #123
```

### 测试要求

- 新功能必须包含测试
- 测试覆盖率不低于80%
- 所有测试必须通过
- 包含单元测试和集成测试

### 文档要求

- 更新相关文档
- 添加API文档
- 更新用户指南
- 添加代码注释

## 📚 相关资源

- [Tauri官方文档](https://tauri.app/)
- [FastAPI文档](https://fastapi.tiangolo.com/)
- [React文档](https://react.dev/)
- [Ant Design文档](https://ant.design/)
- [Rust文档](https://doc.rust-lang.org/)

## 🆘 获取帮助

- **GitHub Issues**: 报告bug和功能请求
- **Discussions**: 技术讨论和问题解答
- **Discord**: 实时交流和协作
- **邮件**: 联系维护者

---

🎉 **感谢您的贡献！**