機制問答頁維護手冊

🔴 問答頁不能搬到別的深度：畫圖程式走 ../../_shared/，只有放在 docs/features/<某資料夾>/<子資料夾>/ 這一層才找得到。搬到別層就要一起改檔尾載入器的 LOCAL_MERMAID。找不到時會退到網路下載，離線就會變原始文字。

• 左側選單 <nav class="toc"> 分六組，每組一個 <ol>，每題一列 <li><a href="#qN" data-page="qN">。
• 右側每題一個 <section class="page" id="qN" hidden>，裡面一張或多張 <article>。第一張是主題答案，之後是補問，補問不另開頁。
• 每頁底部 .pager 有上一題、下一題。
• 檔尾兩段程式：頁面路由（依網址 #qN 顯示該頁），以及畫圖與點擊放大。

1. 在選單對應組的 <ol> 加一列 <li><a href="#qN" data-page="qN" title="完整題目"><span class="tn">QN</span><span class="tt">短題目</span></a></li>。要加註（如「＋2 補問」「11-02 新增」）就在 tt 裡面再放一個 <span class="cnt">…</span>。
2. 在 <div class="content"> 內適當位置加 <section class="page" id="qN" hidden>，含 crumb、<article>、.pager。
3. 重接前後兩頁的 .pager：前一頁的「下一題」指向新題、後一頁的「上一題」指向新題。
4. 補問：在既有那頁最後一張 <article> 之後加一張，題號欄寫 QN<br><small>補問 2</small>，選單那列的 cnt 數字跟著改。

寫法：先結論再事實；每個說法對回程式碼行號或實查結果；有問題用「問題、建議、理由」三段。標題要專業，不要口語化或對仗句。發現缺陷寫進「發現的問題」，待決策的方案取捨寫進「待討論」。

• 用 <pre class="mermaid">，第一行一定要寫完整的 %%{init: ...}%%。
• 流程圖（flowchart）的 init 一定要帶 'darkMode':false 與 mainBkg、nodeTextColor。只給一半時，線上平台在使用者系統是深色模式時會把方塊換成深色，深字配深底看不見。時序圖照現有那幾張的 init 抄即可。
• 目錄結構這類用 <pre class="tree"> 樹狀文字，不用流程圖。
• 圖自動可點擊放大，不必額外處理。

F=docs/features/FR-175-2611-mechanism-qa-hub/qa/mechanism-qa.html
grep -c 'border-left' "$F"     # 要是 0（全專案禁左側粗色邊框）

標籤平衡檢查（先把 mermaid 與 script 內容換掉再解析，否則圖裡的 <br/> 會誤報）：

python3 -c "
import html.parser,re,sys
src=open(sys.argv[1],encoding='utf-8').read()
src=re.sub(r'<pre class=\"mermaid\">.*?</pre>','<pre class=\"mermaid\"></pre>',src,flags=re.S)
src=re.sub(r'<script>.*?</script>','',src,flags=re.S)
class P(html.parser.HTMLParser):
    def __init__(s): super().__init__(); s.st=[]; s.err=[]
    def handle_starttag(s,t,a):
        if t not in ('br','meta','link','img','hr','input'): s.st.append(t)
    def handle_endtag(s,t):
        if s.st and s.st[-1]==t: s.st.pop()
        else: s.err.append(t)
p=P(); p.feed(src); print('mismatch',p.err[:3],'unclosed',p.st[:3])" "$F"

畫圖與放大要實際開來驗。用測試專案已裝的 Playwright，無頭模式（不開視窗）：開 #flow、#q8，確認圖畫成 SVG、點圖出現 .dv-overlay、按 ESC 會關。至少再測一次擋掉全部網路，確認離線也能畫。

1. 先讀一次線上網址（Artifact 工具 action: read），確認沒被別人改過；有改就先把對方的改動併進 repo 那支檔。
2. 發布同一支檔到同一個網址（url 帶線上網址）。
3. 把 repo 那支檔 commit，只 add 這支（與交接檔），禁用 -am。

線上平台會再包一層外殼並注入自己的畫圖程式。問答頁檔尾的載入器偵測到平台的 /_runtime/mermaid 就不畫，只幫平台畫好的圖掛上放大，不會重複畫。

沒有 writer 就不要發布，只改 repo 這支並 commit，請決策者發布。分享設定只能由決策者在網頁上改。

• 只讀與整理。不改程式、不出包、不發布更新站、不寫入任何主機或資料庫、不 push。
• 188 STG、189 POC 只能唯讀查。主機上的 .env、guidant.env 只准列鍵名，不讀值；比對密碼只比雜湊前幾碼。
• 決策者說「先別寫」就只回答；問完一輪說「更新文件」才一次寫。
• 發現的問題交各案首腦開卡，本區不動手修。