chore: Phase 2-4 死代碼清理計畫 (Dead Code Cleanup)

[s123104]

📋 背景

Phase 1 死代碼分析已完成（commit 22dd3dca），識別了 26 個未使用檔案、100+ 未使用導出、9 個未使用依賴。

分析報告:

• .reports/dead-code-analysis.md (完整分析)
• .reports/cleanup-summary.md (執行摘要)

Phase 1 完成項目: ✅

• 新增缺失測試依賴 (vitest, xml2js)
• 生成完整分析報告
• 所有測試通過 (1904/1904)

---

🎯 Phase 2: 依賴清理 (Medium Risk)

待驗證的未使用依賴

Root package.json:

{
  "@changesets/changelog-github": "用於 changeset 格式化",
  "@playwright/test": "E2E 測試框架",
  "@vitejs/plugin-react-swc": "Vite React 插件",
  "@vitest/coverage-v8": "測試覆蓋率工具",
  "vite-ssg-sitemap": "SSG sitemap 生成器"
}

apps/ratewise/package.json:

{
  "lighthouse": "效能測試工具",
  "workbox-*": "7 個 Service Worker 套件",
  "zustand": "狀態管理（未使用）"
}

任務清單

• 建立依賴使用矩陣 (npm scripts + CI mapping)
• 檢查 .github/workflows/*.yml 中的依賴引用
• 檢查 package.json scripts 中的依賴引用
• 驗證 workbox-* 是否被 Service Worker 使用
• 確認 zustand 是否為計畫中的功能
• 移除確認未使用的依賴
• 執行完整測試套件驗證
• 更新 CHANGELOG.md

風險評估: 🟡 Medium - 可能影響 CI/CD 流程

---

🎯 Phase 3: 未使用導出清理 (Low-Medium Risk)

安全刪除候選

1. Workspace 工具函數:

// scripts/lib/workspace-utils.mjs
export const getSSGApps          // ❌ 未使用
export const validateAppConfig   // ❌ 未使用

2. SEO 配置導出:

// apps/*/seo-paths.config.mjs
export const SEO_FILES           // ❌ 未使用
export const normalizePath       // ❌ 未使用
export const shouldPrerender     // ❌ 未使用
export const getIncludedRoutes   // ❌ 未使用
export const APP_CONFIG          // ❌ 未使用

3. 數據檔案:

// apps/nihonname/src/constants.ts
export const SURNAME_DATA_FULL       // ❌ 未使用
export const getSurnameDetail        // ❌ 未使用
export const getFunnyNamesByCategory // ❌ 未使用
// ... 8 個未使用導出

// apps/nihonname/src/data/funnyNames.ts
// 40+ 個未使用的 pun 類別導出

4. JSON-LD Schema:

// apps/quake-school/src/seo/jsonld.ts
export const courseSchema        // ❌ 未使用
export const quizSchema          // ❌ 未使用

// apps/nihonname/src/seo/jsonld.ts
export const buildImageObjectSchema  // ❌ 未使用

任務清單

• 使用 rg 搜索每個導出的引用情況
• 建立自動化導出使用分析工具（基於 AST）
• 確認無動態 import 或字串引用
• 逐一刪除確認未使用的導出
• 每次刪除後執行測試驗證
• 考慮歸檔大型數據檔案（而非直接刪除）
• 更新 CHANGELOG.md

風險評估: 🟢 Low-Medium - 需驗證無隱藏引用

---

🎯 Phase 4: 元件導出標準化 (High Risk)

重複導出模式

17 個元件同時有命名和默認導出：

// 當前模式
export const ComponentName = () => { /* ... */ }
export default ComponentName; // ❌ 重複

// 需要標準化為
export default function ComponentName() { /* ... */ }
// 或
export const ComponentName = () => { /* ... */ }

受影響元件:

• quake-school: 1 個
• nihonname: 11 個
• ratewise: 12 個
• haotool: 4 個

任務清單

• 決定標準（命名 vs 默認導出）
• 使用 AST 工具分析所有 import 引用
• 建立自動化重構腳本
• 分批重構（每次 3-5 個元件）
• 每批次後執行完整測試套件
• 驗證 SSR/SSG 功能正常
• 更新相關文檔
• 更新 CHANGELOG.md

風險評估: 🔴 High - 需要大量 import 更新 + 完整回歸測試

---

⚠️ Service Worker 測試腳本審查

檔案: apps/ratewise/scripts/test-*-sw*.mjs (9 個)

狀態: 🔶 保留 (建立於 2026-01-11, < 1 個月)

任務清單

• 2026-05-08 再次審查（3 個月後）
• 確認 Service Worker 功能正常運作
• 檢查 git history 是否有後續使用
• 如確認為調試工具，移至 archive 或刪除

---

📊 預期影響

Phase 2 (依賴清理)

• 移除 9-15 個未使用依賴
• 減少 node_modules 大小約 50-100MB
• 加快 CI/CD 安裝速度

Phase 3 (導出清理)

• 清理 100+ 個未使用導出
• 減少程式碼行數約 500-1000 行
• 改善 tree-shaking 效果

Phase 4 (元件標準化)

• 統一 17 個元件導出方式
• 改善程式碼一致性
• 更新約 50-100 個 import 語句

---

✅ 完成標準

每個 Phase 必須達成:

• 所有測試通過 (1904/1904)
• TypeScript 檢查無錯誤
• Prettier 格式檢查通過
• Pre-commit hooks 全通過
• Build 成功
• CHANGELOG.md 已更新
• 建立獨立 commit (可回滾)

---

📅 建議時程

• Phase 2: 本週完成（依賴驗證 + 移除）
• Phase 3: 下週完成（導出清理）
• Phase 4: 下 Sprint（元件標準化 + 完整測試）
• SW 腳本審查: 2026-05-08

---

📚 參考文檔

• Dead Code Analysis Report
• Cleanup Summary
• Phase 1 Commit

---

🔧 工具

已安裝分析工具:

pnpm knip          # 未使用檔案和導出
pnpm depcheck      # 未使用依賴
pnpm ts-prune      # TypeScript 未使用導出（需修復 tsconfig）

建議工具:

• AST-based 重構工具 (jscodeshift)
• 自動化 import 更新 (ts-morph)
• Dependency graph visualizer

---

⚠️ 注意事項

1. 測試優先: 每次清理前後都要執行完整測試
2. 漸進式: 小批次清理，易於回滾
3. 獨立 Commit: 每個 Phase 或每批清理獨立提交
4. CI/CD 驗證: 推送後確認 CI 通過
5. 文檔同步: 更新 CHANGELOG 和相關文檔
6. 團隊溝通: 清理前通知團隊，避免衝突

---

Created by: refactor-clean skill
Related: Phase 1 完成於 commit 22dd3dca