互動式網站架構 是做什麼的？
成果
建立一個對外公開的正式環境 Next.js 網站，其內容、敘事、視覺識別與互動品質至關重要。這是一個適用於內容主導型網站的通用架構：品牌與行銷網站、SaaS 與產品網站、發布頁面、編輯性質頁面、作品集、社群、會議、文件型網站，以及沈浸式展示網站。
核心是固定的：
- 伺服器端渲染內容；
- 窄小的客戶端島嶼；
- 經過驗證的內容合約；
- 共享的設計與動態代碼；
- 原生的瀏覽器行為；
- 伺服器回應中的 SEO 與無障礙設計；
- 基於路由的效能預算。
選擇產品所需的模組：
| 模組 | 使用時機 |
|---|---|
| 內容收集與詳情 | 網站包含專案、文章、產品、人物、活動或類似記錄 |
| 作品集或案例研究 | 組織需要透過作品來證明自身能力 |
| 沈浸式檔案庫 | 視覺探索是產品的主要介面 |
| 商店 | 網站銷售數位或實體產品 |
| CMS 適配器 | 編輯者能夠獨立於發布週期進行發布 |
| 聯絡表單 | 僅有郵件連結或行事曆連結不足 |
不要將非必要的模組強加到不需要它們的網站上。
典型的配置檔案重用相同的核心：
- SaaS 或產品：登陸頁、產品介紹、功能、內容集合、文件或更新日誌。
- 品牌或發布：活動敘事、產品揭露、等候清單、社會證明。
- 編輯性質：集合索引、文章詳情、作者、主題、搜尋。
- 社群或會議：講者、議程、場次、場地、票務。
- 作品集：專案索引、案例詳情、視覺檔案庫、聯絡。
- 商務：目錄、產品詳情、結帳、下載或履行。
在採取行動之前請先閱讀
- 對於每一次建構、重新設計或架構變更，請閱讀 references/architecture-contract.md。
- 在建立資料夾、合約、服務、適配器或伺服器動作之前，請閱讀 references/code-architecture.md。
- 在安裝、升級或移除依賴項之前，請閱讀 references/dependency-matrix.md。
- 對於新的應用程式，請遵循 references/build-playbook.md。
- 對於新路由、內容類型、島嶼、檔案庫、商店產品或遷移，請遵循 references/evolve-playbook.md。
- 在接受或發布之前，請遵循 references/quality-gates.md。
可重複使用的範本位於 assets/templates/ 下。僅在它們與所選架構相符時才從它們出發。不要盲目複製每個範本。
不可協商的規則
- 預設將頁面組合與主要內容保持在伺服器元件中。
- 將
use client放在最小的可行葉節點。在可能的情況下，透過客戶端包裝器來動畫呈現伺服器端渲染的子元素。 - 將 TypeScript 資料合約視為每個內容實體、中繼資料記錄、畫廊與 Sitemap 條目的唯一事實來源。
- 為每個交疊互動提供一個真實的路由，該路由在沒有客戶端狀態、JavaScript 或雜湊值的情況下也能正常運作。
- 優先使用原生 HTML 行為：連結、按鈕、表單、
<dialog>、焦點管理以及瀏覽器歷史記錄。 - 將金鑰（secret）保留在僅限伺服器的模組中。只有公開的識別碼才能使用
NEXT_PUBLIC_*。 - 當存在商務功能時，將價格、授權決策、付款確認以及受保護的下載保留在伺服器端。
- 尊重
prefers-reduced-motion、鍵盤導航、可見的焦點指示器、語意化標題以及無腳本（no-script）下的可讀性。 - 避免將一個路由的內容放入另一個路由的初始客戶端套件中。當客戶端殼層需要計數或標籤時，從伺服器傳遞小型的摘要資訊。
- 使用模組化單體架構，包含輕量的路由適配器、自有的功能模組、明確的埠口（ports）以及單一的組合邊界。
- 偏好穩定的依賴項。不要在 Canary 版本的 React 建構上啟動新的正式環境應用程式。
預設技術棧
除非網站有明確記錄的理由需要不同，否則使用依賴項矩陣中經過驗證的確切版本。
- Node 26 LTS 系列與 pnpm。
- Next.js App Router、React、React DOM、TypeScript。
- Tailwind CSS 4 用於代碼（token）、重置（reset）與工具佈局。
- CSS Modules 用於路由或元件特定的組合。
- Motion 用於 React 編排與手勢處理。
- 對於足夠處理的互動，使用原生的 Dialog、Canvas、SVG、CSS 與 Web Animations API。
- 個別引入 Lucide 圖示。
- Zod 用於內容與外部輸入的邊界驗證。
- Vercel 用於部署、分析與圖片傳遞。
- 當需要商務功能時，使用 Stripe Embedded Checkout 與伺服器動作。
工作順序
- 盤點公開頁面：登陸頁、內容索引、詳情路由、轉換路徑、法律條款路由、搜尋、檔案庫與商務。
- 在實作之前，先凍結路由清單與客戶端邊界圖。
- 在建立檔案之前，先指派功能擁有者、埠口、路由適配器與外部適配器。
- 在建構區塊之前，先建立內容實體模型與所需的多媒體。
- 建立全域代碼、字體、間距、狀態、減少動畫行為以及圖片慣例。
- 建構伺服器殼層、導航、路由備用方案（fallbacks）與 SEO 中繼資料。
- 一次新增一個客戶端島嶼。記錄每個島嶼必須在客戶端執行的原因。
- 使用原生 Dialog 與 URL 狀態建構交疊互動。同時新增對應的標準頁面路由。
- 在定義好資料、備用方案、減少動畫行為與效能邊界之後，再加入複雜的視覺效果。
- 僅在操作模式要求時，才加入 CMS、商務、帳戶或持久化儲存。
- 執行架構邊界檢查、結構性審計、重點測試、品質關卡與正式環境預覽驗收。
- 分別報告已實作的行為、已驗證的證據以及未經驗證的限制。
決策規則
- 對於懸停、焦點、按下、揭露、跑馬燈（marquee）與簡單狀態變更，使用 CSS 過渡效果。
- 對於協調變體、佈局過渡、拖曳、存在感（presence）以及與滾動連結的編排，使用 Motion。
- 僅在無法使用 DOM、SVG 與 CSS 可靠表現視覺效果時，才使用 Canvas 或 WebGL。加入可見性暫停、DPR 限制、清理、減少動畫行為以及靜態備用方案。
- 保持內容集合為伺服器端渲染。僅將計數、標籤或選定的記錄傳送到客戶端交疊殼層。
- 當同一內容也有標準頁面時，使用原生的
<dialog>來顯示預覽與面板。對於深入、冗長或需要獨立連結的內容，使用專用路由。 - 對於與應用程式一同發布的小型團隊，使用經過驗證的程式碼內容。當編輯者需要獨立發布時，在儲存庫適配器後引入 CMS。
- 當商店僅需即時購買與下載時，使用無狀態的 Stripe 工作階段。當產品需要授權、退款、帳戶、訂單記錄或重試時，再加入資料庫與經過驗證的 Webhook。
- 僅在識別出元件庫擁有的基礎元件（primitive）後，才新增 Radix、shadcn 或其他元件庫。原生的元素與網站自有的基礎元件是基線。
- 將作品集、檔案庫與商店視為模組。它們重用核心的內容、路由、樣式、動態與安全合約。
必要的建構產出物
建立並維護這些網站層級的產出物：
docs/architecture.md：路由圖、客戶端邊界、內容所有權、外部服務與效能預算。src/features/*/domain與src/features/*/application：經過驗證的合約與功能。src/platform/*：外部適配器與僅限伺服器的組合根節點（composition root）。src/shared/*：經過驗證的跨功能合約與設計基礎元件。src/components/*：具有明確名稱的伺服器組合與客戶端島嶼。src/app/*：頁面、佈局、中繼資料、Sitemap、robots.txt 與路由處理器。.env.example：名稱與用途，絕不能包含真實的金鑰。- 內容驗證、客戶端狀態機、伺服器動作與關鍵瀏覽器旅程的測試。
- 包含預覽、瀏覽器、無障礙、效能、SEO 與條件式商務證據的發布檢查清單。
結構性審計
在搭建好架構後、發布前，執行架構邊界檢查與套件審計：
pnpm arch:check
node scripts/audit_site.mjs --root /path/to/app
在 CI 中使用 --strict 以便在出現警告時視為失敗。該腳本檢查依賴項存在性、路由與內容結構、客戶端/伺服器金鑰危險、對話框與動畫安全措施、測試、SEO 檔案以及原始碼映射暴露。它補充測試，並不取代測試。
完成合約
只有在以下所有條件都滿足時，建構才算完成：
- 路由與邊界圖與實作相符；
- 依賴圖無循環且
arch:check通過； - 路由使用功能的公開 API，且組合根節點擁有接線（wiring）權責；
- 應用程式在沒有 Canary 或同儕依賴項衝突的情況下成功建構；
- 關鍵內容出現在伺服器 HTML 中；
- 交疊、選單與鍵盤路徑能正常運作並恢復焦點；
- 減少動畫與無腳本備用方案已驗證；
- 中繼資料、Sitemap、robots.txt、標準 URL（canonical URLs）與社交圖像皆已存在；
- 初始路由的 JS 與圖片載入量保持在文件規定的預算內；
- 當存在商務功能時，使用伺服器擁有的價格、伺服器端確認以及受保護的下載；
- 預覽與正式環境的證據分別記錄。