# Product Requirement Document
## HTML Transform

| 欄位 | 內容 |
|------|------|
| 版本 | v0.1 |
| 日期 | 2026-05-02 |
| 狀態 | Draft |

---

## 1. 背景與目標

HTML Transform 是一個安裝在 pnpm-workspace / monorepo 中的 prototype-driven orchestration framework。它讓工程師指定四個資料夾，由單一 coding agent 依序驅動完整 pipeline，將 HTML prototype 轉換為可運作、可維護的 Vuetify 前端實作，並用 backend API schema 對齊資料流。

**四個資料夾：**

| 識別子 | 說明 |
|--------|------|
| `prototype` | HTML prototype 來源 |
| `frontend` | 已預先建立的 Vuetify 前端專案 |
| `backend` | 已預先建立的 backend API 專案 |
| `output` | 生成結果的寫入目標 |

**核心設計原則：** pipeline 的每個 stage 都產出可被人工 review 的 artifact，agent 的不確定性由結構化中間產物吸收，而非在最終輸出才暴露。HTML prototype 不是完整規格；rendered browser evidence、DOM/accessibility snapshot、`LayoutSpec`、project conventions、API contract、`TaskList` 才共同構成實作依據。

**成功標準：**
- 相同 prototype 執行兩次，`output` 資料夾的結果語意一致
- Diff report 的平均 similarity score 高於 75%
- `LayoutSpec` 的 `null` 欄位比率低於 30%
- Stage 7 的 quality gates（typecheck、lint、test、route smoke test）全部通過，或明確標示為環境缺失而非實作失敗
- 每次 run 都能回溯到對應的 screenshot、DOM snapshot、spec、plan、agent raw output 與 verification report

---

## 2. 系統架構

```
ht.config.ts
     │
     ▼
┌─────────────────────────────────────────────────────┐
│                   Orchestrator                      │
│  （讀取 config，依序呼叫各 stage，傳遞中間產物）         │
└──────┬──────────┬──────────┬──────────┬─────────────┘
       │          │          │          │
       ▼          ▼          ▼          ▼
   [Stage 1]  [Stage 2]  [Stage 3]  [Stage 4]
    Capture    Decompose   Extract    Validate
       │          │          │          │
       └──────────┴──────────┴──────────┘
                       │
                  LayoutSpec
                       │
              ┌────────┴────────┐
              ▼                 ▼
          [Stage 5]         [Stage 6]
            Plan               Run
          TaskList         coding agent
                               │
                          output/
                               │
                          [Stage 7]
                         Diff & Verify
                    reports + quality gates
```

**Agent 角色：** 單一 coding agent（由 `ht.config.ts` 中的 `agent` 欄位指定，支援 claude-code、codex、gemini）全程驅動所有 stage，包含 vision 截圖分析、spec 提取、程式碼實作、diff 評分。Orchestrator 負責呼叫順序與中間產物的序列化，agent 負責每個 stage 的實際執行。

---

## 3. 設定檔

```typescript
// ht.config.ts
import { defineConfig } from 'html-transform'

export default defineConfig({
  prototype: './packages/prototype',
  frontend:  './packages/web',
  backend:   './packages/api',
  output:    './packages/result',

  agent: 'claude-code',   // 'claude-code' | 'codex' | 'gemini'

  vision: {
    viewport: { width: 1440, height: 900 },
    captureStates: ['default', 'scrolled', 'mobile'],
    includeDomSnapshot: true,
    includeAccessibilityTree: true,
  },

  project: {
    packageManager: 'pnpm',
    frontendFramework: 'vue3',
    uiLibrary: 'vuetify3',
    qualityCommands: {
      typecheck: 'pnpm typecheck',
      lint: 'pnpm lint',
      test: 'pnpm test',
    },
  },

  plan: {
    interactiveReview: true,   // Stage 5 完成後暫停，等待人工確認 TaskList
    requireApiContractMatch: true,
  },

  diff: {
    scoreThreshold: 75,        // 低於此分數的 region 在 report 中標示警告
    requireDomChecks: true,
    requireFlowChecks: true,
  },
})
```

