BackupTools（Windows 版）安装与使用说明
=======================================

作用：图形界面的备份与还原工具，把本机选定的文件/文件夹备份到 Gitee 仓库，
并在需要时增量还原。与 Unix 版完全独立：配置、备份内容、发布渠道互不影响。

一、运行环境
------------
1. 64 位 Windows。
2. 可访问 Gitee 的 HTTPS（TCP 443）。
3. 有效的 Gitee 私人令牌。
4. 不依赖系统 git（无需安装 Git for Windows），无需管理员权限与额外运行时。

二、获取与安装
--------------
从发布渠道下载可执行文件（二者内容相同）：

   <发布根>/windows/backup-tools-windows.exe           固定名，便于收藏/直链
   <发布根>/windows/backup-tools-windows-<版本>.exe    带版本号

同目录的 README.txt 即本文档。

1. 把 exe 放到固定目录（例如 D:\Tools\BackupTools\）。
2. 双击运行，直接进入图形界面，无需安装器。
3. 更新使用同目录 update-manifest.json 中的 sha256 校验；手动下载时可用
   发布目录中的 update-manifest.json 核对完整性。

命令行入口（可选）：

   backuptoolswin            启动图形界面
   backuptoolswin version    显示版本
   backuptoolswin help       显示帮助

三、首次设置
------------
在「设置」页填写以下内容，然后点「保存设置」：

1. Gitee 仓库地址：https://gitee.com/<用户>/<仓库>.git
2. 主机名：手动填写本机名称，写入备份快照，供还原时判断路径策略。
3. 私人令牌：保存到 Windows 凭据管理器（目标名 BackupTools/gitee-token），
   不写入配置文件、备份仓库或日志。
   「删除令牌」可清除已保存的令牌。
4. 更新地址：输入框默认显示当前生效的 update_base_url（发布根，不含项目名与
   平台，例如 https://example.com）；修改后点「保存设置」即写入本机配置，之后
   「检查更新」立即按新地址访问。留空或未以 http:// / https:// 开头时不会保存。

设置页还有「检查更新」与「跳过 TLS 证书校验（不安全，仅排障用）」。
本机配置位置：%APPDATA%\BackupTools\config.json

四、管理备份源
--------------
1. 「备份源」页「添加文件…」可多选文件；「添加文件夹…」选择一个文件夹。
   本 App 不提供任何预制源，源随时可增删改。
