v0.9.x 版本敏捷重構執行模式

重要: 整個 v0.9.x 版本系列遵循敏捷重構方法論，詳見：敏捷重構方法論

執行原則

• 主線程只負責任務分派，絕不親自執行程式碼修改
• 每個任務交給子代理人處理，完成後由重構代理人檢查
• 任務規模過大時向上回報，PM 代理人負責二次拆分
• 完成後由文件代理人更新工作日誌，標記小版本完成

Agent 分工

• 執行: lavender, sage, pepper, cinnamon, mint 等專業代理人
• 檢查: cinnamon-refactor-owl (重構代理人)
• 拆分: rosemary-project-manager (PM 代理人)
• 文件: memory-network-builder (文件代理人)

版本資訊

• 版本號: v0.9.0+1
• 開始時間: 2025-09-27
• 工作類型: 重大架構重構
• 預估週期: 完整中版本週期
• 優先級: 關鍵架構債務

重構目標

核心目標

基於設計文件 v2.0 規範，將過度設計的錯誤處理系統重構為原生 Exception + ErrorCodes 簡化架構，提升效能並降低維護成本。

具體成果指標

• 效能提升: 錯誤建立時間從 ~1ms 降至 < 0.1ms
• 記憶體優化: 錯誤物件記憶體占用從 ~1KB 降至 < 200 bytes
• 程式碼簡化: 移除 ~80% 的錯誤處理程式碼
• 維護性: 零學習成本，使用標準 Dart Exception

現況分析與問題評估

發現的架構問題

1. 雙重錯誤系統並存

1lib/core/error_handling/
2├── app_error.dart          # AppError 抽象基類定義
3└── unified_error_handler.dart  # 統一錯誤處理器
4
5lib/core/errors/
6├── app_error.dart          # AppError 具體實作
7├── standard_error.dart     # StandardError 包裝器
8├── error_adapters.dart     # 錯誤轉換器
9└── error_codes.dart        # 錯誤代碼

問題分析:

• 兩個目錄都包含 app_error.dart，責任不明確
• StandardError 作為 BusinessLogicError 的包裝器，增加不必要複雜度
• 導入路徑混亂，error_handling/app_error.dart 和 errors/app_error.dart 互相依賴

2. 過度設計問題

基於實際程式碼分析:

 1// StandardError.dart - 過度包裝
 2class StandardError extends BusinessLogicError {
 3  StandardError(String code, String message, [Map<String, dynamic>? context,])
 4    : super(
 5        code: code,
 6        message: message,
 7        businessRule: 'LEGACY_STANDARD_ERROR',  // 固定值，無實際意義
 8        context: context,
 9      );
10}

發現的過度設計:

• 複雜的錯誤分類系統（NetworkError, ValidationError, BusinessLogicError 等）
• StandardError 只是 BusinessLogicError 的薄包裝
• 深度複製和循環參照處理增加不必要開銷
• ErrorAdapters 提供多餘的轉換功能

3. 與設計文件 v2.0 不一致

設計文件 v2.0 規範:

注意：v2.0 重大架構更新: 基於 Linux/John Carmack 專家建議，完全放棄 StandardError 複雜設計，回歸原生錯誤處理 + ErrorCodes 簡化模式

實際實作狀況:

• 仍使用複雜的 AppError 分層系統
• StandardError 包裝器違反簡化原則
• UnifiedErrorHandler 功能過於複雜

新架構設計（基於設計文件 v2.0）

核心設計原則

專家驅動的簡化設計

過度工程化問題 (當前 v0.8.x):

• 複雜的錯誤分類系統解決不存在的問題
• 深度複製和循環參照處理增加不必要開銷
• ID 生成和時間戳記錄對實際業務無價值
• 學習成本高，維護困難

簡化設計優勢 (目標 v0.9.x):

1. 回歸原生: 使用 Dart Exception，零學習成本
2. 高效能: 錯誤建立時間 < 0.1ms，記憶體占用 < 200 bytes
3. 實用主義: 只解決真正存在的問題
4. 零依賴: 不引入不必要的複雜度

技術架構設計

1. 統一錯誤代碼系統

 1// lib/core/errors/error_codes.dart
 2enum ErrorCode {
 3  // 驗證錯誤
 4  validationFailed,
 5  invalidInput,
 6
 7  // 網路錯誤
 8  networkTimeout,
 9  noConnection,
10
11  // 業務邏輯錯誤
12  bookNotFound,
13  duplicateBook,
14
15  // 系統錯誤
16  storageError,
17  permissionDenied
18}

2. 原生 Exception 擴展

 1// lib/core/errors/exceptions.dart
 2
 3// 業務邏輯異常
 4class BookException implements Exception {
 5  final ErrorCode code;
 6  final String message;
 7
 8  const BookException(this.code, this.message);
 9
10  @override
11  String toString() => 'BookException: ${code.name} - $message';
12}
13
14// 驗證異常
15class ValidationException implements Exception {
16  final ErrorCode code;
17  final String message;
18  final String? field;
19
20  const ValidationException(this.code, this.message, [this.field]);
21
22  @override
23  String toString() => 'ValidationException: ${code.name} - $message${field != null ? ' (field: $field)' : ''}';
24}
25
26// 網路異常
27class NetworkException implements Exception {
28  final ErrorCode code;
29  final String message;
30
31  const NetworkException(this.code, this.message);
32
33  @override
34  String toString() => 'NetworkException: ${code.name} - $message';
35}