---

## 4. Pipeline 詳細需求

### Stage 1：Capture

**目的：** 產出 prototype 的視覺真相，取代 agent 腦補的渲染結果。

| 需求 ID | 說明 |
|---------|------|
| F1-1 | 對每個 `.html` 檔案，以 desktop（1440×900）、tablet（768×1024）、mobile（375×812）各截一張全頁截圖 |
| F1-2 | 以本地 static server 提供 prototype 檔案，避免 `file://` 協定的 CORS 問題 |
| F1-3 | 截圖前等待 `networkidle`，再額外等待 500ms，確保 CSS animation 穩定 |
| F1-4 | 以原始 `.html` 檔案的 SHA-256 hash 作為 cache key；hash 未變動時跳過截圖 |
| F1-5 | 截圖儲存至 `.ht/cache/prototype/{filename}/{viewport}-{state}.png` |
| F1-6 | 對每個 viewport/state 產出 DOM summary 與 accessibility tree snapshot，作為 Stage 2–5 的非視覺 evidence |
| F1-7 | 記錄外部資源載入失敗清單（font、image、script、stylesheet），寫入 capture metadata |

**產出物：** `.ht/cache/prototype/` 下的截圖、DOM snapshot、accessibility snapshot 與 capture metadata

---

### Stage 2：Decompose

**目的：** 識別頁面的主要區域，為 Stage 3 的局部提取做準備。直接對整頁截圖做一次性提取，精度低且不穩定；分區後再提取可大幅降低錯誤率。

| 需求 ID | 說明 |
|---------|------|
| F2-1 | 以 desktop 截圖呼叫 agent（vision 模式），識別頁面主要區域 |
| F2-2 | 回傳 JSON array，每個 item 包含 `id`、`name`、`rough_position`、`element_count_estimate`、`semantic_role` |
| F2-3 | 依據 `rough_position`，用 Playwright `clip` 截取每個 region 的局部截圖 |
| F2-4 | Prompt 明確要求只回 JSON，不附任何說明文字 |
| F2-5 | 使用 Stage 1 的 DOM summary 與 accessibility tree 輔助確認 region 名稱、可互動元素與文字，不只依賴截圖 |

**產出物：** `PageDecomposition` JSON（含各 region 的局部截圖路徑）

---

### Stage 3：Extract

**目的：** 從每個 region 截圖提取結構化的 `LayoutSpec`。

| 需求 ID | 說明 |
|---------|------|
| F3-1 | 每個 region 獨立呼叫 agent，輸入該 region 的局部截圖 |
| F3-2 | Prompt 以填空題形式提供 `LayoutSpec` JSON 結構，要求 agent 填值而非自由生成 |
| F3-3 | `vuetifyComponent` 必須是 Vuetify 3 的真實 component 名稱（對照白名單驗證） |
| F3-4 | 不確定的欄位填 `null`，Prompt 明確禁止猜測 |
| F3-5 | `colorPalette` 只填截圖中實際出現的色碼（hex 或 rgba） |
| F3-6 | `textSamples` 填截圖中可見的真實文字，最多 3 筆 |
| F3-7 | 對表單、列表、表格、導覽與 action button 產出 `uiContract` 欄位，描述 label、field type、required 狀態、主要/次要 action、可觀察互動 |
| F3-8 | 若 DOM/accessibility evidence 與 vision 判讀衝突，保留 `warnings`，不得任意合併成確定結論 |

**產出物：** 每個 region 的 `RegionSpec` JSON

---

### Stage 4：Validate

**目的：** 確保 `LayoutSpec` 符合 schema，自動修復可修復的問題，標記需要人工介入的頁面。

