# 2026-07-17 Cloudflare Pages 文件站部署 — SUMMARY

> 一次 arc 部署了兩個文件站（test repo docs-site 站 + BE specs 手冊站），並為 BE specs 加了版本導覽頁機制。本檔記 BE 側為主，test 側部署細節記在 test repo `docs-site/README.md` 部署段。

## 為何做

docs-site（test repo）與 FR-047 spec 手冊（BE repo）原本都只有「file:// 離線看」或「rsync 到公司 server」的假設。Raymond 決定用 Cloudflare Pages（免費方案）做正式對外託管，且拍板 **各 repo 文件站分開部署、各自網址**（原本考慮過單一 `guidantai-docs` 站聚合多 repo，因 Pages 一專案只能連一 repo、跨 repo 聚合要 sync script 副本，放棄聚合改分站）。

## 上線結果（皆已驗證 200）

| 站 | 網址 | 來源 repo / 輸出目錄 | 觸發 |
|----|------|---------------------|------|
| 測試文件站 | https://guidant-ai-test-docs.pages.dev | compliance-manager-test / `docs-site` | push main 且動到 `docs-site/*` |
| SPEC 手冊站 | https://guidant-ai-spec-docs.pages.dev | compliance-manager-be / `docs/specs` | push main 且動到 `docs/specs/*` |

兩站皆：GitLab 整合自動部署、無 build command（html 是版控內產物）、免費方案（頻寬/請求無限，500 builds/月）。

SPEC 站 URL 結構：`/` 版本導覽頁 → `/v1.8.0/html/README.html` 各版手冊入口。

## BE commits（已 push origin/main）

| hash | 內容 |
|------|------|
| `0049479b` | `render_html.py` 加 `build_version_index()`：掃 `docs/specs/v*/html/README.html` 產 `docs/specs/index.html` 版本卡片導覽頁（新版在前、最新標記）；整版 build 末尾自動再生 + `--index-only` 模式 |
| `472e331f` | 導覽頁維護備註（「本頁由 render_html.py 產生…」）從畫面移除改 HTML 註解——對外頁不露內部資訊 |

test repo commit（未 push）：`aa849cf` docs-site/README.md 部署段改記 Pages 實況。

## 行為差異

- `python scripts/deliverables/render_html.py docs/specs/v1.8.0` 現在**末尾會自動重生 `docs/specs/index.html`**；未來開 `v1.9.0/` 重跑 build，導覽頁自動長出新卡，零手動。
- spec 產線變成：改 md → 跑 render_html.py → commit（含 html/ + index.html）→ push main → **自動上線**。
- push to main 從「純備份」升格為「上線開關」——只要 commit 動到 `docs/specs/`（BE）或 `docs-site/`（test）就會部署。

## 部署操作 handover（dashboard 側，Raymond 操作）

- Cloudflare dashboard → Workers & Pages；兩專案皆 Raymond 個人帳號。
- 建站三要點：Framework 預設「無」、build command 留空、輸出目錄如上表。
- **組建監看路徑**在專案建好後設：專案 → 設定 → 組建 → Build watch paths → include。
- 踩過的坑 ×2：輸出目錄欄位貼上時**帶尾端空格** → `Output directory "docs/specs " not found`，兩個站都踩了一次。log 特徵是引號內路徑尾有空白；清空重打即解。
- 另一個入口坑：dashboard「建立應用程式」預設把人導去 **Workers** Git 流程（特徵：部署命令 `npx wrangler deploy`、要建 API Token）——要切到 **Pages** 分頁走 Connect to Git 才是本 arc 用的流程。

## 未決 / follow-up

- **Cloudflare Access（限 email 登入）未設**——兩站目前知道網址就能看。Raymond 已知悉，要加時再設（免費層 50 使用者內）。
- test repo `aa849cf` 未 push（push 等 Raymond 明示；下次 push 會觸發一次 docs-site 部署，無害）。
- BE `docs/specs/v1.8.0/html/README.html` 工作區曾有誤植字元 `ㄥ`（來源不明的手滑），已 revert——html 是產物勿手改的又一例證。