# 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`：
```js
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 策略 |
產出：
```text
.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 |
產出：
```text
.ht/spec/{page}.spec.json
.ht/spec/{page}.ui-contract.md
```
`.spec.json` 目前仍保留 `regions` 欄位作為相容層，但它不是 MVP 的主要設計中心。
---
## 6.1 App Structure Map
目的：讓通用 prompt 不必靠人工說明，就能知道每個 prototype 應如何放進前端 app。
產出：
```text
.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 |
產出：
```text
.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。
這些能力只有在實際需求明確出現後才新增。