| 需求 ID | 說明 |
|---------|------|
| F4-1 | 以 Zod schema 驗證每個 region 的 extract 結果 |
| F4-2 | `vuetifyComponent` 不合法時，查 Vuetify 3 白名單找最相近的名稱並自動修正 |
| F4-3 | 色碼格式不合法時，嘗試 normalize；無法修正時填 `null` |
| F4-4 | 產出 `ValidationReport`，記錄 `autoFixedCount`、`nullFieldCount`、`warnings` |
| F4-5 | `nullFieldCount` 超過 30% 時，將該頁標記為 `requiresHumanReview: true`，並在 CLI 輸出警告 |
| F4-6 | 語意驗證 region 數量、文字樣本、主要 action、表單欄位與 DOM/accessibility evidence 是否一致 |
| F4-7 | 產出人工可讀的 `ui-contract.md` 摘要，讓使用者可在實作前 review prototype contract |

**產出物：** 完整的 `LayoutSpec` JSON（儲存至 `.ht/spec/{filename}.spec.json`）+ `ValidationReport` + `ui-contract.md`

---

### Stage 5：Plan

**目的：** 將 `LayoutSpec` 拆解為 agent 可逐一執行的 `TaskList`，讓 Stage 6 的執行單元保持小而可控。

| 需求 ID | 說明 |
|---------|------|
| F5-1 | 讀取 `LayoutSpec`、`frontend/` 的現有元件、`backend/` 的 API schema，產出 `TaskList` |
| F5-2 | 每個 Task 對應一個 page 或 component，包含：`id`、`type`、`targetFile`、`specReference`、`apiDependencies` |
| F5-3 | Task 之間的依賴關係以 `dependsOn` 陣列表示，Orchestrator 依此決定執行順序 |
| F5-4 | `ht.config.ts` 中 `plan.interactiveReview: true` 時，產出 TaskList 後暫停，輸出預覽並等待使用者輸入 `y` 繼續 |
| F5-5 | `TaskList` 儲存至 `.ht/plan/tasklist.json`，支援手動編輯後重新執行 Stage 6 |
| F5-6 | 掃描 `frontend/` 產出 `project-conventions.md`，至少包含 routing、Vuetify 使用方式、表單封裝、API client/composable、Pinia、validation、i18n、測試慣例 |
| F5-7 | 掃描 `backend/` 產出 `api-contract.md`；若存在 OpenAPI 優先使用，否則從 TypeScript interface、controller、route 或 markdown 抽象 endpoint contract |
| F5-8 | 產出 `component-mapping.json`，描述 prototype region/section 對應 Vuetify component 或既有自訂 wrapper 的映射 |
| F5-9 | `plan.requireApiContractMatch: true` 時，Task 不得引用 `api-contract.md` 未列出的 endpoint；缺口須產出 `contractProposal` 並標記需人工確認 |

**TaskList 結構（摘要）：**

```typescript
interface Task {
  id: string
  type: 'page' | 'component' | 'api-integration'
  targetFile: string           // 相對於 output/ 的路徑
  specReference: string        // 對應 LayoutSpec 的 regionId
  apiDependencies: string[]    // backend API endpoint 清單
  inputArtifacts: string[]     // spec、contract、conventions、mapping 等 artifact 路徑
  acceptanceChecks: string[]   // 此 task 完成後必須通過的檢查
  dependsOn: string[]          // 其他 task id
  status: 'pending' | 'running' | 'done' | 'error'
}
```

**產出物：** `.ht/plan/tasklist.json`、`.ht/plan/project-conventions.md`、`.ht/plan/api-contract.md`、`.ht/plan/component-mapping.json`

---

### Stage 6：Run

**目的：** 讓 coding agent 依序執行 TaskList，將 Vuetify 元件與 API 整合寫入 `output/`。

