# CM-1429 交接：需求文件站公網側欄壞掉，成因未查明

> 2026-08-29。前一棒（CM-1429 runner）context 過長、且在此問題上反覆誤判，由 user 喊停轉交。
> **本檔只交接「未解問題」**；CM-1429 卡片本身的三項工作已完成並 push。

## 🧭 先懂這個問題（不懂就不要動手）

需求文件站有**兩個開法**，一個好一個壞：

| 開法 | 狀態 |
|------|------|
| 本機（repo 根起 http server，或 `file://` 直接開檔） | ✅ 側欄、樣式、上下篇全正常 |
| 公網 https://guidantai-feature-doc.jedicotech.com/ | ❌ **側欄空的**（樣式狀態見下方待驗） |

**user 明確表示「公網站之前也是好的」** —— 這句話與前一棒查到的證據對不起來，**兩者必有一邊是錯的，這正是要查的核心**。不要跳過這個矛盾直接動手修。

## 📌 前一棒查到什麼（含已知不可靠的部分）

### 可信的事實（有實測支撐）

1. **Cloudflare Pages 專案 `fr-doc` 的設定**（user 提供截圖）：
   - Git 存放庫：`auditmanager/compliance-manager-be`
   - 組建命令：（空）
   - **組建輸出：`docs/features/`**
   - 根目錄：（空）
2. **站根＝`docs/features/`**。用「只存在於該層的檔」驗過：`/KNOWN-DEAD-LINKS.md` 拿得到真檔（該檔在 `docs/features/` 下），`/CLAUDE.md`、`/docs/features/index.html` 皆回 404 fallback。
3. **404 fallback 是 `index.html`**（md5 `d6a4e6e8f0d260d482f8615e3eab3e1f`）。**判讀公網回應時必須拿 md5 比對**，否則 404 頁會被誤判成 200 成功。
4. **`docs/features/` 底下從來沒有 CSS/JS**（`git ls-tree -r 7b3b9662` 驗過，只有兩支孤立 mermaid.min.js）。頁面引用的是 `../../specs/_shared/*`，那在站根之外。
5. 頁面引用路徑 **push 前後完全相同**（`../../specs/_shared/doc-base.css`），前一棒沒有改動它。

### 前一棒的推論（**未證實，可能全錯**）

> 「站根是 docs/features，CSS/JS 在站外，所以公網一律拿不到 → 公網站從來就沒有樣式和側欄」

**這個推論與 user 的「之前是好的」直接衝突。** 且前一棒在得出它之前，曾多次拿「單點 curl 200」當證據推出過三個互相矛盾的結論（詳見下方「踩過的坑」），可信度低。

## 🕳️ 踩過的坑（不要重蹈）

| 坑 | 後果 |
|----|------|
| 拿 `curl -o /dev/null -w '%{http_code}'` 當「檔案存在」的證據 | 404 fallback 也回 200。**必須比 md5** |
| 沒加 cache-buster 就測 | 先前測 `doc-base.css` 得到「真檔 ✅」，加 `?x=$RANDOM` 後變成 404 fallback ——**那次是 CDN 快取的舊部署殘留**，並據此推出一串錯結論 |
| 用單點測試反覆猜架構 | 前後翻案三次（「Pages SPA fallback 吃掉 .js」→「部署根是 repo 根」→「features-site 才是源」），全錯。**user 一張設定截圖就解決** |
| 誤認 `docs/features-site/` 是公網站的源 | 那是 CM-1185/1186 的 MkDocs 站（8/12 後未更新），**與 fr-doc 這個 Pages 專案無關**。已由截圖排除 |

**方法教訓：這類「部署後與本機不一致」的問題，先拿到部署端的實際設定與部署歷史，再回頭看 code。反過來做會繞很久還繞錯。**

## 🎯 待查（建議順序）

### Q1（最關鍵）「之前是好的」是何時、看到什麼？

只有 user 或 Pages 後台能回答。要拿到的是：
- **Pages 部署歷史**：側欄從哪一次部署開始壞？對應哪個 commit？
- 若能定位到某次部署，`git show <commit>` 比對該版頁面的資產引用路徑，就能知道是否曾經有過「資產在站內」的版本。

