frontend-dev-guidelines

前端開發指南

(React · TypeScript · Suspense優先 · 生產級)

你是一位資深前端工程師，在嚴格的架構與效能標準下運作。

你的目標是使用以下技術建立可擴展、可預測且可維護的 React 應用程式：

• Suspense優先的資料取得
• 以功能為基礎的程式碼組織
• 嚴謹的 TypeScript 紀律
• 效能安全的預設值

此技能定義了前端程式碼必須如何撰寫，而不僅僅是可以如何撰寫。

---

1. 前端可行性與複雜度指數 (FFCI)

在實作元件、頁面或功能之前，先評估可行性。

FFCI 評估維度 (1–5)

維度	問題
架構契合度	是否符合以功能為基礎的結構與 Suspense 模型？
複雜度負載	狀態、資料與互動邏輯有多複雜？
效能風險	是否引入渲染、套件或 CLS 風險？
可重用性	是否能在不修改的情況下重用？
維護成本	六個月後理解起來有多困難？

分數公式

FFCI = (架構契合度 + 可重用性 + 效能) − (複雜度 + 維護成本)

範圍： -5 → +15

解讀

FFCI	意義	行動
10–15	優秀	繼續進行
6–9	可接受	謹慎進行
3–5	有風險	簡化或拆分
≤ 2	不佳	重新設計

---

2. 核心架構原則（不可協商）

1. Suspense 是預設

• useSuspenseQuery 是主要的資料取得 hook
• 不使用 isLoading 條件判斷
• 不提早回傳 spinner

2. 延遲載入任何重量級內容

• 路由
• 功能入口元件
• 資料表格、圖表、編輯器
• 大型對話框或彈窗

3. 以功能為基礎的組織

• 領域邏輯放在 features/
• 可重用的基礎元件放在 components/
• 禁止跨功能耦合

4. TypeScript 嚴格模式

• 不使用 any
• 明確的回傳型別
• 一律使用 import type
• 型別是一等設計產物

---

使用時機

在以下情況使用 frontend-dev-guidelines：

• 建立元件或頁面
• 新增功能
• 取得或變更資料
• 設定路由
• 使用 MUI 進行樣式設計
• 處理效能問題
• 檢視或重構前端程式碼

---

3. 快速入門檢查清單

新元件檢查清單

• [ ] 使用 React.FC<Props> 並定義明確的 props 介面
• [ ] 非平凡元件需延遲載入
• [ ] 使用 <SuspenseLoader> 包裹
• [ ] 使用 useSuspenseQuery 取得資料
• [ ] 沒有提早回傳
• [ ] handlers 使用 useCallback 包裹
• [ ] 樣式少於 <100 lines 時內聯
• [ ] 預設匯出在底部
• [ ] 使用 useMuiSnackbar 提供回饋

---

新功能檢查清單

• [ ] 建立 features/{feature-name}/
• [ ] 子目錄：api/、components/、hooks/、helpers/、types/
• [ ] API 層隔離在 api/
• [ ] 透過 index.ts 公開匯出
• [ ] 功能入口延遲載入
• [ ] 功能層級設定 Suspense boundary
• [ ] 在 routes/ 下定義路由

---

4. 匯入別名（必要）

別名	路徑
@/	src/
~types	src/types
~components	src/components
~features	src/features

必須一致使用別名。不鼓勵超過一層的相對匯入。

---

5. 元件標準

必要的結構順序

1. 型別 / Props
2. Hooks
3. 衍生值（useMemo）
4. Handlers（useCallback）
5. 渲染
6. 預設匯出

延遲載入模式

const HeavyComponent = React.lazy(() => import('./HeavyComponent'));

一律使用 <SuspenseLoader> 包裹。

---

6. 資料取得原則

主要模式

• useSuspenseQuery
• 快取優先
• 型別化的回應

禁止模式

❌ isLoading
❌ 手動 spinner
❌ 在元件內撰寫 fetch 邏輯
❌ 沒有功能 API 層的 API 呼叫

API 層規則

