Skip to content

01-dev.md

Latest commit

 

History

History
158 lines (119 loc) · 7.32 KB

01-dev.md

File metadata and controls

158 lines (119 loc) · 7.32 KB

MoveC 开发文档（内部）

本文件面向开发者，记录系统架构、模块职责、关键流程、构建运行与测试方法，以及近期重要改动。对外宣传请参考 html/index.html（对外网站，仅负责介绍与宣传）。

一、系统概览

  • 目标：安全、可回退地释放系统盘空间，提供目录迁移、重复文件清理、磁盘分析等能力。
  • 技术栈：Delphi VCL（Windows 原生）、本地 SQLite（见 MoveC.db 及升级脚本）、Win32/Win64 支持。
  • 安全性：防篡改/反调试、自修复（重启修复未完成交易）、HMAC/哈希校验（参见升级脚本与安全模块）。

目录结构（节选）：

  • 核心窗体与功能
    • uMain.pas 主界面（工具栏与菜单入口、状态输出、AboutMe 安全模块）。
    • uDirectoryMigration.pas 目录迁移模块（并行复制、占用进程处理、校验/删除、联接创建与审计、断点与回滚、重启自愈）。
    • uSmartDuplicateCleanup.pas 智能重复清理（扫描、明细报告、分组折叠、策略勾选、回收站删除、硬链接替换）。
    • uDiskAnalysis.pas 磁盘分析（聚合统计、Top100 大文件、导出 CSV、只读分析）。
    • uPostRebootRepair.pas 重启自修复（处理 pending_finalize/needs_junction 等事务）。
  • 安全与防护
    • uAntiDebug.pas、uAntiTamperPackage.pas、uSimpleSecureManager.pas、FrameAboutMe.*。
  • 数据库与脚本
    • MoveC.db 及 UpgradeDatabase_*.sql（数据库升级脚本）。
  • 网站（对外）
    • html/（index.html, styles.css, script.js）

二、模块职责与依赖

  • uMain.pas

    • 入口与总线：创建工具栏与菜单入口（重复清理/目录迁移/磁盘分析），风险横幅提示。
    • 集成 AboutMe 安全模块；初始化样式与 UI；输出状态日志。

  • uDirectoryMigration.pas

    • 并行复制：TParallel.For + MaxDegreeOfParallelism = TThread.ProcessorCount - 1，I/O 节流（每 64 文件 Sleep(1)）
    • 数据完整性：拷贝后做哈希/大小校验，校验通过再删除源文件。
    • 事务与状态：将不同阶段写入事务（INI/DB），支持断点续迁、回滚、重启后自修复。
    • 联接：CreateDirectoryJunction() 创建后调用 VerifyJunction() 审计；失败标记 needs_junction 并提示，重启后自愈。
    • 占用处理：集成 Restart Manager（frmLockingProcesses.pas/uRestartManager.pas）。

  • uSmartDuplicateCleanup.pas

    • 扫描：尺寸 → 头部哈希（如 64KB）→ 全量 SHA-256，减少误判与性能开销。
    • 明细报告：
      • 列表折叠为“组头 + 文件项”，组头双击折叠/展开；
      • 列排序、过滤（仅显示已勾选）、分组过滤；
      • 组级操作（本组留最新/全选/反选）、全局策略（每组保留最新/勾选30天前）；
      • 删除到回收站，校验“每组至少保留1个”；删除后刷新分组。

  • uDiskAnalysis.pas

    • 聚合统计：按根目录的顶层子目录聚合文件数量/总大小/最近写入时间；
    • Top100 大文件：按大小降序列出，双击用资源管理器选择；
    • 导出：当前页签导出为 CSV（UTF-8），Summary.csv/Top100.csv；
    • 仅分析不改写数据。

  • uPostRebootRepair.pas

    • 处理 pending_finalize（继续收尾）、needs_junction（补建联接并校验）等，确保事务最终一致。

三、关键流程