3. 統一錯誤處理器

 1// lib/core/errors/error_handler.dart
 2class ErrorHandler {
 3  static void handleError(Exception error) {
 4    switch (error.runtimeType) {
 5      case BookException:
 6        _handleBookError(error as BookException);
 7        break;
 8      case ValidationException:
 9        _handleValidationError(error as ValidationException);
10        break;
11      case NetworkException:
12        _handleNetworkError(error as NetworkException);
13        break;
14      default:
15        _handleGenericError(error);
16    }
17  }
18
19  static void _handleBookError(BookException error) {
20    // 簡單的書籍相關錯誤處理
21    print('書籍錯誤: ${error.message}');
22  }
23
24  static void _handleValidationError(ValidationException error) {
25    // 簡單的驗證錯誤處理
26    print('驗證錯誤: ${error.message}');
27  }
28
29  static void _handleNetworkError(NetworkException error) {
30    // 簡單的網路錯誤處理
31    print('網路錯誤: ${error.message}');
32  }
33
34  static void _handleGenericError(Exception error) {
35    // 通用錯誤處理
36    print('未知錯誤: ${error.toString()}');
37  }
38}

4. 統一導出入口

1// lib/core/errors/errors.dart
2export 'error_codes.dart';
3export 'exceptions.dart';
4export 'error_handler.dart';

使用範例

重構前（複雜）

 1// 重構前 - 複雜的錯誤處理
 2import 'package:book_overview_app/core/errors/standard_error.dart';
 3import 'package:book_overview_app/core/error_handling/unified_error_handler.dart';
 4
 5// 拋出錯誤
 6throw StandardError.validation('書籍標題不能為空');
 7
 8// 處理錯誤
 9try {
10  // 一些操作
11} catch (e) {
12  UnifiedErrorHandler().handleBusinessError(e);
13}

重構後（簡化）

 1// 重構後 - 簡化的錯誤處理
 2import 'package:book_overview_app/core/errors/errors.dart';
 3
 4// 拋出錯誤
 5throw ValidationException(ErrorCode.invalidInput, '書籍標題不能為空', 'title');
 6
 7// 處理錯誤
 8try {
 9  // 一些操作
10} catch (e) {
11  ErrorHandler.handleError(e);
12}

重構執行計畫

階段1：建立新架構（估時：1-2小時）

任務清單

• 建立 lib/core/errors/error_codes.dart

  • 定義完整的 ErrorCode 枚舉
  • 涵蓋所有現有錯誤場景

• 建立 lib/core/errors/exceptions.dart

  • 實作 BookException, ValidationException, NetworkException
  • 確保原生 Exception 相容性

• 建立 lib/core/errors/error_handler.dart

  • 實作簡化的統一錯誤處理邏輯
  • 提供基本的錯誤分類處理

• 建立 lib/core/errors/errors.dart

  • 統一導出所有錯誤相關類別
  • 成為唯一的錯誤處理導入入口

驗收標準

• 所有新檔案通過 dart analyze 檢查
• 基本功能測試通過
• 符合設計文件 v2.0 規範

階段2：移除舊架構（估時：1小時）

任務清單

• 刪除 lib/core/error_handling/ 整個目錄

  • 移除 app_error.dart (抽象基類版本)
  • 移除 unified_error_handler.dart

• 清理 lib/core/errors/ 過時檔案

  • 刪除 app_error.dart (具體實作版本)
  • 刪除 standard_error.dart
  • 刪除 error_adapters.dart
  • 保留並整合 error_codes.dart 有用內容

風險控制

• 分檔案逐一移除，每次移除後執行測試
• 確保沒有隱藏的依賴關係
• 建立移除前的備份點

階段3：全域重構（估時：2-3小時）

任務清單

• 掃描並識別所有使用位置

  • 使用 Serena MCP 工具找出所有 AppError/StandardError 引用
  • 建立完整的重構對照表

• 批次替換導入語句

  • 統一使用 import 'package:book_overview_app/core/errors/errors.dart';
  • 移除所有舊的錯誤處理導入

• 重構錯誤拋出邏輯

  • StandardError → 對應的具體 Exception
  • 業務邏輯錯誤 → BookException
  • 驗證錯誤 → ValidationException

• 更新錯誤處理邏輯

  • try-catch 區塊使用新的 Exception 類型
  • 錯誤處理使用 ErrorHandler.handleError()

重構優先序

1. 高風險檔案（核心業務邏輯）
2. 中風險檔案（次要功能模組）
3. 低風險檔案（測試檔案、工具檔案）

階段4：測試更新與驗證（估時：1-2小時）

任務清單