| 需求 ID | 說明 |
|---------|------|
| F6-1 | Orchestrator 依 `dependsOn` 拓撲排序，逐一將 task 交給 agent 執行 |
| F6-2 | 每個 task 的 prompt context 包含：對應的 `RegionSpec`、`ui-contract.md` 摘要、`project-conventions.md`、`component-mapping.json`、`targetFile` 的現有內容（若存在）、相關 API contract |
| F6-3 | Agent 的輸出直接寫入 `output/{targetFile}`；寫入前備份至 `.ht/backup/` |
| F6-4 | Task 執行失敗時標記 `status: 'error'`，記錄錯誤訊息，繼續執行無依賴的後續 task |
| F6-5 | 支援 `ht run --retry-failed` 指令，只重新執行 `status: 'error'` 的 task |
| F6-6 | 每個 task 完成後更新 `.ht/plan/tasklist.json` 的 `status` 欄位 |
| F6-7 | Agent invocation 必須限制 `allowedPaths`，預設只能寫入 `output/` 與 `.ht/`；不得修改 `prototype/`、`frontend/`、`backend/` 原始輸入資料夾 |
| F6-8 | 每次 agent raw output、changed files、exit code、stderr/stdout summary 寫入 `.ht/runs/{runId}/agent/` |

**產出物：** `output/` 資料夾中的 Vuetify 元件與整合程式碼

---

### Stage 7：Diff & Verify

**目的：** 量化 `output/` 的結果與 prototype 的視覺相似度，並以 deterministic checks 優先驗證實作品質，讓工程師能快速判斷生成結果是否可交付。

| 需求 ID | 說明 |
|---------|------|
| F7-1 | 對 `output/` 中每個頁面以相同 viewport 截圖 |
| F7-2 | 將 output 截圖與 Stage 1 的 prototype 截圖交給 agent 評分（0–100），判斷視覺相似度 |
| F7-3 | 產出靜態 HTML report，每行並排顯示：prototype 截圖、output 截圖、similarity score |
| F7-4 | Score 低於 `ht.config.ts` 中 `diff.scoreThreshold`（預設 75）的項目以警告色標示 |
| F7-5 | Report 儲存至 `.ht/diff/{filename}.diff.html`，執行完畢後在 CLI 輸出 report 路徑 |
| F7-6 | 執行 `project.qualityCommands` 中設定的 typecheck、lint、test；缺少指令時記錄為 `skipped` 並說明原因 |
| F7-7 | 執行 DOM-level checks：主要文字、form label、table/list item、primary/secondary action 是否存在且可互動 |
| F7-8 | 執行 flow-level checks：可由 `LayoutSpec.interactions` 推導的 drawer、tab、modal、form submit、navigation 等互動 smoke test |
| F7-9 | 採 deterministic first, agent fallback second：固定檢查失敗時才呼叫 agent 協助分析原因，不讓 agent 取代可重跑驗證 |
| F7-10 | 產出 `VerificationReport`，彙整 quality commands、DOM checks、flow checks、visual diff 與人工需處理項目 |

**產出物：** `.ht/diff/` 下的靜態 HTML report + `.ht/verify/verification-report.json`

---

## 5. CLI 指令設計

| 指令 | 說明 |
|------|------|
| `ht scan` | 執行 Stage 1–4（Capture → Validate），產出 `LayoutSpec` |
| `ht plan` | 執行 Stage 5，產出 `TaskList`；`interactiveReview: true` 時暫停等待確認 |
| `ht run` | 執行 Stage 6，依 `TaskList` 驅動 agent 寫入 `output/` |
| `ht run --retry-failed` | 只重新執行 `status: 'error'` 的 task |
| `ht diff` | 執行 Stage 7 的 visual diff，產出 similarity report |
| `ht verify` | 執行 Stage 7 的 quality commands、DOM checks 與 flow checks |
| `ht go` | 依序執行全部 stage（scan → plan → run → diff → verify） |
| `ht status` | 顯示目前 `TaskList` 的執行狀態摘要 |
| `ht doctor` | 檢查 pnpm workspace、Playwright、agent CLI、Vuetify component whitelist、quality commands 是否可用 |

---

## 6. 資料夾結構

