html-transform/README.md

HTML Transform

HTML Transform 是 prototype evidence 工具。現行 MVP 只做兩件事：

• doctor：檢查執行 scan 需要的前置條件。
• scan：讀取 HTML prototype，產生瀏覽器證據與頁面級 UI Contract。
• app-map.json：推論每個 prototype 的頁面角色與 layout 使用策略，並用 prototype/*.md 的人工 domain guide 輔助補上舊系統對照。

不提供 plan、run、diff、verify、go、status。這些舊骨架已移除，避免把尚未完成的自動化流程誤認成可用功能。

MVP 範圍

scan 會執行：

Stage 1 Capture
Stage 3-lite Page Contract
Stage 4-lite Contract Validation

Stage 2 decomposition 不執行。現有 prototype 主要是後台系統頁面，重點是表單、查詢條件、表格、actions 與資訊架構；切 region screenshot 對 MVP 價值不高。

目前沒有 Codex slash command。也就是說，在 repo 根目錄輸入 /scan 不會自動執行本工具。

指令

在 packages/html-transform 目錄內：

node src/cli.js doctor
node src/cli.js scan

在 repo 根目錄：

node packages/html-transform/src/cli.js doctor
node packages/html-transform/src/cli.js scan

若要在根目錄用簡短指令，建議由根目錄 package.json 包一層：

{
  "scripts": {
    "scan": "node packages/html-transform/src/cli.js doctor && node packages/html-transform/src/cli.js scan"
  }
}

之後即可執行：

pnpm scan

前置需求

需要 Node.js 20 以上。

node --version
pnpm --version

安裝相依套件：

pnpm install

確認 playwright-cli 可用：

pnpm --filter html-transform exec playwright-cli --version

若環境還沒有 Chromium：

pnpm --filter html-transform exec playwright-cli install-browser chromium

設定檔

設定檔不是工具執行的絕對必要條件；沒有設定檔時，工具會使用內建預設並讀取：

packages/prototype/

本 repo 的 HTML prototype 位於根目錄 ./prototype，不是 ./packages/prototype。因此從 repo 根目錄執行 node packages/html-transform/src/cli.js scan 時，需要根目錄 ht.config.mjs 覆寫 prototype 路徑。

本 repo 根目錄目前使用最小設定：

export default {
  prototype: './prototype'
}

目前 MVP 只使用 prototype。scan 會讀取其中的 HTML prototype，也會讀取 prototype/*.md 作為 app-map 的輔助 domain guide。frontend、backend、output、plan 等欄位不會被 doctor 或 scan 使用，不需要為本 MVP 加入設定檔。

Doctor

node packages/html-transform/src/cli.js doctor

檢查項目：

• prototype directory
• package-local vite
• playwright-cli
• pnpm

Scan

node packages/html-transform/src/cli.js scan

scan 會自動：

• 用 Vite static server 提供 prototype。
• 用 playwright-cli 開啟每個 HTML。
• 等待 networkidle，再等待 500ms。
• 截取 desktop 1440 x 900 full-page screenshot。
• 產生 DOM summary。
• 產生 accessibility snapshot。
• 記錄 resource failure 與 console error/warning。
• 建立頁面級 pageContract。
• 驗證 contract 與 DOM evidence 是否明顯衝突。
• 讀取 prototype/*.md 的對照表，擷取 prototype 檔、舊 JSP、舊 PB、對應 Vue view 或功能描述。
• 產出 .ht/app-map.json，供通用 prompt 判斷 auth、legacy shell、feature page、layout 策略與舊系統對照。

產物

每個 HTML 的 capture artifact：

.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

每個 HTML 的 contract artifact：

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

.spec.json 會包含 pageContract。regions 欄位目前仍保留，目的是相容既有資料形狀；不要把它視為 Stage 2 decomposition。

.ht/app-map.json 是跨頁面的應用結構推論。通用 prompt 應先讀它，再決定每個 prototype 是 auth、legacy-shell-reference、feature-page 或其他角色。MVP 固定策略是 template layout/style 優先，prototype 只提供內容與功能證據。

若 prototype/*.md 內有 markdown table 對照 prototype HTML，例如 venue/query-room.html，scan 會把匹配結果寫進 route：

{
  "prototype": "venue/query-room.html",
  "guide": {
    "source": "venue.md",
    "legacyJsp": "zte_pro/zte451_02.jsp + zte451_02_1.jsp",
    "legacyPb": "n_zte451.of_zte451_02 / of_zte451_02_1",
    "targetView": "RoomQueryView.vue",
    "description": null
  },
  "evidence": {
    "prototypeGuide": "venue.md"
  }
}

這些 guide 欄位只輔助 route 與舊系統對照理解；HTML capture、DOM summary、UI contract 與 screenshot 仍是畫面內容的主要 evidence。

驗證

修改本 package 後至少執行：

pnpm --filter html-transform typecheck
pnpm --filter html-transform test
node packages/html-transform/src/cli.js doctor
node packages/html-transform/src/cli.js scan