• 更新單元測試

  • 使用新的 Exception 類型進行測試
  • 確保測試覆蓋率不下降

• 更新整合測試

  • 端到端錯誤處理流程測試
  • 錯誤場景模擬測試

• 效能基準測試

  • 測量錯誤建立時間 < 0.1ms
  • 測量記憶體占用 < 200 bytes

• 100% 測試通過驗證

  • dart test 全部通過
  • flutter test 全部通過
  • dart analyze 無警告

階段5：文檔同步（估時：30分鐘）

任務清單

• 更新 CLAUDE.md 錯誤處理規範

  • 移除舊的 AppError/StandardError 範例
  • 新增原生 Exception 使用範例

• 確認設計文件一致性

  • 驗證實作完全符合設計文件 v2.0
  • 更新任何不一致的描述

預期效果與成功指標

效能提升目標

量化指標

• 錯誤建立時間: 從 ~1ms 降至 < 0.1ms（提升 10x）
• 記憶體使用: 從 ~1KB 降至 < 200 bytes（降低 80%）
• 程式碼量: 移除 ~80% 錯誤處理程式碼
• 編譯時間: 減少錯誤處理相關編譯時間

效能測試方法

 1// 效能基準測試
 2void main() {
 3  group('錯誤處理效能測試', () {
 4    test('錯誤建立時間測試', () {
 5      final stopwatch = Stopwatch()..start();
 6      for (int i = 0; i < 1000; i++) {
 7        final error = ValidationException(ErrorCode.invalidInput, '測試錯誤');
 8      }
 9      stopwatch.stop();
10
11      final averageTime = stopwatch.elapsedMicroseconds / 1000;
12      expect(averageTime, lessThan(100)); // < 0.1ms = 100 microseconds
13    });
14  });
15}

維護性提升

開發體驗改善

• 零學習成本: 使用標準 Dart Exception，無需學習自訂錯誤系統
• IDE 支援: 完整的自動完成和型別檢查
• 除錯友善: 標準 Exception 堆疊追蹤
• 測試簡化: 使用標準 Exception matching

程式碼品質提升

• 單一職責: 每個 Exception 類別只負責特定錯誤類型
• 清晰架構: 明確的錯誤處理流程
• 易於擴展: 新增錯誤類型只需擴展 ErrorCode 枚舉

驗證標準

功能驗證

• 所有現有錯誤場景正常運作
• 新的錯誤處理流程完整覆蓋
• 使用者體驗無變化（透明重構）

品質驗證

• 100% 測試通過率
• 0 個 dart analyze 警告
• 效能基準測試全部達標
• 程式碼覆蓋率不下降

架構驗證

• 完全符合設計文件 v2.0 規範
• 導入路徑完全語意化
• 無循環依賴問題

風險評估與應對策略

高風險項目

1. 大規模重構可能破壞現有功能

風險等級: 高 應對策略:

• 階段性重構，每階段獨立測試
• 建立重構前的完整測試基準
• 每個檔案重構後立即驗證

2. 測試覆蓋率可能下降

風險等級: 中 應對策略:

• 重構過程中同步更新測試
• 確保每個 Exception 類型都有對應測試
• 使用測試覆蓋率工具監控

3. 效能目標可能無法達成

風險等級: 中 應對策略:

• 建立效能基準測試
• 每階段都進行效能驗證
• 如無法達標則調整設計

應急計畫

重構失敗回滾策略

1. 階段回滾: 每階段完成後建立 Git 標籤
2. 檔案回滾: 每個檔案重構前建立備份
3. 完整回滾: 保留 v0.8.26 分支作為安全回滾點

問題處理優先級

1. P0 - 影響測試通過率: 立即修復
2. P1 - 影響核心功能: 當日修復
3. P2 - 影響次要功能: 階段內修復
4. P3 - 程式碼品質問題: 重構完成前修復

里程碑與時程規劃

重構時程表

關鍵檢查點

每日檢查點

• 測試通過率維持 100%
• 編譯無錯誤無警告
• 重構進度追蹤更新

階段檢查點

• 階段目標完全達成
• 無已知技術債務
• 下階段準備工作完成

任務分派準備

即將分派的任務類別

TDD 驅動任務

• 每個新 Exception 類別的測試優先開發
• 錯誤處理流程的完整測試覆蓋

重構執行任務

• 舊程式碼的批次替換和驗證
• 導入路徑的統一化重構

品質保證任務

• 效能基準測試的建立和執行
• 程式碼品質檢查和修復

文檔同步任務

• 技術文檔的更新和一致性檢查
• 使用範例和指引的更新

任務分派策略

並行任務規劃

• 新架構建立與測試撰寫可並行進行
• 不同模組的重構可獨立執行
• 文檔更新可與程式碼重構並行

依賴關係管理

• 新架構建立 → 舊架構移除 → 全域重構
• 每階段完成驗證 → 下階段開始
• 測試更新與程式碼重構同步進行

任務拆分清單 (44 個小版本)

階段0：準備文件建立 (v0.9.1 - v0.9.4) — 優先動作

