Outlook Mail Deduplicator v1.0.26.04.09.09.45
https://drive.google.com/file/d/1KSnW80APDB8V9o_9SqRBrgL53LOpFtN6History:
Outlook Mail Deduplicator v1.0.26.04.09.09.06發布前最後一次修改，Claude 把一個 worker 意外覆蓋掉了，導致按下 [開始掃描] 沒作用
# Outlook Mail Deduplicator 使用手冊
## 一、系統概述
**Outlook Mail Deduplicator** 是一款安全、高效的 Microsoft Outlook 重複郵件檢測與處理工具。
### 核心功能
- **重複檢測**：基於 Message-ID、From、To、Subject、傳送時間等多維度識別重複郵件
- **安全驗證**：顯示重複郵件對比，使用者手動確認保留哪一封
- **智慧處理**：支援三種處理策略（保留最舊/最新/預覽）
- **衝突管理**：對於完全相同的郵件基於使用者選擇處理
---
## 二、系統架構
### 核心模組
#### 2.1 Outlook Profile 管理
- **enumerate_profiles()**：列舉當前系統中所有 Outlook Profile
- **ProfileLoaderThread**：後臺載入 Profile 對應的郵箱帳號
#### 2.2 郵件掃描引擎
- **FolderWalker**：遞迴遍歷所有郵件夾
- **DuplicateEngine**：多維度重複檢測（Message-ID、From、To、Subject、時間容忍）
- **ScanWorker**：後臺掃描執行緒，支援暫停/繼續/取消
#### 2.3 報告生成
- **report_writer.py**：生成 JSON 報告（記錄所有重複群組、衝突、處理結果）
- **CSV 報告**：可選的 Excel 相容格式報告
#### 2.4 衝突處理
- **ConflictDialog**：衝突處理主對話方塊
- **ConflictWorker**：衝突搬移後臺執行緒
- **增量更新**：暫停/取消/進度時自動儲存處理進度
## 三、使用指南
### 3.1 啟動應用
```bash
python main.py # 直接執行（開發模式）
Build.bat # 編譯打包（自動注入版本號）
```
### 3.2 主視窗操作流程
#### 步驟 1：選擇 Profile
1. 應用啟動後自動列舉所有 Outlook Profile
2. 在「Profile」下拉選單中選擇目標帳號
3. 點選「載入 Profile」按鈕開始載入
**狀態指示**：按鈕灰顯表示正在載入，完成後恢復
#### 步驟 2：選擇郵件夾
- 左側「資料夾樹」顯示所有郵件夾（按賬號/子夾 hierarchy 組織）
- 勾選要掃描的郵件夾（支援多選）
- **示例**：Inbox、Sent Items、Archive 等
#### 步驟 3：配置處理策略
**「處理策略」選項**
- **保留最舊**：在重複群組中保留髮送時間最早的郵件
- **保留最新**：保留髮送時間最晚的郵件
- **預覽（不處理）**：僅生成報告，不移動郵件
**「時間差容忍」選項**
- 範圍：0~1800 秒
- 作用：判定兩封郵件是否"同時傳送"（時差小於設定值視為相同）
- 預設：0 秒（精確比對）
#### 步驟 4：掃描郵件
- 點選「立即掃描」開始檢測
- 即時進度：視窗下方顯示已處理郵件數、估計時間
- **暫停/繼續**：點選「暫停」按鈕可暫停掃描，再點一次繼續
- **取消**：點選「取消」按鈕中止掃描
#### 步驟 5：檢視報告
- 掃描完成後自動開啟報告（同時儲存到 `reports/` 目錄）
- 報告內容：
- 重複群組列表
- 衝突群組列表（需手動處理）
- 處理結果摘要
#### 步驟 6：處理衝突（如有）
**何時觸發衝突**
- 多個郵箱/資料夾中存在完全相同的郵件（Message-ID、From、To 都相同）
- 自動處理策略無法判定保留哪一封
**處理衝突的方式**
1. 點選「衝突處理」按鈕
2. 選擇要處理的 JSON 報告檔案
3. 如果當前 Profile 與報告不匹配，系統會自動提示並載入正確的 Profile
4. 在「衝突處理」視窗中：
- **樹狀列表**顯示每個衝突群組及其郵件
- **選擇**要保留的郵件（勾選 radio button）
- **預設**：自動選擇最舊的郵件為保留物件
- **清除**：取消所有選擇
5. 點選「處理衝突」開始處理
- 保留的郵件原地不動
- 其他郵件移動到 `Duplicates_Conflict [時間戳]` 資料夾（保持原有資料夾結構）
6. **進度控制**
- **暫停**：暫停處理，已處理的郵件狀態儲存
- **取消**：中止處理，已儲存的狀態不回滾
---
## 四、處理預設規則
### 4.1 郵件對比維度
| 維度 | 優先順序 | 說明 |
|------|--------|------|
| Message-ID | 1 | 郵件伺服器分配的唯一標識 |
| From Email | 2 | 發件人郵箱地址 |
| To Email | 3 | 收件人郵箱地址 |
| Subject | 4 | 郵件主旨 |
| Sent Time | 5 | 傳送時間（在時間差容忍範圍內視為相同） |
### 4.2 群組分類
- **重複群組**：多個郵件具有相同的 Message-ID + From + To + Subject，在同一處理策略下自動判定
- **衝突群組**：無法自動判定（例如同時存在多個來源），需使用者手動選擇
### 4.3 處理結果記錄
每次處理後更新 JSON 報告中的 `action` 欄位：
```json
{
"entry_id": "...",
"action": "keeper" // 被保留的郵件
// 或
"action": "moved" // 成功移動到 Duplicates/Duplicates_Conflict
// 或
"action": "move_failed" // 移動失敗（記錄錯誤原因）
}
```
---
## 五、報告檔案
### 5.1 JSON 報告格式
位置：`reports/[時間戳]_dedupe_report.json`
```json
{
"run_id": "20260408_141601",
"profile": "dino9021@tbcs.net",
"strategy": "keep_oldest",
"time_tolerance_sec": 0,
"accounts": [
{
"store_id": "...",
"display_name": "Account Name",
"duplicate_groups": [...],
"conflicts": [...],
"summary": {
"groups_found": 100,
"mails_moved": 50,
"conflicts": 10
}
}
]
}
```
### 5.2 CSV 報告
位置：`reports/[時間戳]_dedupe_report.csv`
便於在 Excel 中檢視重複群組詳情
---
## 六、日誌檔案
### 6.1 主程式日誌
- **位置**：`reports/[時間戳]_outlook_dedupe.log`
- **內容**：掃描過程中的詳細日誌（所有模組輸出匯聚）
- **級別**：DEBUG、INFO、WARNING、ERROR
### 6.2 衝突處理日誌
- **位置**：`reports/[時間戳]_conflicts_session.log`
- **內容**：衝突處理過程中的即時操作日誌
---
## 七、故障排除
### Q：掃描速度很慢
**A**：這是正常的。系統需要逐一遍歷每封郵件。大型郵箱（10 萬+郵件）可能需要數分鐘。
### Q：超出最大 RPC 錯誤後無法繼續
**A**：Outlook COM Session 已中斷。掃描會自動停止。重新啟動應用後再次掃描即可。
### Q：衝突處理時報「The operation failed. An object cannot be found.」
**A**：原郵件已不存在（可能被手動刪除、被其他執行緒搬移等）。系統現在會自動視為處理成功。
### Q：能否跳過已處理的郵件
**A**：可以。再次點選「處理衝突」時，系統會檢查 `action` 欄位，自動跳過已成功處理的專案，只處理尚未處理或失敗的專案。
---
## 八、安全建議
- **備份重要郵件**：處理前建議先備份郵箱（Export to PST）
- **先預覽**：第一次使用建議選擇「預覽」策略檢視報告
- **從小範圍開始**：先在同一個郵件夾測試，確認行為正確後再擴大範圍
- **檢查日誌**：處理完成後檢視日誌，確認是否有異常或失敗
---
## 九、版本資訊
- **應用名**：Outlook Mail Deduplicator
- **版本號格式**：1.0.YY.MM.DD.HH.mm（編譯時自動注入）
- **依賴**：PySide6、pywin32、pythoncom（用於 Outlook COM 互動）
---
## 十、聯絡與反饋
如有問題或建議，請檢查日誌檔案以獲取診斷資訊。
by Dino9021
沒有留言:
張貼留言