1// 功能模組A：字串錯誤 (Sample Code)
 2function moduleA_operation() {
 3  if (failed) throw 'OPERATION_FAILED'
 4}
 5
 6// 功能模組B：自定義錯誤類別 (Sample Code)
 7function moduleB_operation() {
 8  if (failed) throw new CustomError('MODULE_B_ERROR', details)
 9}
10
11// 功能模組C：原生錯誤 (Sample Code)
12function moduleC_operation() {
13  if (failed) throw new Error('Generic error message')
14}
15
16// 結果：三種不同的錯誤處理方式在同一系統中並存

1// 測試模組A (Sample Code)
2expect(() => moduleA()).toThrow('OPERATION_FAILED')
3
4// 測試模組B (Sample Code)
5expect(() => moduleB()).toThrow(CustomError)
6
7// 測試模組C (Sample Code)
8expect(() => moduleC()).toThrow(Error)

1// 跨系統傳輸時的序列化困境 (Sample Code)
2function serializeError(error) {
3  if (typeof error === 'string') return { type: 'string', value: error }
4  if (error instanceof CustomError) return error.toJSON()
5  if (error instanceof Error) return { message: error.message }
6  // 需要處理每種錯誤類型...
7}

1# 我們曾經嘗試的方法 (Sample Code)
2# 1. 逐個修復各 UC 的錯誤處理 → 不一致狀態持續存在
3# 2. 建立新的 ErrorCodes → 與舊系統並存造成更大混亂
4# 3. 強制統一標準 → 開發阻力大，容易半途而廢

 1// 統一錯誤處理橋接器 (Sample Code)
 2class ErrorSystemBridge {
 3  static TRANSITION_MODES = {
 4    LEGACY_COMPATIBLE: 'legacy_first',    // 向後相容優先
 5    MODERN_PREFERRED: 'modern_first',     // 新系統優先
 6    DUAL_VALIDATION: 'parallel_check',    // 雙系統驗證
 7    GRADUAL_MIGRATION: 'step_by_step'     // 逐步遷移
 8  }
 9
10  static handleError(error, mode = 'GRADUAL_MIGRATION') {
11    // 核心創新：同時支援舊新系統，確保零中斷遷移
12    const legacyFormat = this.toLegacyFormat(error)
13    const modernFormat = this.toModernFormat(error)
14
15    return this.selectByMode(legacyFormat, modernFormat, mode)
16  }
17}

 1// 模組特化適配器範例 (Sample Code)
 2class ModuleErrorAdapter {
 3  static ERROR_MAPPING = {
 4    // 精確映射：每個舊錯誤對應明確的新類型
 5    'OLD_VALIDATION_ERROR': {
 6      newType: 'VALIDATION_ERROR',
 7      severity: 'MODERATE',
 8      recovery: 'USER_INPUT_REQUIRED'
 9    },
10    'OLD_NETWORK_TIMEOUT': {
11      newType: 'TIMEOUT_ERROR',
12      severity: 'HIGH',
13      recovery: 'AUTOMATIC_RETRY'
14    }
15  }
16
17  static convertError(oldError) {
18    const mapping = this.ERROR_MAPPING[oldError.code]
19    if (!mapping) throw new Error('Unknown error type')
20
21    // <1ms 轉換目標，保證熱路徑效能
22    return new StandardError(mapping.newType, oldError.message, {
23      severity: mapping.severity,
24      recovery: mapping.recovery,
25      originalCode: oldError.code
26    })
27  }
28}