v0.9.1 - 建立 API 規格文件

• 代理人: lavender-interface-designer
• 目標: 建立完整的錯誤處理系統 API 規格
• 檔案: docs/v0.9.0-error-handling-api-specification.md
• 參考文件: docs/app-error-handling-design.md (設計文件 v2.0)
• 內容: 完整介面定義、方法簽名、使用範例、效能要求
• 後續責任: 完成後需更新所有實作任務的參考文件欄位
• 時間: 2 小時

v0.9.2 - 建立 TDD 測試規格

• 代理人: sage-test-architect
• 目標: 建立新錯誤處理系統的完整測試規格
• 檔案: docs/v0.9.0-error-handling-test-specification.md
• 參考文件:
  • docs/v0.9.0-error-handling-api-specification.md (前置依賴)
  • docs/test-pyramid-design.md (測試架構)
• 內容: 測試案例、驗收標準、效能基準、整合測試場景
• 後續責任: 完成後需更新所有實作任務的測試規格參考
• 依賴: 必須在 v0.9.1 完成後執行
• 時間: 2 小時

v0.9.3 - 建立移轉指引

• 代理人: lavender-interface-designer
• 目標: 建立舊系統到新系統的移轉指引
• 檔案: docs/v0.9.0-error-handling-migration-guide.md
• 參考文件:
  • docs/v0.9.0-error-handling-api-specification.md (前置依賴)
  • 現有錯誤處理檔案 (lib/core/errors/, lib/core/error_handling/)
• 內容: 移轉對照表、使用場景範例、最佳實踐、問題排除
• 後續責任: 完成後需更新重構任務的移轉策略參考
• 依賴: 必須在 v0.9.1 完成後執行
• 時間: 2 小時

v0.9.4 - 建立實作範例與任務更新

• 代理人: pepper-test-implementer
• 目標: 建立實作範例並更新所有任務的參考文件資訊
• 檔案: docs/v0.9.0-error-handling-implementation-examples.md
• 參考文件:
  • docs/v0.9.0-error-handling-api-specification.md (前置依賴)
  • docs/v0.9.0-error-handling-test-specification.md (前置依賴)
  • docs/v0.9.0-error-handling-migration-guide.md (前置依賴)
• 內容: 程式碼範例、使用情境示範、常見模式、最佳實踐
• 後續責任:
  • 更新 v0.9.5-v0.9.44 所有任務的參考文件欄位
  • 補充 TDD 測試依賴資訊
  • 完成準備階段總結
• 依賴: 必須在 v0.9.1-v0.9.3 完成後執行
• 時間: 3 小時 (包含任務更新時間)

階段1：新架構建立 (v0.9.5 - v0.9.12)

v0.9.5 - 建立 ErrorCode 枚舉系統

• 代理人: lavender-interface-designer
• 目標: 設計完整的 ErrorCode 枚舉架構
• 檔案: lib/core/errors/error_codes.dart
• 參考文件:
  • docs/v0.9.0-error-handling-api-specification.md (API 規格)
  • docs/v0.9.0-error-handling-implementation-examples.md (實作範例)
• 測試依賴: docs/v0.9.0-error-handling-test-specification.md
• 前置任務: v0.9.1-v0.9.4 (準備文件完成)
• 時間: 1 小時

v0.9.6 - 實作 ErrorCode 枚舉定義

• 代理人: pepper-test-implementer
• 目標: 實作所有錯誤代碼枚舉值
• 檔案: lib/core/errors/error_codes.dart
• 參考文件:
  • docs/v0.9.0-error-handling-api-specification.md (API 規格)
  • docs/v0.9.0-error-handling-implementation-examples.md (實作範例)
• 測試依賴: docs/v0.9.0-error-handling-test-specification.md
• 前置任務: v0.9.5 (ErrorCode 枚舉系統設計)
• 時間: 1 小時

v0.9.7 - 設計原生 Exception 類別架構

• 代理人: lavender-interface-designer
• 目標: 設計 BookException, ValidationException, NetworkException
• 檔案: lib/core/errors/exceptions.dart
• 參考文件:
  • docs/v0.9.0-error-handling-api-specification.md (API 規格)
  • docs/v0.9.0-error-handling-implementation-examples.md (實作範例)
• 測試依賴: docs/v0.9.0-error-handling-test-specification.md
• 前置任務: v0.9.6 (ErrorCode 枚舉定義完成)
• 時間: 1.5 小時

v0.9.8 - 實作 BookException 類別

• 代理人: pepper-test-implementer
• 目標: 實作 BookException 和相關測試
• 檔案: lib/core/errors/exceptions.dart, 測試檔案
• 參考文件:
  • docs/v0.9.0-error-handling-api-specification.md (API 規格)
  • docs/v0.9.0-error-handling-implementation-examples.md (實作範例)
• 測試依賴: docs/v0.9.0-error-handling-test-specification.md
• 前置任務: v0.9.7 (Exception 類別架構設計)
• 時間: 2 小時

v0.9.9 - 實作 ValidationException 類別

