CLAUDE.md — /tools/alphafold（AlphaFold 學習中心）

AlphaFold 開放學習工具。主題 01 = 肌少症網絡（IA 可容多主題）。Phase 1 = 前端 + 最小後端代理。

專案資訊

• 線上：https://paulkuo.tw/tools/alphafold（**四語 i18n**：/tools/alphafold + /en /ja /zh-cn）
• i18n 架構（與 /wiki 同模式）：共用元件 src/components/alphafold/AlphaFoldHub.astro（吃 lang prop）+ 字典 src/i18n/alphafold.ts（zh-Hant 母版 + alphafold.{en,ja,zh-cn}.json 機器翻譯，待 Paul 覆核）+ 4 薄路由。語言中立結構（座標/accession/蛋白名/顏色/天數）在元件、譯文在字典。改文案改字典（zh-Hant 改 .ts、其餘改對應 .json），別動元件邏輯。client 端字串經 <script define:vars> 注入。改任一語頁面內容記得 bump CACHE_VERSION（尤其 zh-Hant 的 hreflang/切換器）。
• 技術棧：Astro 靜態頁 + is:inline vanilla JS（忠實移植 Cowork 定稿原型）；3Dmol.js（jsDelivr CDN）
• 後端：Worker paulkuo-ticker（api.paulkuo.tw）新增三個公開代理端點（見下）
• 起始日：2026-07-12（Code，承 Cowork handoff AlphaFold 學習中心 Phase 1）
• 狀態：頁面已於 localhost 驗過、尚未部署 Pages（新搜尋文案待 Paul 審 + 部署 go）；Worker 代理已上線

架構要點（踩過的坑，務必遵守）

1. 所有 class/id 前綴 af- / af，且包在 .af-hub 容器：主站全域 CSS 有 .hero{display:flex}、.card、.btn、.panel、.tag 等同名規則會「反向滲入」同名元素（實測把 hero 擠成直排）。用 <div> 取代 header/section/footer 元素、CSS 變數掛 .af-hub（非 :root）避免覆蓋主站變數。改版時別新增未前綴的 class。
2. 動態 DOM（tracker/shelf/concepts/network）用 is:inline script + <style is:global>：innerHTML/createElement 建立的元素拿不到 Astro scoped 屬性，scoped <style> 匹配不到 → 用 global（已前綴，不外洩）。
3. 3Dmol 從 jsDelivr 載（cdn.jsdelivr.net/npm/[email protected]，CSP 白名單）：原型用的 3Dmol.org 不在 CSP script-src 白名單。defer + ensure3Dmol() 輪詢，非阻塞。
4. 3D 結構與蛋白事實一律走 Worker 代理（api.paulkuo.tw），前端不直連 EBI/UniProt：主站 CSP connect-src 只放 self + api.paulkuo.tw；代理另解 CORS + 邊緣快取 + 版本無關。
5. AlphaFold 檔案版本會漂移：DB 已 v4→v6（2025-08-01）。代理不硬編版本，先打 alphafold.ebi.ac.uk/api/prediction/{acc} 取當前 pdbUrl 再抓，避免 pinned 版本靜默 404。

Worker 代理端點（worker/src/protein.js，公開、無認證、邊緣快取、CORS *）

• GET /api/protein/search?q= → 名稱/基因/accession → 候選（reviewed 優先）
• GET /api/protein/:uniprot → 正規化事實 JSON（gene/name/species/length/function/localization/domains/disease/interactions/pdb_refs/alphafold_entry）
• GET /api/af/:uniprot → AlphaFold PDB 結構（text/plain）
• accession 格式 ^[A-Z0-9]{6,10}$ 先驗證再建上游 URL（SSRF 防護）。bump PROXY_CACHE_VERSION 可整池失效。

Smoke Test（每次 deploy 後跑，結果寫 worklog）

• ✅ /tools/alphafold 線上可開、色系與主站一致（hard refresh 驗；Phase 1 zh-only）
• ✅ 追蹤器勾選 + 本週目標編輯，重整後仍在（localStorage）；可任意跳關
• ✅ 速查：輸入 P01308（胰島素）能生成速查卡（事實 + 3D + pLDDT）；查無結構有明確 empty state
• ✅ Myostatin 精讀卡 3D 可轉、pLDDT 四色（0053d6/65cbf3/ffdb13/ff7d45）、N→C 切換正常；經代理載入非直連
• ✅ 每個動畫旁有「代表什麼/來源」；全站無任何暗示 AlphaFold 顯示折疊過程的動畫/文案（科學誠信紅線）
• ✅ 概念小抄可展開；網絡圖 Myostatin 可點、待建節點有提示；書櫃顯示 Myostatin 已建 + 新增 tile
• ✅ footer CC BY 4.0 標註在；免責聲明（結構假說 ≠ 實驗證據）在
• API 端各打一支確認 200 + 一支既有端點（/health）確認無回歸

已知待辦 / Phase 1.5+

• 精讀卡持久化成 wiki entity（pillar life，進知識星圖）— #3 決策已定 wiki entity，尚未實作
• 曝光：頁面目前未被任何導覽/pillar hub 連結（BaseLayout 無 pillar prop、tool 頁不在 articles collection）；曝光機制待定
• D1 登入跨裝置同步（Paul 2026-07-12 拍板 defer 到 Phase 1.5）
• 3D 進階：信心度漸入揭示、導覽動畫（依序點亮 domain/結合位）、構型 morph（需該蛋白有兩個 PDB 構型）
• 搜尋區文案為新增（非原型），待 Paul 審定

檔案結構

• index.astro — 整頁（markup + <style is:global> + <script is:inline>）
• ../../../../worker/src/protein.js — 代理端點；worker/src/index.js router 內接三條路由