pessimistcamellia/proto-note

原型變更標註層（proto-note）

在單一檔案 HTML 原型上疊加「研發視角變更導覽」：右側固定深色備註欄（模組勾選 + 備註卡）↔ 頁面編號錨點 + canvas 連線；雙向懸停/點擊定位；備註卡附帶 SDD 深層連結。

安裝與目錄

# 個人 skill（推薦）
git clone https://github.com/pessimistcamellia/proto-note.git ~/.cursor/skills/proto-note

# 或專案內
git clone https://github.com/pessimistcamellia/proto-note.git .cursor/skills/proto-note

也可將整個目錄複製到上述路徑。目錄結構：

proto-note/
├── SKILL.md
├── assets/diff-annotator.js      # 標註引擎（整段內聯到原型，請勿修改邏輯）
├── references/changeset-schema.md
├── docs/screenshots/             # README 效果圖
└── scripts/deploy_github.sh      # GitHub Pages 備選部署

環境依賴

能力	工具	缺失時
技術棧/原始碼定位	codewiki MCP（或等價程式碼檢索）	使用線上 URL + 原始碼倉庫 + 瀏覽器 DOM 還原
SDD 深層連結	lark-cli（飛書）	手動填寫文件 URL 與章節 blockId；非飛書則連結到對應章節錨點
像素級校準	瀏覽器 DevTools / chrome-devtools MCP	手動開啟線上頁面對照
部署	內網靜態託管（優先）	個人 GitHub Pages（deploy_github.sh，需 gh 授權）

團隊若另有前端規範 skill（如選型白名單、元件庫用法），製作前請按需讀取；如果沒有，則以目標倉庫原始碼與團隊文件為準。

預設方案：元件庫與發佈優先級

按優先級執行；前一級不可用時才落到下一級，最後一級為預設備援：

1. 元件庫 / 規範（優先）：使用目標線上系統真實在用的元件庫與元件規範（對照原始碼 / DOM / 團隊規範 skill），禁止無依據更換元件庫。
2. 發佈地址（優先）：有內網現成靜態託管（或團隊約定的內網地址）時，優先發佈到內網。
3. 預設備援：若無法取得真實元件庫/規範，或因權限、網路、內網不可達等原因無法使用 → 元件可按通用方案自選（仍保持單檔案可互動 HTML）；發佈到使用者個人 GitHub 倉庫（Pages）。部署前須確認 gh 授權，未授權請先與使用者溝通，禁止未經同意推送私人倉庫。

產品鐵律

1. 變更三級 + 類型：頁面 / 模組 / 欄位；類型需區分新增、文案、枚舉口徑、邏輯、流程、刪除，禁止籠統標註為「新增」。
2. 預設隱藏、模組勾選：開啟時不顯示標註；按 page::module 勾選；狀態存於 localStorage。新增模組的缺失 key 預設為 true（可見），禁止使用「曾關過任一開關」來繼承隱藏；髒狀態需靠升級 LS_KEY 版本清除。
3. 只連動 SDD，不展示 PRD：備註卡使用 SDD文檔URL#blockId。
4. 資訊精簡：備註欄無版本號/基線/操作說明；desc 只寫結論。
5. 可點必有效：勾選模組即切換視圖 + 滾動 + 脈衝定位。
6. 評審態只在備註欄：正常/空態/錯誤態等放在 demoControls；真實業務 Tab 留在業務頁。
7. 輸入分支給可複現範例：examples 需與 fixture 一致，禁止佔位假值。
8. 備註欄不擋內容：不壓縮業務佈局；靠 spacer 擴展 scrollWidth，水平滾動可看全右側。禁止只加 body padding-right 或修改業務根寬度。
9. 元件庫與規範優先真實線上：能還原則必須還原（見「預設方案」第 1 級）。使用同款元件庫不等於還原——骨架、列集/列寬、凍結列、儲存格結構、操作列佈局、自訂類名與關鍵樣式須對照線上 DOM/原始碼；交付前應逐畫面截圖比對。僅在無法取得真實元件庫/規範時，才允許使用通用元件備援。
10. 發佈優先內網，否則個人 GitHub：有內網地址優先使用；不可用時發佈至個人 GitHub Pages（見「預設方案」第 2–3 級）。
11. 「前」= 線上現狀：新增時寫「無此頁面/模組/功能/欄位」；禁止寫成相對於上一版 demo 的差異；線上新增點不得漏標。
12. 無 UI 落點不連線：純流程/鏈路 target: null，無錨點；卡片放入「流程與鏈路 · 頁面不可見」，且排在 changes 末尾。
13. 彈窗內變更：點擊備註卡須經 DIFF_HOOKS.locate 開啟彈窗再連線；錨點/連線的 z-index 應高於彈窗（引擎使用 9000 段）。
14. 彈窗隨頁面橫縱滾動：備註欄開啟時，彈窗容器隨 (-scrollX,-scrollY) 平移（引擎已處理）；禁止鎖死滾動來回避問題。
15. 可下載物需為真實格式：模板/回執需與真實業務同格式同結構（如雙 sheet 需真 .xlsx），禁止使用 CSV 冒充。
16. 多端分別製作並連動：營運後台、C 端等按系統邊界分別製作 HTML；統一選單標明「端 · 頁面」；有跨頁資料則模擬寫入/讀取/啟停/異常。
17. 備註卡必須可跳轉 SDD：有 SDD 時每條變更（或所在功能點）需配置 sdd.section + blockId，卡片需渲染深層連結；點擊應開啟對應章節，而非只顯示章節名稱。

展示層規範（引擎已內建，請勿回退）