• 代理人: pepper-test-implementer
• 目標: 實作 ValidationException 和相關測試
• 檔案: lib/core/errors/exceptions.dart, 測試檔案
• 參考文件:
  • docs/v0.9.0-error-handling-api-specification.md (API 規格)
  • docs/v0.9.0-error-handling-implementation-examples.md (實作範例)
• 測試依賴: docs/v0.9.0-error-handling-test-specification.md
• 前置任務: v0.9.8 (BookException 實作完成)
• 時間: 2 小時

v0.9.10 - 實作 NetworkException 類別

• 代理人: pepper-test-implementer
• 目標: 實作 NetworkException 和相關測試
• 檔案: lib/core/errors/exceptions.dart, 測試檔案
• 參考文件:
  • docs/v0.9.0-error-handling-api-specification.md (API 規格)
  • docs/v0.9.0-error-handling-implementation-examples.md (實作範例)
• 測試依賴: docs/v0.9.0-error-handling-test-specification.md
• 前置任務: v0.9.9 (ValidationException 實作完成)
• 時間: 2 小時

v0.9.11 - 設計統一錯誤處理器架構

• 代理人: lavender-interface-designer
• 目標: 設計 ErrorHandler 類別架構
• 檔案: lib/core/errors/error_handler.dart
• 參考文件:
  • docs/v0.9.0-error-handling-api-specification.md (API 規格)
  • docs/v0.9.0-error-handling-implementation-examples.md (實作範例)
• 測試依賴: docs/v0.9.0-error-handling-test-specification.md
• 前置任務: v0.9.10 (NetworkException 實作完成)
• 時間: 1 小時

v0.9.12 - 實作統一錯誤處理器

• 代理人: pepper-test-implementer
• 目標: 實作 ErrorHandler 和相關測試
• 檔案: lib/core/errors/error_handler.dart, 測試檔案
• 參考文件:
  • docs/v0.9.0-error-handling-api-specification.md (API 規格)
  • docs/v0.9.0-error-handling-implementation-examples.md (實作範例)
• 測試依賴: docs/v0.9.0-error-handling-test-specification.md
• 前置任務: v0.9.11 (ErrorHandler 架構設計)
• 時間: 2 小時

階段2：統一導出系統 (v0.9.13 - v0.9.14)

v0.9.13 - 建立統一導出檔案

• 代理人: mint-format-specialist
• 目標: 建立 errors.dart 統一導出入口
• 檔案: lib/core/errors/errors.dart
• 參考文件:
  • docs/v0.9.0-error-handling-api-specification.md (API 規格)
  • docs/v0.9.0-error-handling-implementation-examples.md (實作範例)
• 前置任務: v0.9.12 (ErrorHandler 實作完成)
• 時間: 30 分鐘

v0.9.14 - 新架構整合測試

• 代理人: sage-test-architect
• 目標: 建立新錯誤處理系統的整合測試
• 檔案: 整合測試檔案
• 參考文件:
  • docs/v0.9.0-error-handling-test-specification.md (測試規格)
  • docs/v0.9.0-error-handling-implementation-examples.md (實作範例)
• 前置任務: v0.9.13 (統一導出檔案完成)
• 時間: 2 小時

階段3：舊架構移除 (v0.9.15 - v0.9.18)

v0.9.15 - 分析舊檔案依賴關係

• 代理人: cinnamon-refactor-owl
• 目標: 分析所有舊錯誤處理檔案的使用情況
• 檔案: 分析報告
• 參考文件:
  • docs/v0.9.0-error-handling-migration-guide.md (移轉指引)
• 前置任務: v0.9.14 (新架構整合測試完成)
• 時間: 1 小時

v0.9.16 - 移除 unified_error_handler.dart

• 代理人: cinnamon-refactor-owl
• 目標: 安全移除統一錯誤處理器檔案
• 檔案: lib/core/error_handling/unified_error_handler.dart
• 參考文件:
  • docs/v0.9.0-error-handling-migration-guide.md (移轉指引)
• 前置任務: v0.9.15 (依賴關係分析完成)
• 時間: 1 小時

v0.9.17 - 移除 error_handling/app_error.dart

• 代理人: cinnamon-refactor-owl
• 目標: 移除錯誤處理目錄中的 AppError 定義
• 檔案: lib/core/error_handling/app_error.dart
• 參考文件:
  • docs/v0.9.0-error-handling-migration-guide.md (移轉指引)
• 前置任務: v0.9.16 (unified_error_handler.dart 移除)
• 時間: 1 小時

v0.9.18 - 移除其餘舊檔案並整合內容

• 代理人: cinnamon-refactor-owl
• 目標: 移除其餘舊檔案並整合有用內容到新系統
• 檔案: lib/core/errors/app_error.dart, standard_error.dart, error_adapters.dart
• 參考文件:
  • docs/v0.9.0-error-handling-migration-guide.md (移轉指引)
  • docs/v0.9.0-error-handling-api-specification.md (API 規格)
• 前置任務: v0.9.17 (error_handling 目錄清理)
• 時間: 2 小時