1// 效能基準測試結果 (Sample Code)
2const performanceMetrics = {
3  errorCreationSpeed: '2-10x faster',      // 錯誤建立速度
4  memoryUsage: '35-40% reduction',         // 記憶體使用減少
5  serializationTime: '<1ms per error',     // 序列化時間
6  crossPlatformConsistency: '100%'        // 跨平台一致性
7}

 1// src/core/migration/StandardErrorWrapper.js (Sample Code)
 2class StandardErrorWrapper {
 3  static MIGRATION_MODES = {
 4    LEGACY_ONLY: 'legacy_only',      // 只使用舊系統
 5    WRAPPER_MODE: 'wrapper_mode',    // 包裝器模式（預設）
 6    DUAL_MODE: 'dual_mode',          // 雙重系統並行
 7    ERRORCODES_ONLY: 'errorcodes_only' // 只使用新系統
 8  }
 9
10  // 向後相容的 StandardError 介面
11  constructor(code, message, details = {}) {
12    this.mode = config.migrationMode || 'wrapper_mode'
13
14    // 安全機制：保持舊介面不變
15    this.code = code
16    this.message = message
17    this.details = details
18
19    // 內部轉換：映射到新的 ErrorCodes 系統
20    this.errorCodesInstance = this._convertToErrorCodes(code, message, details)
21  }
22
23  _convertToErrorCodes(code, message, details) {
24    // 安全轉換邏輯，確保語意一致性
25    const mapping = ErrorMapping.getMapping(code)
26    return new ErrorCodes[mapping.newType](mapping.newCode, message, {
27      ...details,
28      migrationSource: 'StandardError',
29      originalCode: code
30    })
31  }
32
33  // 關鍵：完全保持舊 API 的行為
34  toString() { return this.errorCodesInstance.toString() }
35  toJSON() { return this.errorCodesInstance.toJSON() }
36}

 1// src/core/migration/DualErrorSystemBridge.js (Sample Code)
 2class DualErrorSystemBridge {
 3  static DUAL_SYSTEM_MODES = {
 4    LEGACY_FIRST: 'legacy_first',         // 優先使用 StandardError
 5    ERRORCODES_FIRST: 'errorcodes_first', // 優先使用 ErrorCodes
 6    PARALLEL: 'parallel',                 // 平行處理兩套系統
 7    TRANSITIONAL: 'transitional'          // 過渡模式
 8  }
 9
10  constructor(options = {}) {
11    this.mode = options.mode || 'PARALLEL'
12    this.compatibilityLevel = options.compatibility || 'STRICT'
13    this.performanceMonitor = new PerformanceMonitor()
14  }
15
16  // 雙向轉換核心：確保資料完整性
17  async handleError(error, context = {}) {
18    const startTime = performance.now()
19
20    try {
21      // 安全檢查：驗證輸入錯誤的有效性
22      this._validateErrorInput(error)
23
24      let result
25      switch (this.mode) {
26        case 'PARALLEL':
27          // 平行處理：同時使用兩套系統，確保一致性
28          result = await this._handleParallelMode(error, context)
29          break
30        case 'LEGACY_FIRST':
31          result = await this._handleLegacyFirst(error, context)
32          break
33        case 'ERRORCODES_FIRST':
34          result = await this._handleErrorCodesFirst(error, context)
35          break
36        default:
37          result = await this._handleTransitionalMode(error, context)
38      }
39
40      //  關鍵：雙向驗證確保轉換精度
41      if (this.compatibilityLevel === 'STRICT') {
42        await this._verifyConversionAccuracy(error, result)
43      }
44
45      return result
46    } catch (conversionError) {
47      // 錯誤處理：轉換失敗時的安全機制
48      return this._handleConversionFailure(error, conversionError, context)
49    } finally {
50      //  效能監控：追蹤轉換效能
51      this.performanceMonitor.recordConversion(performance.now() - startTime)
52    }
53  }
54
55  async _verifyConversionAccuracy(original, converted) {
56    // 檢查語意完整性
57    if (original.code !== converted.getOriginalCode()) {
58      throw new ConversionError('Code mapping失敗')
59    }
60
61    // 檢查資料完整性
62    const roundTripResult = this._convertBack(converted)
63    if (!this._isDataEquivalent(original, roundTripResult)) {
64      throw new ConversionError('Round-trip 驗證失敗')
65    }
66  }
67}

 1// src/core/errors/UC01ErrorAdapter.js (Sample Code)
 2class UC01ErrorAdapter {
 3  // 錯誤映射表：確保精確轉換
 4  static getErrorMapping() {
 5    if (!this._errorMapping) {
 6      this._errorMapping = {
 7        // DOM_ERROR 類型映射
 8        'PAGE_DETECTION_FAILED': {
 9          newType: 'DOM_ERROR',
10          newCode: 'DOM_001',
11          riskLevel: 'HIGH',
12          conversionComplexity: 'SIMPLE'
13        },
14        'ELEMENT_EXTRACTION_FAILED': {
15          newType: 'DOM_ERROR',
16          newCode: 'DOM_002',
17          riskLevel: 'MEDIUM',
18          conversionComplexity: 'SIMPLE'
19        },
20
21        // NETWORK_ERROR 類型映射
22        'CONNECTION_TIMEOUT': {
23          newType: 'NETWORK_ERROR',
24          newCode: 'NET_001',
25          riskLevel: 'HIGH',
26          conversionComplexity: 'MEDIUM'
27        },
28
29        // SYSTEM_ERROR 類型映射
30        'STORAGE_QUOTA_EXCEEDED': {
31          newType: 'SYSTEM_ERROR',
32          newCode: 'SYS_001',
33          riskLevel: 'CRITICAL',
34          conversionComplexity: 'COMPLEX'
35        }
36        // ... 更多映射定義
37      }
38    }
39    return this._errorMapping
40  }
41
42  // 高效能轉換：<1ms 目標
43  static convertError(standardError) {
44    const startTime = performance.now()
45
46    try {
47      // 快速查找：使用預建索引
48      const mapping = this.getErrorMapping()[standardError.code]
49      if (!mapping) {
50        throw new AdapterError(`無法映射錯誤代碼: ${standardError.code}`)
51      }
52
53      // 安全轉換：保持所有原始資訊
54      const errorCodesInstance = new ErrorCodes[mapping.newType](
55        mapping.newCode,
56        standardError.message,
57        {
58          ...standardError.details,
59          // 可追蹤性：保留轉換資訊
60          migrationInfo: {
61            originalCode: standardError.code,
62            convertedAt: new Date().toISOString(),
63            adapterVersion: 'UC01-v1.0',
64            riskLevel: mapping.riskLevel
65          }
66        }
67      )
68
69      // 效能監控：確保符合 <1ms 目標
70      const conversionTime = performance.now() - startTime
71      if (conversionTime > 1.0) {
72        console.warn(`轉換效能警告: ${conversionTime}ms 超過 1ms 目標`)
73      }
74
75      return errorCodesInstance
76    } catch (error) {
77      // 失敗處理：提供降級機制
78      return this._createFallbackError(standardError, error)
79    }
80  }
81
82  // 安全機制：轉換失敗時的降級處理
83  static _createFallbackError(originalError, conversionError) {
84    return new ErrorCodes.SYSTEM_ERROR('SYS_999', '錯誤轉換失敗', {
85      originalError: originalError.toString(),
86      conversionError: conversionError.message,
87      fallbackMode: true
88    })
89  }
90}

 1// 實際發現的問題模式 (Sample Code)
 2// 症狀1：開發者困惑
 3function handleErrorA() { throw 'STRING_ERROR' }
 4function handleErrorB() { throw new CustomError(...) }
 5function handleErrorC() { throw new Error(...) }
 6
 7// 症狀2：測試複雜化
 8expect(() => funcA()).toThrow('STRING_ERROR')      // 字串比對
 9expect(() => funcB()).toThrow(CustomError)         // 類型檢查