• 右側備註欄：深海軍藍、寬度 360px，可收起為浮動入口。
• 橫向滾動：使用 document.body.scrollWidth 測量業務寬度（spacer 為 absolute，不計入該值）；請勿先隱藏 spacer 再測量。恢復滾動使用 behavior:"instant"，避免與 scroll-behavior:smooth 衝突。
• 錨點：文檔座標 position:absolute，釘在目標左上角；禁止使用 fixed+滾動追幀；遮擋時使用 elementFromPoint 隱藏。
• 連線：平時無連線；懸停/固定時只畫一條；固定態優先於懸停態；起點取即時 rect。
• 備註卡：編號 + 標題 + 類型·層級 + 結論 + 前/後 + SDD；可包含 examples。
• 展示區：備註欄頂部的 segmented control → DIFF_HOOKS.setDemoState。

技術棧還原（Step 0）

依「預設方案」執行：能還原則還原；不能則記錄原因後進行自由選型備援。

1. 使用者未提供線上 URL → 先提醒；仍無則自行檢索系統/路由/原始碼。
2. 使用 codewiki（或原始碼檢索）確認：框架、元件庫、路由→頁面檔案、關鍵模板片段；必要時檢查索引新鮮度，並用線上 DOM 校準。
3. 優先使用目標倉庫真實元件庫與規範；新增控制項應沿用該頁既有的類型/尺寸/排列。使用同款元件庫不等於還原——骨架、列集/列寬、凍結列、儲存格結構、操作列佈局、自訂類名須對照線上 DOM/原始碼。
4. 若有團隊規範 skill 則遵循；否則跟隨目標倉庫與文件。
5. 當像素級或檢索不足時：開啟線上頁面抓取掛載方式、元件類名、表格列寬/凍結列、操作列結構、自訂 computed style。
6. 產出仍為單一檔案 HTML；能從 CDN 引入同款框架/元件庫則引入。整頁無法還原時，自由選用常見元件庫完成可互動原型，並在交付說明中註明「未還原原因」。
7. 發佈：有內網靜態地址則優先上傳；否則在取得使用者 GitHub 授權後使用 deploy_github.sh 發佈至個人倉庫。

高頻陷阱：請勿為外層設定超寬 min-width 撐死表格（會丟失內部橫向滾動與 fixed 列）；統一選單頂欄使用 position:fixed，避免寬頁橫向滾動時頂欄斷開。

多頁面 / 多端與資料連動

1. 先列出矩陣：端/系統 → 頁面 → 關鍵狀態 → 上下游資料；不同技術棧分開檔案，不強行合併。
2. 統一選單：命名為「端 · 頁面」，當前頁高亮；選單不做變更備註。
3. 同源同目錄部署，確保 localStorage 共享。
4. 共享狀態 key：proto-note:<requirement-slug>:state:v1；讀寫後在同頁派發事件，跨標籤監聽 storage。
5. URL 只攜帶業務 ID；正文放在共享狀態。非同源優先改為同源，否則使用 postMessage 並校驗 origin。
6. 內建 fixture +「重設展示資料」；上下游狀態與異常皆可複現。

工作流程

0. Step 0 技術棧還原。
1. 從 PRD 提取變更清單、端/頁面矩陣、輸入分支與跨頁資料關係 → 參見 references/changeset-schema.md。
2. 取得 SDD blockId，寫入每條 sdd。
3. 按端製作原型；多端需配置選單與共享狀態並驗證連動。
4. 接入標註層：
   • 容器加上 data-diff-page；落點補上 id；實作 DIFF_HOOKS.locate / setDemoState。
   • 評審 Tab 移入 meta.demoControls。
   • 分支寫入 examples（需與 fixture 一致）。
   • 在 </body> 前內聯 DIFF_CHANGESET，再整段複製最新版 assets/diff-annotator.js（請勿沿用過期拷貝）。
5. 部署與自我檢查：

   • 優先內網：有現成內網靜態託管則上傳；若物件鍵不覆蓋則更換新路徑（如 -v2），以返回 URL + md5 為準。

   • 備援 GitHub Pages：內網不可用時發佈至個人倉庫。先執行 gh auth status；無權限則溝通並完成 gh auth login，禁止未經授權推送私人倉庫：

     bash ~/.cursor/skills/proto-note/scripts/deploy_github.sh <slug> ./index.html
     

自我檢查清單

• 能還原時已使用線上真實元件庫/規範；不能還原時已註明原因並進行自由選型備援
• 發佈優先內網；內網不可用時已取得授權後發佈至個人 GitHub
• 與線上逐畫面比對（若有線上頁面：列寬、凍結列、操作列、分頁、頂欄）
• 初始無錨點/連線；模組未勾選；新增模組對舊訪客預設可見
• 勾選模組僅顯示對應的卡/錨點/線，並自動定位；彈窗內變更可自動開窗且線在彈窗之上
• 滾動無錨點偏移；平時無連線，固定/懸停僅一條線；固定態不會被 hover 搶走
• 備註欄開啟時可橫向滾動看全右側；橫向滾動位置不因 DOM 更新彈回；彈窗隨底頁橫縱滾動
• target:null 無錨點，卡片在「流程與鏈路」且靠後；「前」均為線上現狀、無漏標
• 備註卡 SDD 深層連結可開啟並定位到對應章節
• 展示態只在備註欄；examples 可複現；下載物格式正確
• 多端選單可達；跨原型讀寫/刷新/跨標籤/重設一致
• 收起備註欄時乾淨整潔；業務互動不受影響

參考

• 本倉庫 README.md（效果截圖、Live demo、預設方案說明）
• Live demo：https://pessimistcamellia.github.io/non-ecommerce-thirdparty-order-prototype/admin-upload.html