網頁應用程式架構
請先閱讀 web-craft。僅載入任務所需的參考資料；套件和框架適配器僅用於所選的套件和框架。
對照表
| 主題 | 參考資料 |
|---|---|
| 伺服器與客戶端元件、BFF、環境變數與秘密邊界 | references/server-client.md |
| API 層、錯誤模型、狀態所有權、表單、樂觀 UI、URL 狀態 | references/data-forms.md |
| 載入、錯誤和未找到邊界、重試、離線、骨架計時 | references/states.md |
| i18n：註冊表、解析、URL、目錄、格式化、後端標頭 | references/i18n.md |
| RTL、邏輯屬性、方向性圖示、入口 | references/rtl.md |
| 身份驗證、授權、XSS、CSRF、Cookie、快取隔離、個人資料 | references/auth-security.md |
| 主題：使用者偏好 vs 應用的主題、系統變更、無閃爍 | references/theming.md |
| 公開頁面的 SEO | references/seo.md |
| GEO：在 AI 搜尋和助手工具中的可見性 | references/geo.md |
| Next.js App Router 適配器 | references/fw-next.md |
| React + Vite 適配器 | references/fw-vite.md |
| shadcn/ui 適配器 | references/kit-shadcn.md |
| Ant Design 適配器 | references/kit-antd.md |
| Material UI 適配器 | references/kit-mui.md |
| 搭配 node-craft（或任何 OpenAPI）後端使用 | references/node-craft-contract.md |
| 官方來源與審查日期 | references/sources.md |
普遍適用的規則
- 按需定義邊界。 元件之所以成為客戶端元件，是因為它需要互動性、瀏覽器 API 或客戶端狀態，而非預設如此。保持互動式區塊小巧。切勿將僅供伺服器使用的程式碼、ORM 客戶端或秘密引入客戶端程式碼；公開的環境變數並非秘密。
- 單一 API 層。 一個 fetch 客戶端、一個以穩定代碼和狀態為鍵的型別化錯誤模型、一種身份驗證行為。功能不應自行建構 fetch 和重試邏輯。伺服器資料位於查詢/快取層，全域客戶端狀態位於小型 store 或 context 中，表單狀態位於表單工具中，本地 UI 狀態位於元件內。模擬資料源透過配置啟用，僅用於開發和測試，絕不透過編輯功能來切換；不受信任的回應在執行時期進行解析。
- 表單。 除非專案使用其他工具，否則使用 react-hook-form + Zod。設定
mode: 'onTouched'、reValidateMode: 'onChange'，聚焦並滾動到第一個錯誤，透過setError處理伺服器欄位錯誤，錯誤後保留值，禁止雙重提交。伺服器始終是驗證的主體。 - 狀態具有邊界。 路由層級的載入和錯誤邊界，以及資料串流處的本地 Suspense；一個元件失敗不應導致整個頁面空白。
- i18n 是架構的一部分。 使用真實的引擎、語言環境註冊表（BCP 47 標籤、方向、目錄、顯示名稱）、除非另有選擇否則採用英文後備、伺服器上的請求範圍語言環境、伺服器與客戶端使用相同的初始語言環境、按語言環境和命名空間載入目錄、從應用程式語言環境對應套件和日期語言環境。
- 安全性屬於伺服器端。 在後端進行授權。對您渲染的任何 HTML 進行消毒。Cookie 工作階段需要 CSRF 保護。個人回應絕不進入共用快取；語言環境和用戶相關的回應應變化其快取鍵。
- 公開頁面應易於找到。 在伺服器上渲染語言環境正確的中繼資料，每種語言都有標準網址、僅針對實際對應頁面提供 hreflang 替代連結、網站地圖、與可見內容相符的結構化資料。GEO 從此開始：可索引、可引用的內容以及明確的 AI 爬蟲政策。不保證排名或引用。
- 套件應被適配，而非包裹。 主題和權杖來自產品的設計決策。僅為重複的產品行為或固定 API 才包裹套件元件。請勿在套件自身的動畫系統上疊加第二個動畫系統。
完成條件
應用 web-craft → 完成，再加上：客戶端 bundle 中不得包含秘密或僅供伺服器使用的模組；不同語言環境或不同使用者的兩個並行請求不得混合資料；首次渲染應使用正確的語言和主題；每個聲稱的套件/框架組合均經過實際驗證。