10expect(() => funcC()).toThrow(/error message/)     // 正則匹配

1# 實際測量結果 (Sample Code)
2npm run migration:analyze --metrics
3# 輸出：
4# - 錯誤處理模式：7 種不同方式
5# - 維護工時：每月 40+ 小時處理錯誤處理相關問題
6# - 新人學習成本：需要 2 週理解全部錯誤處理規範

 1// 實際發現的系統狀態 (Sample Code)
 2const systemErrorMappings = {
 3  'UC-01': 'string-based errors',      // 10 個字串錯誤
 4  'UC-02': 'StandardError class',      // 15 個 StandardError
 5  'UC-03': 'native Error objects',     // 12 個原生 Error
 6  'UC-04': 'mixed approaches',         // 混合模式
 7  'UC-05': 'custom error classes',     // 自定義錯誤類
 8  'UC-06': 'result objects',           // 結果物件模式
 9  'UC-07': 'exception throwing'        // 異常拋出模式
10}

 1// Chrome Extension 環境 (Sample Code)
 2class ChromeErrorHandler {
 3  serialize(error) {
 4    if (typeof error === 'string') return {type: 'string', value: error}
 5    if (error instanceof CustomError) return error.toJSON()
 6    // 每種錯誤類型需要特殊處理...
 7  }
 8}
 9
