[Tech Debt][EPIC] TypeScript Refactoring and Zod Schema Optimization

[andrewck24]

問題描述

當前專案存在以下技術債務：

• 部分檔案仍使用 .jsx 格式，未完全遷移至 TypeScript
• 元件缺乏明確的 Props 型別定義，存在隱性的 any 型別
• Zod schemas 散落在各元件中，缺乏重用性和一致性
• 表單數字欄位處理不統一，容易產生型別錯誤

目標

• ✅ 完整 TypeScript 化專案
• ✅ 建立統一的 Zod Schema 架構
• ✅ 提升程式碼型別安全性和可維護性
• ✅ 優化表單數字欄位處理

執行階段

• 第一階段：基礎建設與型別修正

  • [Tech Debt] 檔案格式標準化 (.jsx → .tsx) #225
  • [Tech Debt] 元件 Props 型別定義 #226
  • [Tech Debt] 表單狀態管理型別安全 #227

• 第二階段：Zod Schema 架構重構

  • 建立通用 Zod Schema 模組
  • Schema 檔案架構調整與集中化

• 第三階段：應用新的 Schema 架構

  • 應用通用 Schema
  • 從集中的 Schema 衍生型別與 Props

🚨 整體風險評估與緩解策略

高風險項目

1. • Schema 架構調整: 大範圍的檔案重構

• 緩解: 分批進行，每次只處理一個 feature 資料夾
• 備份: 建立分支保存重構前的狀態

2. • 型別與 Props 整合: 可能影響多個元件

• 緩解: 逐個元件進行，完成後立即測試
• 回歸測試: 確保所有表單功能正常

中風險項目

1. Props 型別定義: 可能發現現有的型別不一致問題

   • 緩解: 建立標準的型別定義模式
   • 漸進式: 先處理簡單元件，累積經驗後處理複雜元件

2. 表單狀態管理: Zod schema 與現有邏輯可能不匹配

   • 緩解: 仔細測試每個表單的驗證邏輯
   • 向下相容: 確保新的 schema 不會破壞現有功能

低風險項目

1. 檔案重新命名: 純粹的檔案操作
2. 通用 Schema 模組: 新增功能，不影響現有程式碼

📈 成功指標

• 型別安全: TypeScript 嚴格模式下無錯誤
• 測試覆蓋: 所有修改的元件通過現有測試
• 開發效率: IDE 提供完整的型別提示和自動補全
• 程式碼品質: ESLint 和 TypeScript 檢查通過
• 文件化: 所有新的 schema 和型別都有完整說明

🔄 執行建議

1. 按階段執行: 嚴格按照三個階段順序進行
2. 頻繁提交: 每完成一個小任務就提交，方便回滾
3. 同步測試: 每個 Issue 完成後都要進行完整測試
4. 團隊協作: 重大變更前先與團隊成員討論
5. 文件更新: 同步更新相關的開發文件和 README

Story Points: 34 | 預估工時: 2.5-3.5 週