File-Structure-Sync

根据"指纹"同步文件结构。即使文件名已被修改，也能让备份盘自动跟随使用盘的目录结构。

🌟 项目简介

在管理海量数据（如视频、摄影素材、无损音乐）时，我们经常会遇到这样的痛点：备份盘 A 和 使用盘 B 存有完全相同的一批文件。我们在 使用盘 B 中进行了大量的人工整理：重命名、创建多级子文件夹、归类。由于文件名变了，传统的同步工具（如 rsync）无法识别它们是同一个文件，导致备份盘无法同步这种"结构化的整理成果"。

File-Structure-Sync 通过文件哈希（Hash）建立映射，即使文件名和路径完全不同，也能在备份盘中找回对应文件，并完美克隆你的目录结构。

✨ 核心特性

• ⚡ 采样哈希 (Fast Sample Hashing)：针对超大文件（GB级别）优化。通过读取文件头部、中部和尾部的特定块生成指纹，速度比全量计算快 100 倍以上。
• 📂 结构克隆：根据源盘的物理布局，自动在目标盘创建文件夹并移动文件。
• 🧹 自动清理：整理完成后，自动识别并删除目标盘中残留的空文件夹。
• 📝 映射透明化：生成人类可读的 json 映射表，方便在执行操作前进行人工核对。
• 🛠 无依赖：仅使用 Python 标准库，无需安装任何额外包即可运行。

📋 使用示例

前后对比

源盘 (已整理):

/Movies/Sci-Fi/Inception.mp4

目标盘 (未整理):

/Downloads/Inception_2010_Bluray_1080p.mp4

[运行 File-Structure-Sync 后]

目标盘 (已同步):

/Movies/Sci-Fi/Inception_2010_Bluray_1080p.mp4  <-- 自动归位并保持原画质

通过文件哈希识别，即使文件名完全不同，工具也能准确匹配并按照源盘的结构进行重组。

🚀 使用指南

1. 扫描源盘（生成映射表）

将脚本中的 SOURCE_DIR 指向你已经整理好的"使用盘"目录，运行扫描模式：

python run.py scan --src <源目录路径>

这将生成一个 file_map.json，记录了每个文件的哈希值及其对应的理想路径。

2. 同步目标盘（重组结构）

将 TARGET_DIR 指向你的"备份盘"目录，运行同步模式：

python run.py sync --dst <目标目录路径>

脚本将识别备份盘中的文件，并按照 JSON 里的结构进行重命名和移动。

3. 预览模式（Dry Run）

在执行实际同步前，可以先使用预览模式查看将要进行的操作：

python run.py sync --dst <目标目录路径> --dry-run

🪟 图形界面（PySide6）

安装依赖：

pip install PySide6

启动 GUI：

python gui.py

GUI 中可选择模式（scan/sync）、源目录/目标目录、映射文件路径，并在日志区查看执行输出。

🧰 Windows 打包（单文件 exe）

安装打包依赖：

pip install pyinstaller

运行打包脚本：

.\build.ps1

可选指定图标：

.\build.ps1 -IconPath .\assets\app.ico

输出文件位于 dist\File-Structure-Sync.exe。

🛠 技术细节：采样哈希

为了兼顾性能与唯一性，本项目默认采用以下算法计算指纹：

$$Hash = MD5(Header_{1MB} + Middle_{1MB} + Footer_{1MB} + FileSize)$$

这种方式可以有效区分即使是大小完全相同的不同视频文件（例如同一机位拍摄的不同素材）。

⚠️ 注意事项 (Disclaimer)

• 数据安全：虽然本工具仅涉及重命名和移动操作，但在对重要数据执行操作前，建议先在小样本数据上进行测试。
• 唯一性限制：如果你的文件夹内存在完全一模一样（哈希值一致）的重复文件，映射表将以扫描到的最后一个路径为准。

📄 开源协议

本项目采用 MIT License 许可。你可以自由地使用、修改和分发。

🧾 Release Notes

v1.0.0

• 新增 PySide6 图形界面，支持 scan/sync/dry-run 操作流程
• 提供 Windows 单文件 exe 打包脚本（PyInstaller）
• 保留并增强 CLI 使用方式，日志输出可复用