頁面內需求文件閱讀入口（檢視器）
目標
把專案裡已經存在的需求文件接入產品介面，讓使用者在當前頁面直接查閱對應說明；同時保證入口不拖慢首屏、不洩露歷史內容、不在生產環境意外暴露內部文件。
與文件撰寫的邊界
- 本技能只負責閱讀入口的實作：入口位置、文件映射、建置複製、渲染、搜尋、懶載入、錯誤狀態、生產暴露面、測試與走查。
- 文件內容由
prd-rule-authoring或任何來源提供；本技能不規定文件必須怎麼寫，也不要求專案必須使用 prd-rule-authoring。 - 兩者互不依賴：沒有閱讀入口的專案也應產出需求文件；有閱讀入口也不改變文件的撰寫規則。
- 唯一耦合面是「文件目錄 + Markdown 約定」：路徑、標題、可渲染語法。約定寫在專案配置中，不寫死在技能裡。
何時使用
- 產品/開發/測試希望「在當前頁面直接看規則」，避免分屏查 MD；
- 已有成體系的 Markdown 需求文件，需要唯讀展示；
- 需要把內部文件接入交付演示，但必須控制生產可見性。
不適用：線上編輯/協作評論、文件審批流程、全文檢索服務化、權限分級閱讀（可後續擴展，不在最小實作內）。
閱讀順序
| 檔案 | 何時讀 |
|---|---|
references/integration-design.md | 設計入口/建置/映射/懶載入時 |
references/rendering-and-search.md | 渲染受限 MD、歷史章節過濾、搜尋時 |
references/acceptance-checklist.md | 測試、走查與驗收時 |
references/ops-and-governance.md | 生產暴露面、文件更新與發佈流程時 |
最小實作清單
- 入口：只在有文件映射的頁面顯示；無映射不渲染（不留死按鈕）；入口本身零文件載入。
- 來源：文件源為倉庫內 Markdown（或等價靜態檔案）；建置期複製到產物目錄；建置時做產物↔映射雙向校驗（缺失/孤兒即建置失敗）。
- 映射：路由/頁面 → 文件路徑的註冊表為唯一映射源；文件樹按模組分組；模組級文件單獨標識。
- 載入：抽屜/面板打開後才請求文件；首次打開載入當前文件；搜尋索引在打開後空閒建立；不得啟動時預載文件。
- 渲染：受限 Markdown 渲染（標題/段落/列表/表格/程式碼/引用/分隔線/連結）；全部 HTML 轉義，只輸出白名單標籤；中文/括號檔名分段 URL 編碼；適配子路徑部署；標題錨點 slug 做 HTML/URL 危險字元（
<>&"'）安全化，錨點生成單一出口（目錄/正文/搜尋/定位共用）。 - 閱讀器規則：只展示最新說明——不渲染「更新記錄/更新日誌」章節（含其內容），目錄與搜尋同步排除；如來源文件含歷史快照註記，按專案約定過濾或由文件作者不寫。
- 互動：目錄點擊定位、動作頁可按章節提示預設定位、全域關鍵字搜尋（按文件分組、當前頁命中置頂、片段去 Markdown 噪音）與跳轉、錯誤狀態與重試、關閉。搜尋結果導航上下文：點擊命中只切換正文，不清空搜尋詞/結果列表；保留結果區滾動位置；命中項高亮（穩定 key，至少包含文件+錨點+標題，必要時加片段區分同章節多條）；提供明確的「清空搜尋」入口恢復文件樹；從文件樹打開文件時清空搜尋；不重建索引。紅線：目錄若吸頂或展開列表常駐正文上方，點擊定位必須按覆蓋高度偏移防遮擋；自動化用遮擋級斷言（
toBeVisible不判遮擋）。吸頂摺疊目錄、滾動補償等升級形態細節見references/integration-design.md§7。 - 生產暴露面：入口開關只控制按鈕，不保護靜態文件；生產必須二選一：建置排除文件目錄，或對文件路徑加鑑權（寫入生產接入門禁）。
- 測試：映射完整性、建置產物一致性、歷史章節不顯示、懶載入零預載、搜尋與跳轉、搜尋結果上下文保持（關鍵詞/結果/滾動位置保留、連續命中、清空恢復樹、高亮唯一、不重建索引）、錯誤狀態；目錄/定位補遮擋級斷言（
toBeVisible不判遮擋）；滾動恢復斷言對 clamp 容忍，不要求像素級絕對相等；可見瀏覽器走查並歸檔證據（截圖與最終行為一致）。
邊界
- 不改業務頁面行為、選單/路由業務值、Mock 資料；只加閱讀入口與文件資產鏈路。
- 不引入第三方重型 MD 渲染依賴；渲染器受限、可測試、可轉義。
- 不把「文件撰寫規範」寫進本技能；不把「入口實作細節」寫進文件撰寫技能。
- 真實權限、生產部署與鑑權方式以專案門禁為準；Mock/演示通過不等於生產已防護。
交付說明
入口位置與可見條件、文件來源與映射、建置複製與校驗、渲染與歷史過濾、懶載入與搜尋、錯誤狀態、生產暴露面處理、測試與走查證據、未覆蓋項。