1) 目录迁移生命周期

  1. 扫描与勾选 → 迁移确认（风险提示）。
  2. 并行复制文件到目标（I/O 节流 + UI 节流），记录进度（TInterlocked）。
  3. 文件校验通过后删除源文件；失败项记录等待修复。
  4. 删除空目录；若源根已空：删除源根 → 创建联接（Junction）→ VerifyJunction() 审计：
    • 成功：事务标记完成。
    • 失败：事务标记 needs_junction，提示用户，重启后由 uPostRebootRepair 自愈。
  5. 若源未清空：标记 pending_finalize，重启后继续收尾。
  6. 回滚：如遇联接，先移除联接再创建真实目录并回拷；结束时可选择“清空目标目录（回收站）”。

2) 重复清理

  1. 扫描重复组（尺寸 → 头部哈希 → 全量哈希）。
  2. 明细报告（组头折叠/排序/过滤/策略/组级操作），勾选目标。
  3. 删除策略：
    • 同卷：硬链接替换（保留路径，可撤回）。
    • 跨卷：回收站删除（可撤回）。
  4. 规则校验：“每组至少保留 1 个”。

3) 磁盘分析（只读）

  1. 指定根目录；
  2. 填充“聚合统计”与“Top100 大文件”；
  3. 支持导出 CSV（UTF-8）。

四、构建与运行

  • 工程文件：C盘瘦身.dproj（主程序），其它工具工程如 ImportImages.dproj 等。
  • IDE：Delphi（建议 RAD Studio 10.x 或以上；若有具体版本要求，以团队环境为准）。
  • 依赖：
    • SQLite 动态库：sqlite3.dll（已在根目录）。
    • 运行需管理员权限的场景：创建 Junction、关闭占用进程、访问系统目录等。
  • 运行：
    • Debug/Release 配置：Release 下启用更严格的防篡改与反调试策略。
    • 建议以管理员身份运行可执行程序。

五、测试与验收（简表）

  • 目录迁移

    • 并行复制 + UI 更新流畅；
    • 校验后删除源文件；联接创建并通过审计；失败进入自愈；
    • 回滚可在存在联接/部分完成时完整恢复；
    • 占用进程需“全选”后自动关闭；
    • 边界：超长路径、权限不足、超大/海量小文件。

  • 重复清理

    • 扫描准确；
    • 明细报告交互（折叠/排序/过滤/策略/组级操作）可用；
    • 删除规则校验、回收站撤回、同卷硬链接替换。

  • 磁盘分析

    • 聚合统计与 Top100 正常填充；
    • 双击定位、CSV 导出可用；
    • 仅分析不写入。

六、最近重要改动（2025-10）

  • 目录迁移

    • 并行度自适应（CPU 线程数 - 1，最小 1）、I/O 节流（每 ~64 文件 Sleep(1)）。
    • 联接创建后 VerifyJunction() 审计，失败标记 needs_junction 并提示；重启自愈。

  • 重复清理

    • 明细报告增强：折叠/展开组头、分组过滤、列排序、仅显示勾选、组级操作、全局策略、统计显示；
    • 删除遵循“每组至少留 1 个”，并回收站删除/同卷硬链接替换。

  • 磁盘分析

    • 新增 uDiskAnalysis: 聚合统计 + Top100 大文件；导出 CSV；双击定位；只读分析。

  • 主界面与网站

    • 工具栏 & 菜单接入“磁盘分析”；
    • 网站新增“磁盘分析”亮点、增加“联接安全审计与回退校验”说明。

七、编码约定

  • UI 与工作线程分离：工作线程内不直接操作 VCL 控件，通过 TThread.Queue 节流更新。
  • 进度统计用 TInterlocked；
  • 关键路径异常要落盘（事务/日志）并给出中文友好提示；
  • 删除与迁移默认走“可撤回通道”（回收站/回滚）。

八、后续方向（内部规划）

  • 磁盘分析可视化（轻量图表）、类型/时间维度筛选与导出报告；
  • 清理规则（模式/白名单/年龄阈值）的只读预览 + 手动确认；
  • 自动化/计划任务：暂不实施，后续评审再定档。

如需补充或勘误，请在 PR 中更新本文件，并在提交信息中引用对应模块与变更点。