階段4：Domain 層重構 (v0.9.19 - v0.9.28)

v0.9.19 - 重構 Library Domain 錯誤處理

• 代理人: cinnamon-refactor-owl
• 目標: 更新 lib/domains/library/ 錯誤處理
• 檔案: library domain 相關檔案 (<=5個)
• 參考文件:
  • docs/v0.9.0-error-handling-migration-guide.md (移轉指引)
  • docs/v0.9.0-error-handling-implementation-examples.md (實作範例)
• 前置任務: v0.9.18 (舊檔案移除完成)
• 時間: 2 小時

v0.9.20 - 重構 Import Domain 錯誤處理

• 代理人: cinnamon-refactor-owl
• 目標: 更新 lib/domains/import/ 錯誤處理
• 檔案: import domain 相關檔案 (<=5個)
• 參考文件:
  • docs/v0.9.0-error-handling-migration-guide.md (移轉指引)
  • docs/v0.9.0-error-handling-implementation-examples.md (實作範例)
• 前置任務: v0.9.19 (Library Domain 重構完成)
• 時間: 2 小時

v0.9.21 - 重構 Scanner Domain 錯誤處理

• 代理人: cinnamon-refactor-owl
• 目標: 更新 lib/domains/scanner/ 錯誤處理
• 檔案: scanner domain 相關檔案 (<=5個)
• 參考文件:
  • docs/v0.9.0-error-handling-migration-guide.md (移轉指引)
  • docs/v0.9.0-error-handling-implementation-examples.md (實作範例)
• 前置任務: v0.9.20 (Import Domain 重構完成)
• 時間: 2 小時

v0.9.22 - 重構 Search Domain 錯誤處理

• 代理人: cinnamon-refactor-owl
• 目標: 更新 lib/domains/search/ 錯誤處理
• 檔案: search domain 相關檔案 (<=5個)
• 參考文件:
  • docs/v0.9.0-error-handling-migration-guide.md (移轉指引)
  • docs/v0.9.0-error-handling-implementation-examples.md (實作範例)
• 前置任務: v0.9.21 (Scanner Domain 重構完成)
• 時間: 2 小時

v0.9.23 - 重構 Enrichment Domain 錯誤處理

• 代理人: cinnamon-refactor-owl
• 目標: 更新 lib/domains/enrichment/ 錯誤處理
• 檔案: enrichment domain 相關檔案 (<=5個)
• 參考文件:
  • docs/v0.9.0-error-handling-migration-guide.md (移轉指引)
  • docs/v0.9.0-error-handling-implementation-examples.md (實作範例)
• 前置任務: v0.9.22 (Search Domain 重構完成)
• 時間: 2 小時

v0.9.24 - 重構 Version Management Domain 錯誤處理

• 代理人: cinnamon-refactor-owl
• 目標: 更新 lib/domains/version_management/ 錯誤處理
• 檔案: version management domain 相關檔案 (<=5個)
• 參考文件:
  • docs/v0.9.0-error-handling-migration-guide.md (移轉指引)
  • docs/v0.9.0-error-handling-implementation-examples.md (實作範例)
• 前置任務: v0.9.23 (Enrichment Domain 重構完成)
• 時間: 2 小時

v0.9.25 - 重構 System Domain 錯誤處理

• 代理人: cinnamon-refactor-owl
• 目標: 更新 lib/domains/system/ 錯誤處理
• 檔案: system domain 相關檔案 (<=5個)
• 參考文件:
  • docs/v0.9.0-error-handling-migration-guide.md (移轉指引)
  • docs/v0.9.0-error-handling-implementation-examples.md (實作範例)
• 前置任務: v0.9.24 (Version Management Domain 重構完成)
• 時間: 2 小時

v0.9.26 - 更新 Core 層其他模組錯誤處理

• 代理人: cinnamon-refactor-owl
• 目標: 更新 lib/core/ 其他模組錯誤處理
• 檔案: core 層相關檔案 (<=5個)
• 參考文件:
  • docs/v0.9.0-error-handling-migration-guide.md (移轉指引)
  • docs/v0.9.0-error-handling-implementation-examples.md (實作範例)
• 前置任務: v0.9.25 (System Domain 重構完成)
• 時間: 2 小時

v0.9.27 - 重構 Infrastructure 層錯誤處理

• 代理人: cinnamon-refactor-owl
• 目標: 更新 lib/infrastructure/ 錯誤處理
• 檔案: infrastructure 層相關檔案 (<=5個)
• 參考文件:
  • docs/v0.9.0-error-handling-migration-guide.md (移轉指引)
  • docs/v0.9.0-error-handling-implementation-examples.md (實作範例)
• 前置任務: v0.9.26 (Core 層重構完成)
• 時間: 2 小時

v0.9.28 - 重構 Presentation 層錯誤處理

• 代理人: cinnamon-refactor-owl
• 目標: 更新 lib/presentation/ 錯誤處理
• 檔案: presentation 層相關檔案 (<=5個)
• 參考文件:
  • docs/v0.9.0-error-handling-migration-guide.md (移轉指引)
  • docs/v0.9.0-error-handling-implementation-examples.md (實作範例)
