html-transform/PRD.md

Product Requirement Document

HTML Transform

欄位	內容
版本	v0.3
日期	2026-05-04
狀態	MVP

---

1. 背景與目標

HTML Transform 是 prototype evidence 工具。它的目標不是完整自動化前端生成，而是把 HTML prototype 轉成可 review、可追溯、可交給 coding agent 實作的前置證據。

目前 MVP 只保留有實際價值的功能：

• 檢查 scan 前置條件。
• 用真實瀏覽器擷取 prototype evidence。
• 推論跨頁面的 App Structure Map。
• 產生頁面級 UI Contract。
• 驗證 UI Contract 與 DOM evidence 是否明顯衝突。

不保留未完成的 pipeline 骨架。plan、run、diff、verify、go、status 已不屬於目前產品面。

---

2. CLI Scope

指令	說明
ht doctor	檢查 scan 所需環境
ht scan	產生 browser evidence、page contract、validation report

沒有 Codex slash command。根目錄輸入 /scan 不會自動執行本工具。

---

3. 設定檔

MVP 只使用 prototype：

export default {
  prototype: './prototype'
}

本 repo 的根目錄設定檔可以保留其他欄位給外部工作流參考，但 packages/html-transform 不會執行 frontend/backend/output 相關流程。

---

4. Stage 1：Capture

目的：取得 prototype 的瀏覽器真相，避免只看 HTML source 或讓 agent 腦補畫面。

需求：

ID	說明
F1-1	對每個 .html 檔案截取 desktop 1440 x 900 full-page screenshot
F1-2	使用本地 Vite static server，不使用 file://
F1-3	截圖前等待 networkidle，再等待 500ms
F1-4	以 HTML SHA-256 hash 作為 cache key，未變更時跳過重新截圖
F1-5	截圖寫入 .ht/cache/prototype/{page}/desktop-default.png
F1-6	產出 dom-summary.json 與 accessibility-tree.json
F1-7	產出 capture-metadata.json，記錄 resource failure 與 console error/warning
F1-8	產出 .ht/app-map.json，推論頁面角色與 layout 策略

產出：

.ht/cache/prototype/{page}/desktop-default.png
.ht/cache/prototype/{page}/dom-summary.json
.ht/cache/prototype/{page}/accessibility-tree.json
.ht/cache/prototype/{page}/capture-metadata.json
.ht/app-map.json

---

5. Stage 2：Decompose

MVP 不執行。

不做的項目：

• 不呼叫 vision agent 切主要區域。
• 不產生 decomposition.json。
• 不用 Playwright clip 截取 table/form/main 等局部圖。
• 不建立 region-first extraction pipeline。

---

6. Stage 3-lite：Page Contract

目的：從 Stage 1 evidence 與 HTML source 產生頁面級 UI Contract。

需求：

ID	說明
F3-1	每個 HTML 產出一份 pageContract
F3-2	pageContract 以整頁為單位，不以 region screenshot 為單位
F3-3	記錄 source、screenshot、title、sections、forms、tables、actions、textSamples
F3-4	建議 Vuetify components 必須來自 MVP 白名單
F3-5	forms 記錄 labels、fields、required 狀態與 actions
F3-6	tables 記錄 headers 與少量 sample rows
F3-7	不確定或 evidence 對不上時保留 warnings

產出：

.ht/spec/{page}.spec.json
.ht/spec/{page}.ui-contract.md

.spec.json 目前仍保留 regions 欄位作為相容層，但它不是 MVP 的主要設計中心。

---

6.1 App Structure Map

目的：讓通用 prompt 不必靠人工說明，就能知道每個 prototype 應如何放進前端 app。

產出：

.ht/app-map.json

每個 route 應包含：

欄位	說明
prototype	prototype 相對路徑
kind	auth、auth-support、legacy-shell-reference、prototype-navigation、feature-page 或 reference
module	由資料夾推論的功能模組
targetRole	對前端實作的角色提示
layout	template-auth、template-app 或 ignore
usePrototypeStyle	MVP 固定為 false
usePrototypeContent	是否採用 prototype 的內容資訊架構
routeHint	可用的路由建議，無正式頁面時為 null

推論規則：

• password input 或登入/忘記密碼文字：auth。
• portal/app-layout.html、portal/menu-pane.html、portal/index.html 或含登出/隱藏選單：legacy-shell-reference。
• 非 portal 且有 table/form/action：feature-page。
• module index 若像 prototype 導覽頁：prototype-navigation。
• layout 與 login style 來源固定為 preparation/skt-vuetify-templates。

---

7. Stage 4-lite：Validate Contract

目的：確認 UI Contract 與 browser evidence 沒有明顯衝突。

需求：

ID	說明
F4-1	驗證 textSamples 是否可在 DOM summary 找到
F4-2	驗證 actions 是否可在 DOM summary 找到
F4-3	驗證 form labels 是否可在 DOM summary 找到
F4-4	驗證建議 Vuetify components 是否在白名單內
F4-5	產出 ValidationReport，包含 warnings、nullFieldCount、nullFieldRatio、requiresHumanReview

產出：

.ht/spec/{page}.validation.json

---

8. 非目標

MVP 不追求：

• tablet/mobile 多 viewport capture。
• region decomposition。
• 每個 region 獨立 vision extraction。
• TaskList 產生。
• 自動寫入 frontend/output。
• visual similarity scoring。
• flow smoke test。
• 全自動 coding agent invocation。

這些能力只有在實際需求明確出現後才新增。