fullstack-workflow

此技能為在 Inbox Zero 生態系統中構建全端功能的開發人員提供了一套完整的架構模式。它強制執行嚴格的關注點分離，確保整個程式碼庫的一致性，同時簡化從資料獲取到 UI 變更的開發週期。通過利用伺服器動作 (Server Actions) 進行變更和 SWR 進行用戶端狀態管理等既定模式，此工作流程減少了錯誤並提高了應用程式的可維護性。它非常適合正在處理複雜 Next.js 專案並需要可靠模板進行高效資料操作的軟體工程師。

• 標準化資料流：使用 GET API 路由進行唯讀資料操作，並封裝 withAuth 或 withEmailAccount 中介軟體以確保安全性。

• 變更操作：利用 next-safe-action 定義型別安全的伺服器動作，配備用於輸入驗證的 Zod 結構與用於監控的 Sentry metadata。

• 用戶端優化：實作 SWR 掛鉤，實現高效的前端資料獲取與快取處理。

• 表單管理：整合 React Hook Form 與 zodResolver，確保在調用伺服器動作前進行嚴格的用戶端驗證。

• 錯誤處理：內建自定義錯誤提示工具，可優雅地管理並向終端用戶呈現操作錯誤。

• 構建新功能時務必遵循結構：先定義驗證結構 (schema)，然後定義伺服器動作，接著是 API 路由，最後是對應的 SWR 掛鉤。

• 確保所有 API 路由均受現有中介軟體保護，以維持對電子郵件帳戶和用戶上下文的安全存取。

• 使用現有的 action clients (例如 actionClient) 以確保正確的上下文 (userId 或 emailAccountId) 被注入到每個變更操作中。

• 透過定義回傳型別 (使用 Awaited<ReturnType<typeof getData>>) 來利用型別推論，從而獲得完整的 IDE 支援與執行期安全性。

• 保持邏輯分離；將業務邏輯保留在伺服器動作中，並將 UI 狀態邏輯保留在自定義 React 掛鉤中。