2. 每个源的「排除…」可逐行填写 glob（仅文件夹源支持，文件源按钮为禁用）：
   - 不含 /：匹配任意层级的同名项，如 *.tmp、cache；
   - 含 /（含前导 /）：相对源根锚定，如 logs/*.log、/build。
3. 「合并为组…」把若干未分组源合并为命名组，勾选组头默认勾选全部成员；
   组可重命名、解散，一个源至多属于一个组。
4. 添加重复源会被跳过并提示（文件源同路径唯一；文件夹源同路径且排除规则
   完全一致时唯一）。
5. 勾选状态只决定本次操作范围，不持久化；源列表与排除规则会持久化。

五、备份
--------
1. 在「备份源」页勾选本次要备份的条目（未勾选任何源时不会执行）。
2. 切到「备份」页，点「开始备份」，日志区实时显示进度。
3. 数据推送到 Gitee 仓库的 windows/<YYYYMMDDHHMMSS>/ 目录，不覆盖历史版本；
   该目录同时写入源列表快照（主机名、备份时间、程序版本、源与组）。

六、还原
--------
1. 切到「还原」页，点「载入 Gitee 快照」拉取版本列表。
2. 在「快照版本」下拉框选择版本（默认最新，可加载任意历史版本）。
3. 按快照中的源列表勾选要还原的条目，点「开始还原」。
4. 存在性判定以源路径的父级目录为准：
   - 父级目录存在（或源路径本身可创建）：增量还原，内容相同不重写，
     保留本机独有文件，被覆盖文件先备份到
     %LOCALAPPDATA%\BackupTools\restore-backup\<时间戳>\；
   - 父级目录不存在且快照主机名与本机一致：跳过，结束后展示跳过清单；
   - 父级目录不存在且主机名不一致：询问新的文件/目录位置，可取消跳过。

七、删除远端备份
----------------
1. 切到「删除」页（位于「检查」与「设置」之间），点「刷新版本」拉取远端版本列表。
2. 列表按时间倒序展示时间戳、主机名、备份时间和源数量；每行 checkbox 默认不勾选。
3. 勾选一个或多个要删除的版本，点「删除所选」，确认后执行。
4. 删除会重写仓库分支历史并强制推送：所选版本从全部历史提交中移除，其他电脑
   需重新克隆才能继续使用，且不可在程序内撤销。请谨慎操作。
5. 删除成功后列表自动刷新；删除全部版本后列表为空，可继续备份生成新版本。
6. 需要令牌具备仓库写权限；分支保护或网络问题导致强推失败时会明确报错。

八、检查
--------
「检查」页点「刷新版本」获取快照列表，选择版本后点「开始检查」。
检查只读，逐文件比对并输出未变/已改/缺失统计，不修改本机文件。

九、更新
--------
1. 「设置」页点「检查更新」：程序读取发布清单 update-manifest.json，比较版本；
   有新版本时在确认框中展示本版更新说明（notes），确认后下载并校验 sha256，
   随后程序退出，由内置 updater 就地替换 exe 并自动重启。
2. 更新地址取自本机配置的 update_base_url（首次运行自动写入默认值；可在「设置」
   页「更新地址」中修改并保存，保存后立即生效）；更新固定访问
   <update_base_url>/backup-tools/windows/。
3. 更新后程序目录中的可执行文件统一为 backup-tools-windows.exe；已无作用的
   旧版文件按发布清单自动清理，本机安装清单记录在
   %APPDATA%\BackupTools\installed-files.json。
4. 更新下载到程序同目录的 <exe>.new；替换失败会回滚，保持旧程序可用。
5. 自签/私有 CA 服务器导致证书校验失败时，可勾选「跳过 TLS 证书校验」，
   或在提示时选择本次跳过；跳过校验会失去防篡改能力，仅在排障时使用。
6. 更新不涉及配置文件；配置与仓库缓存在更新后继续沿用。

十、卸载
--------
1. 删除程序目录中的 backup-tools-windows.exe（以及本机安装清单
   %APPDATA%\BackupTools\installed-files.json）即完成卸载。
2. 如需清除本机数据，手动删除：
   - %APPDATA%\BackupTools\（配置）
   - %LOCALAPPDATA%\BackupTools\（仓库缓存与还原前备份）
   - Windows 凭据管理器中的 BackupTools/gitee-token
3. 卸载不会删除 Gitee 仓库中的任何备份数据。

十一、注意事项
--------------
1. 令牌只存于 Windows 凭据管理器；备份、还原、检查、删除期间界面会整体锁定，
   操作完成后自动恢复。
2. 操作进行中关闭窗口会提示，可选择停止当前操作后退出。
3. 还原为增量还原，不删除本机独有文件；Gitee 仓库默认保留全部历史版本，
   只有主动使用「删除」页才会重写分支历史移除所选版本。
4. <发布根> 指更新基地址下的项目目录，即 <update_base_url>/backup-tools；
   例如 update_base_url 为 https://example.com 时，发布根为
   https://example.com/backup-tools。
5. 每次备份、还原、检查或删除前，程序会先把本地仓库副本（位于
   %LOCALAPPDATA%\BackupTools\）完全同步到 Gitee 远端默认分支（通常为
   master），并清理未跟踪残留。若本地副本与远端不一致（例如另一台电脑
   执行过删除并重写历史），未推送的本地内容会被丢弃并在日志中告警；
   本机备份源文件不受影响，重新执行备份即可再次采集。