362 lines
18 KiB
Markdown
362 lines
18 KiB
Markdown
# 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 中穩定執行 |
|