skytek_xinliang
174 lines
4.0 KiB
Markdown
174 lines
4.0 KiB
Markdown
## HTML Transform
|
||
|
||
HTML Transform 是 prototype evidence 工具。現行 MVP 只做兩件事：
|
||
|
||
- `doctor`：檢查執行 `scan` 需要的前置條件。
|
||
- `scan`：讀取 HTML prototype，產生瀏覽器證據與頁面級 UI Contract。
|
||
- `app-map.json`：推論每個 prototype 的頁面角色與 layout 使用策略。
|
||
|
||
不提供 `plan`、`run`、`diff`、`verify`、`go`、`status`。這些舊骨架已移除，避免把尚未完成的自動化流程誤認成可用功能。
|
||
|
||
## MVP 範圍
|
||
|
||
`scan` 會執行：
|
||
|
||
```text
|
||
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` 目錄內：
|
||
|
||
```bash
|
||
node src/cli.js doctor
|
||
node src/cli.js scan
|
||
```
|
||
|
||
在 repo 根目錄：
|
||
|
||
```bash
|
||
node packages/html-transform/src/cli.js doctor
|
||
node packages/html-transform/src/cli.js scan
|
||
```
|
||
|
||
若要在根目錄用簡短指令，建議由根目錄 `package.json` 包一層：
|
||
|
||
```json
|
||
{
|
||
"scripts": {
|
||
"scan": "node packages/html-transform/src/cli.js doctor && node packages/html-transform/src/cli.js scan"
|
||
}
|
||
}
|
||
```
|
||
|
||
之後即可執行：
|
||
|
||
```bash
|
||
pnpm scan
|
||
```
|
||
|
||
## 前置需求
|
||
|
||
需要 Node.js 20 以上。
|
||
|
||
```bash
|
||
node --version
|
||
pnpm --version
|
||
```
|
||
|
||
安裝相依套件：
|
||
|
||
```bash
|
||
pnpm install
|
||
```
|
||
|
||
確認 `playwright-cli` 可用：
|
||
|
||
```bash
|
||
pnpm --filter html-transform exec playwright-cli --version
|
||
```
|
||
|
||
若環境還沒有 Chromium：
|
||
|
||
```bash
|
||
pnpm --filter html-transform exec playwright-cli install-browser chromium
|
||
```
|
||
|
||
## 設定檔
|
||
|
||
沒有設定檔時，預設讀取：
|
||
|
||
```text
|
||
packages/prototype/
|
||
```
|
||
|
||
本 repo 根目錄目前使用：
|
||
|
||
```js
|
||
export default {
|
||
prototype: './prototype',
|
||
frontend: './apps/frontend/hwu-re',
|
||
backend: './apps/backend',
|
||
output: './output',
|
||
plan: {
|
||
interactiveReview: false
|
||
}
|
||
}
|
||
```
|
||
|
||
目前 MVP 只使用 `prototype`。其他欄位可以留著給外部工作流參考，但 `packages/html-transform` 不會執行 frontend/backend/output 相關步驟。
|
||
|
||
## Doctor
|
||
|
||
```bash
|
||
node packages/html-transform/src/cli.js doctor
|
||
```
|
||
|
||
檢查項目：
|
||
|
||
- `prototype` directory
|
||
- package-local `vite`
|
||
- `playwright-cli`
|
||
- `pnpm`
|
||
|
||
## Scan
|
||
|
||
```bash
|
||
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 是否明顯衝突。
|
||
- 產出 `.ht/app-map.json`，供通用 prompt 判斷 auth、legacy shell、feature page 與 layout 策略。
|
||
|
||
## 產物
|
||
|
||
每個 HTML 的 capture artifact：
|
||
|
||
```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
|
||
```
|
||
|
||
每個 HTML 的 contract artifact：
|
||
|
||
```text
|
||
.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 只提供內容與功能證據。
|
||
|
||
## 驗證
|
||
|
||
修改本 package 後至少執行：
|
||
|
||
```bash
|
||
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
|
||
```
|