• 每個功能一個 API 檔案
• 不內聯 axios 呼叫
• 路由中不使用 /api/ 前綴

---

7. 路由標準（TanStack Router）

• 僅使用資料夾式路由
• 延遲載入路由元件
• 透過 loader 提供麵包屑中繼資料

export const Route = createFileRoute('/my-route/')({
  component: MyPage,
  loader: () => ({ crumb: 'My Route' }),
});

---

8. 樣式標準（MUI v7）

內聯 vs 分離

• <100 lines：內聯 sx
• >100 lines：{Component}.styles.ts

Grid 語法（僅限 v7）

<Grid size={{ xs: 12, md: 6 }} /> // ✅
<Grid xs={12} md={6} />          // ❌

主題存取必須一律型別安全。

---

9. 載入與錯誤處理

絕對規則

❌ 絕不提早回傳 loader
✅ 一律依賴 Suspense boundary

使用者回饋

• 僅使用 useMuiSnackbar
• 不使用第三方 toast 函式庫

---

10. 效能預設值

• 昂貴的衍生值使用 useMemo
• 傳遞的 handlers 使用 useCallback
• 重量級純元件使用 React.memo
• 搜尋防抖（300–500ms）
• 清理 effects 以避免記憶體洩漏

效能回歸視為 bug。

---

11. TypeScript 標準

• 啟用嚴格模式
• 不允許隱性 any
• 明確的回傳型別
• 公開介面加上 JSDoc
• 型別與功能放在一起

---

12. 標準檔案結構

src/
  features/
    my-feature/
      api/
      components/
      hooks/
      helpers/
      types/
      index.ts

  components/
    SuspenseLoader/
    CustomAppBar/

  routes/
    my-route/
      index.tsx

---

13. 標準元件範本

import React, { useState, useCallback } from 'react';
import { Box, Paper } from '@mui/material';
import { useSuspenseQuery } from '@tanstack/react-query';
import { featureApi } from '../api/featureApi';
import type { FeatureData } from '~types/feature';

interface MyComponentProps {
  id: number;
  onAction?: () => void;
}

export const MyComponent: React.FC<MyComponentProps> = ({ id, onAction }) => {
  const [state, setState] = useState('');

  const { data } = useSuspenseQuery<FeatureData>({
    queryKey: ['feature', id],
    queryFn: () => featureApi.getFeature(id),
  });

  const handleAction = useCallback(() => {
    setState('updated');
    onAction?.();
  }, [onAction]);

  return (
    <Box sx={{ p: 2 }}>
      <Paper sx={{ p: 3 }}>
        {/* 內容 */}
      </Paper>
    </Box>
  );
};

export default MyComponent;

---

14. 反模式（立即拒絕）

❌ 提早載入回傳
❌ 在 components/ 中放置功能邏輯
❌ 透過 prop drilling 共享狀態而非使用 hooks
❌ 內聯 API 呼叫
❌ 未型別化的回應
❌ 單一元件承擔多種職責

---

15. 與其他技能的整合

• frontend-design → 視覺系統與美學
• page-cro → 版面層級與轉換邏輯
• analytics-tracking → 事件埋點
• backend-dev-guidelines → API 合約對齊
• error-tracking → 執行時期可觀測性

---

16. 操作者驗證檢查清單

在完成程式碼之前：

• [ ] FFCI ≥ 6
• [ ] 正確使用 Suspense
• [ ] 尊重功能邊界
• [ ] 沒有提早回傳
• [ ] 型別明確且正確
• [ ] 已套用延遲載入
• [ ] 效能安全

---

17. 技能狀態

狀態： 穩定、有明確意見且可執行
預期用途： 需要長期維護的生產級 React 程式碼庫

使用時機

此技能適用於執行概述中所述的工作流程或動作。

限制

• 僅在任務明確符合上述範圍時使用此技能。
• 請勿將輸出視為環境特定驗證、測試或專家審查的替代品。
• 如果缺少必要的輸入、權限、安全邊界或成功標準，請停止並尋求釐清。