# AutoClip 系统架构说明 ## 🏗️ 系统整体架构 AutoClip 是一个基于 Python + React 的视频自动切片和合集生成系统，采用前后端分离架构。 ### **架构组件** ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ 前端 (React) │ │ 后端 (FastAPI) │ │ 文件系统 │ │ │ │ │ │ │ │ - 项目管理 │◄──►│ - API 服务 │◄──►│ - 项目文件 │ │ - 视频预览 │ │ - 业务逻辑 │ │ - 输出文件 │ │ - 状态监控 │ │ - 数据处理 │ │ - 元数据 │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ ┌─────────────────┐ │ 数据库 (SQLite) │ │ │ │ - 项目信息 │ │ - 切片元数据 │ │ - 合集元数据 │ │ - 任务状态 │ └─────────────────┘ ``` ## 📁 数据存储架构 ### **1. 数据库层 (SQLite)** **核心表结构：** - `projects`: 项目基本信息 - `clips`: 切片元数据 - `collections`: 合集元数据 - `tasks`: 处理任务状态 - `bilibili_accounts`: B站账号信息 - `upload_records`: 文件上传记录 **数据关系：** ``` projects (1) ──► (N) clips projects (1) ──► (N) collections projects (1) ──► (N) tasks ``` ### **2. 文件系统层** **目录结构：** ``` data/ ├── projects/ # 项目原始文件 │ └── {project_id}/ # 每个项目一个目录 │ ├── raw/ # 原始视频文件 │ ├── step1_outline/ # 大纲生成结果 │ ├── step2_timeline/ # 时间轴分析 │ ├── step3_scoring/ # 内容评分 │ ├── step4_title/ # 标题生成 │ ├── step5_clustering/ # 内容聚类 │ └── step6_video/ # 视频生成 │ ├── clips_metadata.json # 切片元数据 │ └── collections_metadata.json # 合集元数据 ├── output/ # 最终输出文件 │ ├── clips/ # 切片视频文件 │ │ └── {project_id}/ # 按项目组织 │ ├── collections/ # 合集视频文件 │ │ └── {project_id}/ # 按项目组织 │ └── metadata/ # 全局元数据 ├── temp/ # 临时文件 ├── cache/ # 缓存文件 ├── uploads/ # 上传文件 └── backups/ # 数据库备份 ``` ## 🔄 数据流程 ### **1. 项目创建流程** ``` 用户上传视频 → 创建项目记录 → 存储原始文件 → 开始处理流程 ↓ 数据库: projects 表新增记录 文件系统: data/projects/{project_id}/raw/ 存储视频 ``` ### **2. 视频处理流程** ``` 原始视频 → 字幕提取 → 内容分析 → 切片生成 → 合集生成 → 最终输出 ↓ ↓ ↓ ↓ ↓ ↓ step1_outline → step2_timeline → step3_scoring → step4_title → step5_clustering → step6_video ``` ### **3. 数据同步流程** ``` 文件系统处理完成 → 元数据生成 → 同步到数据库 → 前端显示 ↓ ↓ ↓ ↓ clips_metadata.json → 解析元数据 → 写入clips表 → API返回 collections_metadata.json → 解析元数据 → 写入collections表 → API返回 ``` ## 🔧 关键技术实现 ### **1. 数据同步机制** - **自动同步**: 处理完成后自动同步元数据到数据库 - **手动同步**: 提供同步脚本处理历史数据 - **增量同步**: 只同步新增或修改的数据 ### **2. 路径管理** - **统一路径管理器**: `backend/core/unified_paths.py` - **动态路径检测**: 自动检测最佳输出路径 - **路径验证**: 定期检查路径配置一致性 ### **3. 状态管理** - **项目状态**: pending → processing → completed - **任务状态**: pending → running → completed/failed - **实时更新**: WebSocket + 轮询机制 ## 🚨 常见问题和解决方案 ### **1. 数据不一致问题** **现象**: 文件系统有数据，但数据库中没有 **原因**: 数据同步失败或未执行 **解决**: 运行 `scripts/sync_complete_metadata.py` ### **2. 路径混乱问题** **现象**: 文件分散在多个目录 **原因**: 硬编码路径与配置路径冲突 **解决**: 使用统一路径管理器 ### **3. 前端显示异常** **现象**: 后端API正常，前端显示异常 **原因**: 前端缓存或状态管理问题 **解决**: 清除浏览器缓存，重启前端服务 ## 📋 维护和监控 ### **1. 定期检查** - **数据一致性**: 检查文件系统与数据库的一致性 - **路径配置**: 验证路径配置的正确性 - **存储空间**: 监控磁盘空间使用情况 ### **2. 备份策略** - **数据库备份**: 定期备份 SQLite 数据库 - **文件备份**: 重要项目文件的备份 - **配置备份**: 系统配置文件的备份 ### **3. 日志监控** - **应用日志**: 监控应用运行状态 - **错误日志**: 及时发现问题 - **性能日志**: 监控系统性能 ## 🚀 最佳实践 ### **1. 数据管理** - 定期运行数据同步脚本 - 及时清理临时文件和缓存 - 保持文件系统结构清晰 ### **2. 开发流程** - 新功能开发前先清理测试数据 - 使用统一的路径配置 - 及时更新文档和注释 ### **3. 部署维护** - 生产环境定期备份数据 - 监控系统资源使用情况 - 及时更新依赖和修复安全漏洞