fix(ratewise): 修復內容頁與 404 頁殘留的 React #418 hydration mismatch

[s123104]

Summary

staging 驗證（#459 comment、.claude/product-intel/qa-staging-report.md P1-2）發現 #595 部署後 app 殼層四頁已乾淨，但內容頁（/faq/、/guide/、/usd-twd/、/sell-rate-vs-mid-rate/、/usd-twd/100/）每次載入仍拋 #418 args[]=text，404 頁拋 args[]=HTML。本 PR 定位並修復兩個獨立根因。

根因 A｜內容頁 args[]=text：建置時間格式化隨時區漂移

apps/ratewise/src/config/version.ts 的 getFormattedBuildTime() 用 toLocaleDateString('zh-TW')／toLocaleTimeString('zh-TW') 未指定 timeZone。staging/CI 在 UTC build → SSG HTML 寫入 Built on 2026/07/05 19:27；使用者瀏覽器在 Asia/Taipei → client 算出 2026/07/06 03:27 → Footer tooltip 文字節點 mismatch。只有掛 Layout（含 Footer）的內容頁中招；app 殼層走 AppLayout 無 Footer，所以 #595 後看似「殼層已修、內容頁沒修」——實為另一獨立根因。

為何 #595 驗證沒抓到（誠實檢討）：#595 本地驗證 build 與瀏覽器同在 Asia/Taipei，兩側格式化結果相同、必然通過——是驗證方法盲點（缺跨時區組合），不是路由集合漏抽。本次以 TZ=UTC pnpm build × 台北時區瀏覽器在本地完整重演 staging 現象後定位。

修法：getFormattedBuildTime() 兩處格式化固定 timeZone: 'Asia/Taipei'。

根因 B｜404 頁 args[]=HTML：SPA fallback 送首頁快照仍被 hydrate

未知路徑經 SW navigation fallback（或任何 /* → index.html 主機）拿到首頁 SSG 快照（帶 data-server-rendered=true），client 端渲染 NotFound 樹 → 結構性 mismatch。vite-react-ssg 0.8.9 production 因 NODE_ENV gate 一律 hydrate；上游已在 PR #90 merge 修正（!isSSR → render()）但尚未發版。

修法（三件一組）：

1. vite.config.ts onBeforePageRender 為每個預渲染頁注入 <meta name="ssg-route"> 標記
2. src/utils/ssgFallbackGuard.ts＋main.tsx：hydration 前比對標記與當前 URL，不符（404／SW shell fallback／無尾斜線 fallback）即清空 root 並移除 data-server-rendered
3. patches/vite-react-ssg@0.8.9.patch：對齊上游 PR fix(pwa): 修復 Safari PWA 離線顯示「無法打開網頁」問題 #90 一行修正，讓無標記快照走乾淨 render()；上游發版後應移除 patch 改升版

防回歸

• version.test.ts：getFormattedBuildTime() 必須等於 Asia/Taipei 顯式格式化結果（CI 為 UTC，timeZone 被移除即紅）
• prerender.test.ts：抽樣 dist 頁必含 ssg-route 標記；faq 頁 Built on 文字必須等於以 Asia/Taipei 格式化 build-time meta 的結果（build 機器時區漂移即紅）
• ssgFallbackGuard.test.ts：stale 快照降級 render／正確路由維持 hydrate／無標記保守不介入

驗證（零 #418 證據）

停 SW、production build＋preview，11 路由（/、/multi、/favorites、/settings、/faq/、/guide/、/about/、/usd-twd/、/sell-rate-vs-mid-rate/、/usd-twd/100/、404 未知路徑）Playwright console 巡檢：

組合	修復前	修復後
台北 build × 台北瀏覽器	4 筆（fallback 類）	0
台北 build × UTC 瀏覽器	10 筆	0
UTC build × 台北瀏覽器（staging 重演）	內容頁全中	0

404 頁修復後正確渲染 NotFound（h1「404」＋h2「頁面不存在」）、/multi（無尾斜線 fallback）正確渲染多幣別頁。

閘門

• pnpm typecheck 全綠
• ratewise vitest：3322 passed | 2 skipped（含新增守門測試）
• pnpm build:ratewise 成功（pre-push 亦全綠）
• changeset：patch（使用者可感知：console 不再出現錯誤）
• 002 已更新（reward+1／penalty−1，總分 +134 不變）

Refs

• 追蹤 issue：[UX2026][P0] QA-P0-001 React hydration #418 #459（staging 驗證 comment 指認中招頁面）
• staging 報告：.claude/product-intel/qa-staging-report.md P1-2
• 前置修復：fix(ratewise): 修復 SSG 語言與 client 首屏不一致造成的 React #418 #595（i18n SSG 語言首屏，本 PR 補齊其未涵蓋的兩個獨立根因）

Follow-up（已立案，非本 PR 範圍）

• [debt] vite-react-ssg patch 移除追蹤：僅限上游發布含 PR90 修復的版本（0.9.x 不含，勿升） #623：patches/vite-react-ssg@0.8.9.patch 升版陷阱——上游 PR fix(pwa): 修復 Safari PWA 離線顯示「無法打開網頁」問題 #90 已 merge 未發版，升版時必須移除 patch 改吃官方版本
• [bug] SSG 落地頁殘留無 locale 的 toLocaleString()：非 zh-TW 瀏覽器 locale 觸發同類 #418 #624：全 repo 無 locale 參數的 toLocaleString() 盤點（SingleConverter／MultiConverter 等金額顯示，同型時區／locale 漂移風險）
• [test] 跨時區 hydration 閘門制度化＋404 軟回應既有債記錄 #625：跨時區驗證閘門制度化（build TZ ≠ browser TZ 組合納入 hydration 修復 SOP）＋ SPA fallback 軟 404（200 回應）既有債

請勿直接 merge：等待 review 與使用者授權。

Made with Cursor

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[github-actions]

⚠️ Deprecation Warning: The deny-licenses option is deprecated for possible removal in the next major release. For more information, see issue 997.

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[github-actions]

✅ SEO 審計通過！所有 2026 標準驗證項目都符合要求。

• ✅ Sitemap 2026 標準
• ✅ Breadcrumb Schema
• ✅ JSON-LD 結構化數據
• ✅ 內部連結結構