# Cloud Disk Sync - 专业级同步能力演进需求文档
## 1. 引言 (Introduction)
### 1.1 背景
当前 `cloud_disk_sync` 已具备基础的跨云盘/本地同步能力，拥有 CLI 界面和基本的进度显示。为了达到类似 FreeFileSync 的专业级同步体验，需要从核心算法、交互体验、性能表现三个维度进行深度迭代。
### 1.2 目标
构建一个**可视化、交互式、高性能**的云存储同步工具，支持复杂的同步策略和精细的文件差异管理，最终实现“所见即所得”的同步控制。
---
## 2. 核心功能需求 (Functional Requirements)
### 2.1 高级同步策略 (Sync Strategies)
目前的同步逻辑较为单一，需扩展为以下标准模式：
* **双向同步 (Two-Way)**: 自动检测两端变化，同步新增/修改，处理冲突（基于数据库记录上次同步状态）。
* **镜像同步 (Mirror)**: 严格使目标端成为源端的精确副本（删除目标端多余文件）。
* **增量备份 (Update)**: 仅将源端的新增/修改复制到目标端，不删除目标端文件。
* **自定义规则**: 允许用户为特定文件类型或路径配置独立的操作逻辑（如：`*.bak` 仅单向上传）。
### 2.2 可视化差异对比 (Visual Diff & Comparison)
这是 FreeFileSync 的核心体验，需要在 TUI (终端 UI) 或未来的 GUI 中实现：
* **左右分栏视图**: 左侧显示源文件，右侧显示目标文件。
* **差异高亮**:
* **图标标识**: 新增 (+), 删除 (-), 更新 (->), 冲突 (!)。
* **颜色区分**: 绿色(安全操作), 红色(删除/警告), 蓝色(移动/重命名)。
* **多维度对比**:
* **文件大小与时间**: 默认快速对比。
* **内容哈希 (Checksum)**: 精确对比（MD5/SHA256）。
* **二进制内容**: 逐字节对比（用于极其严格的场景）。
### 2.3 交互式操作 (Interactive Operations)
在执行同步前，提供“预检（Dry Run）”阶段，允许用户干预：
* **手动覆盖动作**: 用户可以点击特定文件，改变其同步方向（如：强制从右向左覆盖）。
* **排除/忽略**: 临时将某些文件标记为“本次不经同步”。
* **批量操作**: 选中多个文件进行统一标记。
### 2.4 历史版本与回收站 (Versioning & Trash)
* **版本控制**: 覆盖或删除文件时，不直接物理删除，而是移动到 `.versions/` 目录或重命名为 `file.v1.bak`。
* **防误删机制**: 提供“模拟删除”功能，先移动到回收站，确认无误后再清理。
---
## 3. 非功能需求 (Non-Functional Requirements)
### 3.1 性能优化 (Performance)
* **并行文件扫描**: 多线程递归扫描目录，提升百万级文件列表的加载速度。
* **并发传输**: 支持同时传输多个小文件（类似浏览器的并发请求），充分利用带宽。
* **流水线处理**: 扫描、对比、传输三个阶段解耦，实现流水线作业。
### 3.2 稳定性与容错 (Reliability)
* **原子性保障**: 文件写入使用 `write -> flush -> rename` 模式，防止断电导致文件损坏。
* **断点续传**: 对于大文件，支持分块传输和断点恢复（目前已有基础，需完善）。
* **网络重试**: 智能退避算法处理网络抖动。
---
## 4. UI/UX 演进路线 (UI Evolution)
### 阶段一：增强型 CLI (Current +)
* 优化进度条（已完成）。
* 输出详细的差异报告（JSON/Table）。
### 阶段二：交互式 TUI (Terminal UI)
使用 Rust 的 `ratatui` 库构建终端图形界面：
* **界面布局**:
```text
+------------------+---+------------------+
| Source: /local |Op | Target: /remote |
+------------------+---+------------------+
| file1.txt 10KB | ->| (missing) |
| (missing) |<- | file2.log 5KB |
| config.yml 2KB | !=| config.yml 1KB |
+------------------+---+------------------+
| [Sync Now] [Filter] [Settings] |
+------------------+---+------------------+
```
* **键盘操作**: 使用方向键导航，空格键切换操作动作。
### 阶段三：桌面 GUI (Desktop GUI)
使用 `Tauri` (Web技术栈) 或 `Iced` (Rust原生) 构建跨平台客户端：
* **拖拽支持**: 拖入文件夹建立任务。
* **图表分析**: 可视化展示文件夹大小分布、同步速度曲线。
---
## 5. 技术架构升级方案 (Technical Architecture)
### 5.1 核心层 (Core)
* **VFS (Virtual File System) 抽象**: 统一本地文件系统与 WebDAV/S3 等云存储的接口，支持 `metadata`, `read_chunk`, `write_chunk` 等原子操作。
* **Diff Engine**: 实现基于 Merkle Tree 的快速差异算法。
### 5.2 状态管理 (State Management)
* **SQLite 增强**: 记录每个文件的 `last_sync_timestamp`, `last_sync_hash`，用于实现真正的双向同步冲突检测。
### 5.3 插件化 (Plugin System)
* 支持通过 WASM 或动态库扩展新的存储后端（如 Google Drive, Dropbox）。
---
## 6. 实施计划 (Implementation Plan)
1. **M1 - 引擎重构**: 完善 VFS 抽象，实现双向同步核心算法。
2. **M2 - TUI 开发**: 基于 `ratatui` 实现交互式差异对比界面。
3. **M3 - 并发优化**: 引入 `tokio` 任务池，实现多文件并发传输。
4. **M4 - GUI 原型**: 启动 Tauri 项目，复用 Rust Core 逻辑。