• 前置任務: v0.9.27 (Infrastructure 層重構完成)
• 時間: 2 小時

階段5：測試系統更新 (v0.9.29 - v0.9.35)

v0.9.29 - 更新單元測試錯誤處理

• 代理人: sage-test-architect
• 目標: 更新所有單元測試的錯誤處理
• 檔案: test/unit/ 相關檔案 (<=5個)
• 參考文件:
  • docs/v0.9.0-error-handling-test-specification.md (測試規格)
  • docs/v0.9.0-error-handling-implementation-examples.md (實作範例)
• 前置任務: v0.9.28 (Presentation 層重構完成)
• 時間: 2 小時

v0.9.30 - 更新 Widget 測試錯誤處理

• 代理人: sage-test-architect
• 目標: 更新所有 Widget 測試的錯誤處理
• 檔案: test/widget/ 相關檔案 (<=5個)
• 參考文件:
  • docs/v0.9.0-error-handling-test-specification.md (測試規格)
  • docs/v0.9.0-error-handling-implementation-examples.md (實作範例)
• 前置任務: v0.9.29 (單元測試更新完成)
• 時間: 2 小時

v0.9.31 - 更新整合測試錯誤處理

• 代理人: sage-test-architect
• 目標: 更新所有整合測試的錯誤處理
• 檔案: test/integration/ 相關檔案 (<=5個)
• 參考文件:
  • docs/v0.9.0-error-handling-test-specification.md (測試規格)
  • docs/v0.9.0-error-handling-implementation-examples.md (實作範例)
• 前置任務: v0.9.30 (Widget 測試更新完成)
• 時間: 2 小時

v0.9.32 - 更新 Mock 物件錯誤處理

• 代理人: sage-test-architect
• 目標: 更新所有 Mock 物件的錯誤處理
• 檔案: test/mocks/ 相關檔案 (<=5個)
• 參考文件:
  • docs/v0.9.0-error-handling-test-specification.md (測試規格)
  • docs/v0.9.0-error-handling-implementation-examples.md (實作範例)
• 前置任務: v0.9.31 (整合測試更新完成)
• 時間: 2 小時

v0.9.33 - 建立新錯誤處理系統效能測試

• 代理人: sage-test-architect
• 目標: 建立效能基準測試
• 檔案: 新的效能測試檔案
• 參考文件:
  • docs/v0.9.0-error-handling-test-specification.md (測試規格)
  • docs/v0.9.0-error-handling-api-specification.md (效能要求)
• 前置任務: v0.9.32 (Mock 物件更新完成)
• 時間: 2 小時

v0.9.34 - 建立錯誤處理系統回歸測試

• 代理人: sage-test-architect
• 目標: 建立完整的回歸測試套件
• 檔案: 新的回歸測試檔案
• 參考文件:
  • docs/v0.9.0-error-handling-test-specification.md (測試規格)
  • docs/v0.9.0-error-handling-implementation-examples.md (測試範例)
• 前置任務: v0.9.33 (效能測試建立完成)
• 時間: 2 小時

v0.9.35 - 執行完整測試套件驗證

• 代理人: cinnamon-refactor-owl
• 目標: 確保 100% 測試通過率
• 檔案: 所有測試檔案
• 參考文件:
  • docs/v0.9.0-error-handling-test-specification.md (驗收標準)
• 前置任務: v0.9.34 (回歸測試建立完成)
• 時間: 1 小時

階段6：文檔同步與最終驗證 (v0.9.36 - v0.9.44)

v0.9.36 - 更新 CLAUDE.md 錯誤處理規範

• 代理人: memory-network-builder
• 目標: 更新專案錯誤處理指引
• 檔案: CLAUDE.md
• 參考文件:
  • docs/v0.9.0-error-handling-api-specification.md (API 規格)
  • docs/v0.9.0-error-handling-implementation-examples.md (使用範例)
• 前置任務: v0.9.35 (測試驗證完成)
• 時間: 1 小時

v0.9.37 - 驗證設計文件一致性

• 代理人: memory-network-builder
• 目標: 確認實作符合設計文件 v2.0
• 檔案: 設計文件對比分析
• 參考文件:
  • docs/app-error-handling-design.md (設計文件 v2.0)
  • docs/v0.9.0-error-handling-api-specification.md (API 規格)
• 前置任務: v0.9.36 (CLAUDE.md 更新完成)
• 時間: 1 小時

v0.9.38 - 執行效能基準測試

• 代理人: cinnamon-refactor-owl
• 目標: 驗證效能目標達成
• 檔案: 效能測試報告
• 參考文件:
  • docs/v0.9.0-error-handling-api-specification.md (效能要求)
  • docs/v0.9.0-error-handling-test-specification.md (效能測試)
• 前置任務: v0.9.37 (設計文件驗證完成)
• 時間: 1 小時

v0.9.39 - 執行最終品質檢查