10// Flutter 環境 (Sample Code)
11class FlutterErrorHandler {
12  handleError(error) {
13    if (error is String) return StringError(error)
14    if (error is CustomException) return error.toDart()
15    // 完全不同的處理邏輯...
16  }
17}

1# 實際執行的分析指令 (Sample Code)
2npm run migration:debt-analysis
3# 結果：
4# - 重複代碼：14 個相似的錯誤處理模式
5# - 測試複雜度：每個模組需要不同的測試策略
6# - 序列化問題：無法統一 JSON 格式
7# - 文檔維護：7 套不同的錯誤處理說明文檔

1// 變更影響分析工具結果 (Sample Code)
2const impactAnalysis = {
3  affectedModules: 7,                    // 7 個功能模組
4  testFilesRequiringUpdate: 45,          // 45 個測試檔案
5  documentationPages: 12,                // 12 頁文檔
6  developersAffected: 4,                 // 4 位開發者
7  estimatedMigrationTime: '3-6 months'   // 預估遷移時間
8}

1技術可行性 × 資源可行性 × 時間可行性 × 風險可接受性 = 整體可行性

1影響範圍 + 複雜度 + 時間壓力 + 團隊能力 = 策略選擇

1風險等級 = f(技術複雜度, 業務影響度, 使用頻率, 依賴關係)

1安全第一 → 效率第二 → 完美第三

1分析工具 → 轉換工具 → 驗證工具 → 監控工具

1業務驗證 (頂層)
2│
3├── 整合驗證 (中層)
4│
5└── 單元驗證 (底層)

1測量 → 分析 → 最佳化 → 驗證 → 循環

1問題發現 → 根因分析 → 解決方案 → 效果評估 → 知識沉澱

1概念層：錯誤類型、處理流程、驗證規則
2實現層：語言特定的語法、API、慣例

1規則定義 → 語言適配 → 程式碼生成

1Phase 1：基本語法適配
2Phase 2：語言特性適配
3Phase 3：生態系統適配
4Phase 4：效能最佳化適配

1程式碼品質改善率 = (遷移後品質分數 - 遷移前品質分數) / 遷移前品質分數 × 100%
2遷移覆蓋率 = 已遷移項目數 / 總項目數 × 100%
3自動化率 = 自動處理項目數 / 總項目數 × 100%
4錯誤修復效率 = 平均修復時間(遷移後) / 平均修復時間(遷移前)

 1遷移速度 = 每週完成的遷移項目數
 2問題解決速度 = 平均問題解決時間
 3工具效率 = 工具節省的人工時間 / 工具開發時間
 4學習效率 = 團隊熟練度提升速度
 5```text
 6
 7##### 風險指標
 8
 9```bash
10風險實現率 = 實際發生的風險數 / 預計風險數 × 100%
11影響範圍控制 = 實際影響範圍 / 預估影響範圍
12回滾次數 = 總回滾次數（越少越好）
13嚴重事故率 = 嚴重事故次數 / 遷移週期數

1# 在現有的 GitHub 專案中初始化 Hugo
2hugo new site . --force

1# 使用 git submodule 安裝（推薦）
2git submodule add https://github.com/clente/hugo-bearcub.git themes/hugo-bearcub

 1# 基本設定
 2baseURL = 'https://你的用戶名.github.io/blog'
 3theme = 'hugo-bearcub'
 4copyright = '你的名字 (CC BY 4.0)'
 5defaultContentLanguage = 'zh-tw'
 6
 7# 產生 robots.txt 以利於 SEO
 8enableRobotsTXT = true
 9
10# 設定語法高亮
11[markup]
12  [markup.highlight]
13    lineNos = true
14    lineNumbersInTable = false
15    noClasses = false
16  [markup.goldmark]
17    [markup.goldmark.renderer]
18      unsafe = true
19
20# 多語言模式設定
21[languages]
22  [languages.zh-tw]
23    title = '我的部落格'
24    languageName = 'zh-TW 🇹🇼'
25    LanguageCode = 'zh-TW'
26    contentDir = 'content'
27    [languages.zh-tw.params]
28      madeWith = '使用 [Bear Cub](https://github.com/clente/hugo-bearcub) 製作'
29
30[params]
31  # 網站描述
32  description = '我的個人部落格，分享技術與生活'
33  
34  # 網站標題
35  title = '我的部落格'
36  
37  # 日期格式
38  dateFormat = '2006-01-02'
39  
40  # 主題樣式 (original 或 herman)
41  themeStyle = 'original'
42  
43  # 自動產生社群媒體卡片
44  generateSocialCard = true
45  
46  # 作者資訊
47  [params.author]
48    name = '你的名字'
49    email = 'your.email@example.com'

 1---
 2title: "首頁"
 3---
 4
 5# 歡迎來到我的個人部落格
 6
 7嗨！我是 **你的名字**，歡迎來到我的數位天地。
 8
 9## 關於這個部落格
