Practice Website Kit — Astro + PagesCMS + Cloudflare Pages
技術棧與選擇原因
| 層級 | 選擇 | 原因 |
|---|---|---|
| 網站框架 | Astro | 預設輸出靜態 HTML，幾乎無 JavaScript，手機載入快速，無需修補漏洞，內容使用 Markdown 搭配型別化 frontmatter。 |
| 內容編輯 | PagesCMS (app.pagescms.org) | 免費、開源、基於 Git：工作人員透過網頁表單編輯，每次儲存就是一次 Git 提交。不需要資料庫或 CMS 伺服器來維護。 |
| 託管 | Cloudflare Pages | 免費方案足以容納診所網站（慷慨的建置分鐘與頻寬、支援多個自訂網域），無品牌標示，允許商業使用，全球 CDN，自動 HTTPS。部署 = 連結 Git 儲存庫。 |
| 儲存庫 | GitHub（診所擁有） | 網站的單一據點：Astro 讀取它，PagesCMS 寫入它，Cloudflare 從它建置。 |
讓這個架構奏效的規則：網站是出版物，不是應用程式。 頁面、簡介、文章都是內容。預約、付款、訊息、目錄已有現成系統——網站只會嵌入與連結它們，絕不重新實作，也不接收它們的資料。
給代理的指示
- 交付成果 = 一個診所擁有的可運作儲存庫 + 三個已建立的連線（PagesCMS → 儲存庫、Cloudflare Pages → 儲存庫 + 網域） + 一次通過 CMS 驗證的端到端編輯。如果你沒有帳號存取權限，請產出完整的儲存庫，並為所有人提供一份逐步的連線檢查清單。
- 先進行設定訪談。切勿捏造診所事實——專業證照、執照、保險合約、費用、語言、從業年資。使用佔位符並標記，直到所有人提供資料為止。
- 根據即時設定檔驗證每個平台行為，而非憑記憶：
references/pagescms-config.md中的 PagesCMS filename-template 規則曾讓一個真實網站首次儲存失敗——請將 CMS 儲存測試視為「設定完成」的定義。
設定訪談（在開始建置前詢問一次）
- 診所身份——診所名稱、網域（以及 DNS 在哪——當 DNS 也在 Cloudflare 時，Cloudflare 託管最順暢）、標誌/顏色（若有）、要顯示的電話/電子郵件。
- 規模——個人或團體；治療師清單（姓名、專業證照、執照州別、是否有照片）用於建立簡介頁面。
- 頁面——確認
references/site-blueprint.md中的藍圖（新增/移除：例如是否為每個服務建立獨立頁面？是否需要資源/部落格區塊？是否嵌入轉介目錄？）。 - 語言——單一語言，或是鏡像樹狀結構（例如英文在
/，中文在/zh/）？鏡像結構代表每個語言都需有人工翻譯的頁面，並有各自的 slug——翻譯需要預算；切勿機器翻譯與臨床相關的內容並未經審閱就直接上線。 - 動態嵌入——哪些現有系統會出現在網站上（預約頁面、聯絡表單應用程式、轉介目錄、安全訊息入口）及其 URL。這些會成為 iframe 嵌入 + 備用連結。
- 編輯者——上線後誰負責更新內容（僅所有人？一位管理員？治療師撰寫文章？）——這決定了 PagesCMS 的存取權限，以及網站有多少部分由 CMS 管理而非程式碼管理。
- 現有資產——要遷移的現有網站內容、照片（及其使用權利）、Google 商家檔案與目錄清單，網站必須與這些保持一致。
嚴格規則
- 診所擁有每個帳號——網域註冊商、GitHub、Cloudflare。使用診所的登入資訊建立，並設定診所能控制的復原選項。
- 內容是資料，不是程式碼。 任何編輯者可能修改的內容（治療師簡介、服務、費用、常見問題、文章）都必須放在 Markdown/frontmatter 中，並定義內容綱要——絕不硬編碼到
.astro範本中。 - PagesCMS 的 filename 範本使用
{fields.slug}（或該集合的實際欄位路徑）。裸寫{slug}是無效的，會導致每次 CMS 儲存都失敗並顯示不明確的錯誤。修正設定後，請重新載入 CMS——它會快取每次工作階段的設定。 - 網站不會收集任何臨床資訊。 沒有症狀文字框、沒有「告訴我們你的情況」表單。聯絡方式 = 預約連結/嵌入、電話，以及必要時的路由表單應用程式——加上危機專線（美國為 988，緊急狀況為 911）顯示在聯絡頁面以及任何邀請聯絡的頁面上，並使用網站的語言。
- 嵌入內容需有備用連結。 每個 iframe（預約、目錄）都搭配一個指向相同系統的純連結，這樣被封鎖的框架就不會讓客戶無法繼續操作。
- 資訊宣稱紀律： 網站上的保險合約、費用、專業證照與可用時間必須與診所的資料來源（其名冊/記錄）一致。網站應該是最後編輯事實的地方——如果一個數字存在於兩個地方，需明確指定哪一個為準。
- 效能是治療網站的特色——人們可能感到焦慮、用手機、從目錄簡介點進來。在將圖片放入儲存庫之前先壓縮；一張 2 MB 的英雄圖片是錯誤，不是資產。
建置順序
- 儲存庫 + Astro 骨架 + 依照
references/astro-setup.md的內容模型與references/site-blueprint.md的頁面。 - 本地建置成功；內容佔位符已標記並列出給所有人。
- PagesCMS 設定 + 依照
references/pagescms-config.md的實際儲存測試。 - Cloudflare Pages 連線 + 自訂網域依照
references/cloudflare-pages-deploy.md。 - SEO/效能檢查依照
references/seo-and-performance.md。 - 交接依照
references/maintenance-and-handoff.md；驗證依照references/test-checklist.md。
參考文件
references/architecture-and-stack.md— 三個層級、資料流程、靜態對診所的意義references/site-blueprint.md— 頁面、每個頁面必須包含的內容、治療專屬必要項目references/astro-setup.md— 專案佈局、內容集合 + 綱要、多語言樹狀結構references/pagescms-config.md—.pages.yml、集合、媒體、filename-template 規則references/cloudflare-pages-deploy.md— 專案設定、建置設定、自訂網域、預覽references/seo-and-performance.md— 中繼資料、結構化資料、Sitemap/RSS、llms.txt、圖片references/maintenance-and-handoff.md— 編輯工作流程、更新、備份、誰擁有什麼references/test-checklist.md— 驗收測試，首先是 CMS 儲存測試