```
monorepo/
├── ht.config.ts
├── packages/
│   ├── prototype/       ← 輸入：HTML prototype
│   ├── web/             ← 輸入：Vuetify 前端專案（預先建立）
│   ├── api/             ← 輸入：Backend API（預先建立）
│   └── result/          ← 輸出：生成結果
└── .ht/                 ← 工具產出的所有中間產物與 cache
    ├── cache/prototype/ ← Stage 1 截圖
    ├── spec/            ← Stage 4 LayoutSpec JSON
    ├── plan/            ← Stage 5 TaskList JSON
    ├── runs/            ← 每次 run 的狀態、log、agent raw output、artifact 索引
    ├── backup/          ← Stage 6 寫入前的備份
    ├── verify/          ← Stage 7 verification report
    └── diff/            ← Stage 7 similarity report
```

**Run artifact 結構：**

```
.ht/runs/
└── 2026-05-02-001/
    ├── run.json
    ├── screenshots/
    ├── dom-snapshots/
    ├── agent/
    ├── logs/
    └── artifact-index.json
```

---

## 7. 非功能需求

| 類別 | 需求 |
|------|------|
| 效能 | 單一 HTML 頁面的 Stage 1–4 完整執行不超過 60 秒 |
| 可復現性 | Cache 命中時跳過截圖與 extract，相同輸入產出相同結果 |
| 可觀測性 | 每個 stage 完成後輸出 log，記錄耗時、agent call 次數、cache 命中狀態 |
| 錯誤隔離 | 單一 task 或 region 失敗不中斷整體流程，標記後繼續執行 |
| 可介入性 | `TaskList` 支援手動編輯；`interactiveReview` 模式允許人工在 Plan 後介入 |
| 可追溯性 | 每個輸出檔案都能追溯到 input artifact、agent invocation、task id 與 run id |
| 邊界控制 | Agent 預設只可寫入 `output/` 與 `.ht/`，所有輸入資料夾視為 read-only |

---

## 8. 風險與假設

| 風險 | 程度 | 緩解策略 |
|------|------|---------|
| Vision 分析精度不足，`null` 欄位過多 | 高 | Spike 驗證後調整 prompt；人工補充 spec |
| Prototype 引用外部資源，截圖不完整 | 中 | Local static server + `networkidle` 等待 |
| Agent 生成的程式碼不符合既有前端專案的規範 | 中 | Prompt context 包含現有元件與 coding style；task 單元保持小 |
| Backend API 不足以支援 prototype 行為 | 中 | Stage 5 產出 `contractProposal` 並要求人工確認，不讓 agent 自行發明 endpoint |
| 只靠 screenshot similarity 造成假陽性 | 中 | Stage 7 加入 DOM-level、flow-level 與 project quality checks |
| Vuetify component 白名單不完整，自動修正失敗 | 低 | 預先整理 Vuetify 3 全量 component 清單 |

**核心假設：**
- Prototype 在現代瀏覽器中能正確渲染
- `frontend/` 專案已有基本的 Vuetify 3 設定與 project structure
- `backend/` 專案有可讀的 API schema（OpenAPI 或 TypeScript interface）
- 第一版 MVP 聚焦單一 HTML prototype → 單一 Vue page/component → 既有 API client → `output/` 結果，不追求一開始支援所有 monorepo 形態

---

## 9. 開發里程碑

| 里程碑 | 涵蓋 Stage | 完成條件 |
|--------|-----------|---------|
| M0：Spike | Stage 1–3（手動） | 手動截圖 + 手動 prompt，驗證 `null` 欄位 < 30% |
| M1：Vision Pipeline | Stage 1–4 | `ht scan` 可對一個 HTML 頁面產出完整 `LayoutSpec`、DOM snapshot 與 `ui-contract.md` |
| M2：Plan | Stage 5 | `ht plan` 可產出 `TaskList`、`project-conventions.md`、`api-contract.md`、`component-mapping.json`，interactive review 可運作 |
| M3：Run | Stage 6 | `ht run` 可驅動 agent 對一個頁面完整執行並寫入 `output/` |
| M4：Diff & Verify | Stage 7 | `ht diff` 可產出 similarity report，`ht verify` 可執行 quality、DOM、flow checks |
| M5：整合 | 全部 | `ht go` 全流程可在真實 monorepo 中穩定執行 |