10
11這裡是我分享想法、學習心得和生活點滴的地方。你可以在這裡找到：
12
13- **技術文章**：程式開發經驗分享
14- **學習筆記**：新技術的學習過程
15- **專案記錄**：有趣的專案開發歷程
16- **生活感悟**：日常生活的思考與體驗
17
18## 最新文章
19
20歡迎查看我的[最新文章](/posts/)，或者透過[標籤](/tags/)來瀏覽特定主題的內容。
21
22## 聯絡我
23
24如果你想要與我交流或合作，歡迎透過以下方式聯絡：
25
26- Email: your.email@example.com
27- 有任何問題或建議，也歡迎在文章下方留言
28
29---
30
31*感謝你的造訪，希望這些內容對你有所幫助！*

1# 建立新文章
2hugo new content posts/文章標題.md

 1---
 2title: "文章標題"
 3date: 2025-08-22T20:41:50+08:00
 4draft: false
 5description: "文章描述，用於 SEO 和社群分享"
 6tags: ["標籤1", "標籤2"]
 7---
 8
 9文章內容寫在這裡...
10
11## 小節標題
12
13- 列表項目
14- 另一個項目
15
16### 程式碼範例
17\`\`\`bash
18echo "Hello Hugo!"
19\`\`\`

1# 摘要設定
2summaryLength = 200  # 摘要字數限制

 1---
 2title: "文章標題"
 3date: 2025-01-XX
 4tags: ["標籤1", "標籤2"]
 5---
 6
 7這是文章的開頭部分，會顯示在列表中。
 8
 9這裡是更多內容...
10
11<!--more-->
12
13這裡是文章的其餘部分，只會在單篇文章頁面中顯示。

1---
2title: "文章標題"
3date: 2025-01-XX
4description: "這是文章的摘要，會顯示在列表中"
5tags: ["標籤1", "標籤2"]
6---
7
8文章內容...

 1name: Deploy Hugo site to GitHub Pages
 2
 3on:
 4  push:
 5    branches: ["main"]
 6  workflow_dispatch:
 7
 8permissions:
 9  contents: read
10  pages: write
11  id-token: write
12
13jobs:
14  deploy:
15    runs-on: ubuntu-latest
16    steps:
17      - uses: actions/checkout@v4
18        with:
19          submodules: recursive
20      
21      - name: Setup Hugo
22        uses: peaceiris/actions-hugo@v2
23        with:
24          hugo-version: 'latest'
25          
26      - name: Build
27        run: hugo --minify
28        
29      - name: Deploy to GitHub Pages
30        uses: peaceiris/actions-gh-pages@v3
31        with:
32          github_token: ${{ secrets.GITHUB_TOKEN }}
33          publish_dir: ./public

1# 建立 layouts/partials 目錄
2mkdir -p layouts/partials
3
4# 複製主題的 social_card.html 到你的專案中
5cp themes/hugo-bearcub/layouts/partials/social_card.html layouts/partials/

1<!-- 將第 2 行的字型 URL 替換為支援中文的字型 -->
2{{ $font := resources.GetRemote "https://github.com/adobe-fonts/source-han-sans/raw/release/OTF/TraditionalChinese/SourceHanSansTC-Bold.otf" }}

1<!-- 原來的程式碼 -->
2{{ $author := (default $.Site.Params.author.name ($.Param "author") ) }}
3
4<!-- 修改為 -->
5{{ $author := (or ($.Param "author") $.Site.Params.author.name) }}

1[params]
2  # 自動產生社群媒體卡片
3  generateSocialCard = true

1# 啟動開發伺服器
2hugo server
3
4# 包含草稿
5hugo server --buildDrafts
6
7# 指定 IP 和 Port
8hugo server --bind 0.0.0.0 --port 1313