• 代理人: cinnamon-refactor-owl
• 目標: 全面品質驗證
• 檔案: 品質檢查報告
• 參考文件:
  • docs/v0.9.0-error-handling-test-specification.md (品質標準)
  • docs/v0.9.0-error-handling-api-specification.md (API 規格)
• 前置任務: v0.9.38 (效能測試完成)
• 時間: 1 小時

v0.9.40 - 建立 CommonErrors 預編譯錯誤系統

• 代理人: pepper-test-implementer
• 目標: 實作 CommonErrors 預編譯錯誤系統
• 檔案: lib/core/errors/common_errors.dart, 測試檔案
• 參考文件:
  • docs/v0.9.0-error-handling-api-specification.md (API 規格)
  • docs/v0.9.0-error-handling-implementation-examples.md (實作範例)
• 前置任務: v0.9.39 (品質檢查完成)
• 時間: 2 小時

v0.9.41 - 效能優化與記憶體優化

• 代理人: cinnamon-refactor-owl
• 目標: 執行最終效能優化
• 檔案: 所有錯誤處理檔案
• 參考文件:
  • docs/v0.9.0-error-handling-api-specification.md (效能目標)
• 前置任務: v0.9.40 (CommonErrors 實作完成)
• 時間: 2 小時

v0.9.42 - 跨平台一致性驗證

• 代理人: cinnamon-refactor-owl
• 目標: 驗證與 Chrome Extension 錯誤格式一致性
• 檔案: 跨平台驗證報告
• 參考文件:
  • docs/v0.9.0-error-handling-api-specification.md (跨平台規格)
• 前置任務: v0.9.41 (效能優化完成)
• 時間: 1 小時

v0.9.43 - 完整系統整合測試

• 代理人: sage-test-architect
• 目標: 執行端到端整合測試
• 檔案: 整合測試執行報告
• 參考文件:
  • docs/v0.9.0-error-handling-test-specification.md (整合測試規格)
• 前置任務: v0.9.42 (跨平台驗證完成)
• 時間: 2 小時

v0.9.44 - 重構完成總結報告

• 代理人: memory-network-builder
• 目標: 建立重構完成總結報告
• 檔案: docs/v0.9.0-error-handling-refactor-completion-report.md
• 參考文件:
  • 所有 v0.9.0 錯誤處理文件
  • 工作日誌和任務執行記錄
• 前置任務: v0.9.43 (整合測試完成)
• 時間: 2 小時

任務統計

• 總任務數: 44 個小版本 (完整的錯誤處理系統重構)
• 預估總時間: 約 74-79 小時 (包含完整的準備、實作、驗證階段)
• 平均任務時間: 1.7 小時
• 最大任務時間: 3 小時 (v0.9.4 包含任務更新)
• 準備階段: v0.9.1-v0.9.4 (9 小時，包含文件建立和任務更新)
• 實作階段: v0.9.5-v0.9.44 (65-70 小時)

階段分佈

• 階段0 - 準備文件建立: v0.9.1-v0.9.4 (4 個任務, 9 小時)
• 階段1 - 新架構建立: v0.9.5-v0.9.12 (8 個任務, 12.5 小時)
• 階段2 - 統一導出系統: v0.9.13-v0.9.14 (2 個任務, 2.5 小時)
• 階段3 - 舊架構移除: v0.9.15-v0.9.18 (4 個任務, 5 小時)
• 階段4 - Domain 層重構: v0.9.19-v0.9.28 (10 個任務, 20 小時)
• 階段5 - 測試系統更新: v0.9.29-v0.9.35 (7 個任務, 13 小時)
• 階段6 - 文檔同步與驗證: v0.9.36-v0.9.44 (9 個任務, 12 小時)

重要改進 (v0.9.4 完成)

• 每個任務都有完整的參考文件 (API 規格、測試規格、移轉指引、實作範例)
• TDD 測試依賴關係明確 (所有實作任務都引用測試規格)
• 移轉策略詳細 (重構任務都有移轉指引支援)
• 依賴關係和執行順序清晰 (明確的前置任務要求)
• 參考文件資訊完整 (實作範例提供完整的程式碼指引)

工作日誌狀態

• 當前狀態: v0.9.4 完成 - 準備階段全部完成

  • v0.9.1: API 規格文件完成
  • v0.9.2: 測試規格文件完成
  • v0.9.3: 移轉指引文件完成
  • v0.9.4: 實作範例文件完成 + 所有任務資訊更新完成

• 下一步行動: 準備階段完成，實作階段準備就緒

  • 立即可執行: v0.9.5 - 建立 ErrorCode 枚舉系統
  • 所有實作任務都有完整參考資訊
  • TDD 測試驅動開發模式已建立

• 預計完成時間: v0.9.x 版本週期內完成 (約 10-12 週)

• 風險等級: 低風險 - 完整的準備文件和詳細計畫

工作日誌建立時間: 2025-09-27 18:30 預計更新頻率: 每階段完成後更新進度 責任人: Claude Code AI Assistant 審核狀態: 已建立，等待任務分派