OutlookMailArchive 项目说明

Outlook 邮件归档压缩 COM 加载项（经典 Outlook 桌面版）

1. 项目概述

本项目是一个面向经典 Outlook 桌面版的 COM 加载项，服务于从 Foxmail 迁移到 Outlook 的使用场景，解决迁移后的两大痛点：

1. 磁盘空间紧张：邮件数量几万封、附件体积大。通过附件原地压缩（图片/PDF/Office 文档）+ 按时间段切分 PST 归档，控制单文件体积、释放空间占用。
2. 搜索体验差：Outlook 内置搜索基于 Windows Search 索引，只支持前缀匹配，无法像 Foxmail 那样按编号片段模糊命中（例如输入 104058 找到标题含 ADR104058 的邮件）。本插件内置自研内存索引，提供毫秒级子串模糊搜索。

2. 功能总览

3. 技术架构

3.1 加载项形态

• COM 加载项（非 VSTO）：入口类 Connect 实现 IDTExtensibility2（生命周期）与 IRibbonExtensibility（Ribbon 定制），以 ProgId OutlookMailArchive.AddIn 注册。

• Ribbon XML：采用 Fluent UI customUI（2009/07 schema），以嵌入式资源 Resources/Ribbon.xml 分发，按钮图标 PNG 同为嵌入式资源，由 RibbonController 通过 getImage 回调动态提供。

• 注册方式：PowerShell 安装脚本写注册表（默认 HKCU 当前用户；管理员账号自动补写 HKLM 机器级），无安装器依赖。

3.2 技术栈

3.3 架构分层

Connect（COM 入口/生命周期）
  RibbonController          Ribbon 命令分发 + 图标
  AddInRuntime              基础设施：Application 引用、配置加载、目录、装配解析
  InboxWatcher              新邮件自动处理（NewMailEx 主 + ItemAdd 兜底双事件源）
  MailIndexService          模糊搜索元数据索引（单例，后台采集/持久化/增量更新）
 
 Views（WPF 视图层）
  ArchiveSettingsView       设置窗体
  ArchiveProgressView       批处理进度窗体
  FolderPickerView          文件夹树选择（含搜索文件夹分组）
  FolderCompressView        文件夹压缩进度窗体
  SmartSearchView           模糊搜索窗体
 
 Services（业务服务层）
  ArchiveSettings           配置模型（XmlSerializer 持久化 settings.xml）
  ArchiveBatchService       批处理编排：范围扫描  规则匹配  压缩  迁移
  ArchiveStoreService       规则 PST 定位/挂载/镜像文件夹结构 + 显示名管理
  MailCompressionService    单封邮件附件替换（保留内嵌图片 MAPI 属性）
  AttachmentCompressionService  纯字节压缩引擎（图片/PDF/Office 三类）
  FolderCompressService     文件夹原地压缩（含 Size 前后对比验证）
  SmartSearchService        搜索执行：内存索引命中或现场遍历回退

3.4 关键设计点

附件压缩正确性

• 内嵌正文图片的 PR_ATTACH_CONTENT_ID、PR_ATTACHMENT_HIDDEN、PR_ATTACH_MIME_TAG 等 MAPI 属性在替换附件后逐一恢复，避免正文图片显示失败。

• 压缩效果以 MailItem.Size 保存前后差值验证（真实落盘字节数），而非仅附件字节数。

• 压缩按阈值触发（图片/Office 默认 256KB、PDF 默认 512KB），避免小文件“越压越大”；结果不大于原件时放弃替换。

规则 PST 归档

• 按接收时间命中时间段规则 [开始日期, 结束日期]，迁入按模板命名的 PST（支持 {0} 开始年份、{1} 结束年份、{2}/{3} 起止日期占位符）。

• 源文件夹结构镜像保留到目标 PST（如 收件箱\客户A PST 内同名层级）。

• PST 需要时自动挂载（AddStoreEx + 轮询等待），挂载后把默认显示名（“Outlook 数据文件”）改为文件名，便于辨识；用户手动改过的名称不覆盖。

• 未命中任何规则的邮件留在原文件夹不动。

模糊搜索索引（三通道更新）

• 增量水位线按数据文件（Store）分组记录，避免新挂载旧 PST 被全局水位线跳过；扫描带 2 小时重叠窗口，EntryID 幂等覆盖去重。

• 索引条目仅存托管值（EntryID/StoreID/标题/发件人/收件人/时间/文件夹路径/修改时间），不持有 COM 对象。

• 命中未挂载 PST 的邮件时引导选择文件、AddStoreEx 挂载并校验 StoreID 后打开。

• 删除邮件产生的脏条目由“打开失败自动清理”兜底，另提供手动重建索引。

COM 资源纪律

• 所有 Interop 对象严格 Marshal.ReleaseComObject 释放，遍历 Stores/Folders 的代码统一 keep/release 模式，防止 Outlook 进程句柄泄漏。

4. 目录结构

OutlookMailArchive/
  src/OutlookMailArchive/        源码（SDK 风格 csproj）
     Connect.cs                 COM 入口
     RibbonController.cs        Ribbon 回调
     AddInRuntime.cs / AddInLog.cs   基础设施
     HandyControlRuntime.cs     WPF 主题宿主
     Automation/                冒烟测试 Automation 对象
     Services/                  业务服务（见 3.3）
     Views/                     WPF 视图 + WinForms 宿主
     Resources/                 Ribbon.xml + 图标
  scripts/                       构建/安装/卸载/诊断/冒烟 PowerShell 脚本
  runtime/office-com/            Extensibility/Office 互操作程序集
  dist/                          交付目录（files + scripts + 安装说明）
  docs/                          图标源文件与蓝图文档
  logs/                          本地开发日志

5. 构建与部署

1. 构建：scripts\build_addin.ps1（dotnet build -c Release，产物复制到 dist\files\）。
2. 安装：关闭 Outlook 后双击 dist\install_addin.bat（底层 install_addin.ps1，写 HKCU 注册；管理员账号补写 HKLM）。
3. 卸载：dist\uninstall_addin.bat。
4. 诊断：dist\diagnose_addin.bat 检查程序集、CodeBase、注册表与 .NET 运行时。
5. 验收：源码目录 scripts\test_outlook_smoke.ps1 冒烟脚本（通过 COMAddIn.Object Automation 入口验证），不随 dist 交付。

6. 运行时数据位置

7. 已知限制与注意事项

• PST/OST 数据文件大小在删除/压缩邮件后不会立即缩小，需在 Outlook 中执行“压缩数据文件”才回收磁盘空间。

• 单个 PST 建议控制在 20GB 左右（索引与访问性能最佳区间），上限 50GB；本插件按时间段切分 PST 的设计即为控制单文件体积。

• 模糊搜索索引不采集附件内容（只索引邮件元数据），Windows Search 若另行启用仍会索引正文，其索引位于 C 盘且与 PST 体积正相关——本插件的搜索不依赖 Windows Search。

• 新邮件自动处理始终只监听所选账号的收件箱；批处理与自动处理互不影响。