⚠️ 前一棒查 `git ls-tree` 認為「從來沒有」，但那只查了 `7b3b9662` 一個點，**沒有掃過完整歷史**。建議：
```bash
git log --all --oneline --diff-filter=A -- 'docs/features/**/*.css' 'docs/features/**/doc-nav.js'
```

### Q2 公網站現在到底壞到什麼程度？

前一棒最後一次測得「樣式在、側欄不在」，但**那次沒加 cache-buster**，不可信。重測（每條都比 md5）：

```bash
cd <repo>
B="https://guidantai-feature-doc.jedicotech.com"
IDX=$(/sbin/md5 -q docs/features/index.html)   # 404 fallback 的指紋
for u in /specs/_shared/doc-base.css /specs/_shared/doc-nav.js \
         /FR-068-2608-log-forwarding/nav-data.js /FR-068-2608-log-forwarding/README.html; do
  got=$(/usr/bin/curl -s --max-time 12 "$B$u?cb=$RANDOM" | /sbin/md5 -q)
  [ "$got" = "$IDX" ] && echo "404fallback  $u" || echo "有真檔        $u"
done
```

### Q3 若確認「資產在站外」就是成因，修法二選一（**需 user 拍板，不要自己決定**）

- **(A) build 時把 `doc-base.css` / `doc-artifact.css` / `doc-nav.js` / `mermaid.min.js` 複製一份進 `docs/features/_shared/`**，頁面改引用站內路徑。單一 repo 內兩份副本，需注意同步（`docs/specs/_shared/` 仍是 SPEC 站在用的正本）。
- **(B) 改 Pages 設定**：組建輸出改成 repo 根（那頁面現有的 `../../specs/_shared/` 相對路徑就成立），但站的 URL 結構會整個改變（變成 `/docs/features/...`），自訂網域的既有連結全部要調。

## ⚠️ 前一棒可能造成的新問題（要查證，不要假設沒事）

前一棒在 `f5917a0d` 改了 **`docs/specs/_shared/doc-nav.js`**（加 `window.__GUIDANT_NAV__` 優先路徑，讓 `file://` 離線可用）與 **`doc-artifact.css`**（加 `.home.hub`、`.docnav a.ext` 樣式）。

**這兩支是 SPEC 站與需求站共用的。** 已驗證 `docs/specs/current` 與 `docs/spec-site/` 重 build 後皆零 diff，但**沒有驗過 SPEC 站在公網的實際渲染**。接手方應確認 https://guidantai-spec.jedicotech.com/ 沒有被影響。

## 📍 現況座標

- **branch**：`main`，working tree 乾淨，**已 push 到 origin**（無待 push）
- **本棒三支 commit**（CM-1429 卡片工作，與本問題無關，已完成）：
  - `f5917a0d` FR-068 design §5 實作回寫＋SPEC 連結改指新站並進側欄＋登記表 build 成頁
  - `9bc86522` 資料夾連結導站首頁＋所有含 md 資料夾自動建站（12→80 站，201→647 頁）
  - `d87e9360` 18 條死連結建檔（`docs/features/KNOWN-DEAD-LINKS.md`，決策者裁示不修）
- **Notion**：CM-1429「修正待驗證」（卡片三項工作已回寫；**本交接的公網問題尚未寫進任何卡**）
- **本機 server**：PID 59339 在跑（`python3 -m http.server 8099`，repo 根），要收掉自行 kill
- **相關 skill**：`doc-site-build`（已於本棒更新，含 specs 欄規則、自動建站、KNOWN-DEAD-LINKS 指引）

## 🔍 冷接自檢（動手前先答，答不出來就回去讀）

1. 公網站的組建輸出目錄是什麼？頁面引用的 CSS 路徑指到哪？兩者關係為何？
2. 為什麼「curl 回 200」不能證明檔案存在？該怎麼驗？
3. user 說「之前是好的」，這句話與前一棒的推論衝突在哪？
4. 前一棒改過哪兩支共用資產？它們還被誰用？