feat: 參考backend
This commit is contained in:
skytek_xinliang
@@ -3,8 +3,8 @@
|
||||
HTML Transform 是 prototype evidence 工具。現行 MVP 只做兩件事：
|
||||
|
||||
- `doctor`：檢查執行 `scan` 需要的前置條件。
|
||||
- `scan`：讀取 HTML prototype，產生瀏覽器證據與頁面級 UI Contract。
|
||||
- `app-map.json`：推論每個 prototype 的頁面角色與 layout 使用策略，並用 `prototype/*.md` 的人工 domain guide 輔助補上舊系統對照。
|
||||
- `scan`：讀取 HTML prototype、prototype guide 與 backend API docs，產生瀏覽器證據、頁面級 UI Contract 與 implementation contract。
|
||||
- `app-map.json`：推論每個 prototype 的頁面角色、layout 使用策略、API 對應、維護頁建議範本，並用 `prototype/*.md` 的人工 domain guide 輔助補上舊系統對照。
|
||||
|
||||
不提供 `plan`、`run`、`diff`、`verify`、`go`、`status`。這些舊骨架已移除，避免把尚未完成的自動化流程誤認成可用功能。
|
||||
|
||||
@@ -16,6 +16,8 @@ HTML Transform 是 prototype evidence 工具。現行 MVP 只做兩件事：
|
||||
Stage 1 Capture
|
||||
Stage 3-lite Page Contract
|
||||
Stage 4-lite Contract Validation
|
||||
API Catalog
|
||||
Maintenance Contract
|
||||
```
|
||||
|
||||
Stage 2 decomposition 不執行。現有 prototype 主要是後台系統頁面，重點是表單、查詢條件、表格、actions 與資訊架構；切 region screenshot 對 MVP 價值不高。
|
||||
@@ -69,6 +71,8 @@ pnpm --version
|
||||
pnpm install
|
||||
```
|
||||
|
||||
[playwright](https://playwright.dev/agent-cli/installation)
|
||||
|
||||
確認 `playwright-cli` 可用：
|
||||
|
||||
```bash
|
||||
@@ -95,11 +99,44 @@ packages/prototype/
|
||||
|
||||
```js
|
||||
export default {
|
||||
prototype: './prototype'
|
||||
}
|
||||
prototype: "./prototype",
|
||||
};
|
||||
```
|
||||
|
||||
目前 MVP 只使用 `prototype`。`scan` 會讀取其中的 HTML prototype，也會讀取 `prototype/*.md` 作為 app-map 的輔助 domain guide。`frontend`、`backend`、`output`、`plan` 等欄位不會被 `doctor` 或 `scan` 使用，不需要為本 MVP 加入設定檔。
|
||||
`scan` 目前使用：
|
||||
|
||||
- `prototype`：HTML prototype 與 `prototype/*.md` domain guide 來源。
|
||||
- `backendDocs`：backend API markdown / OpenAPI JSON/YAML docs 來源，預設 `./apps/backend`。
|
||||
|
||||
本 repo 的 `backendDocs` 使用預設值即可。若其他專案的 backend docs 不在 `./apps/backend`，可明確指定：
|
||||
|
||||
```js
|
||||
export default {
|
||||
prototype: "./prototype",
|
||||
backendDocs: "./docs/backend",
|
||||
};
|
||||
```
|
||||
|
||||
若要同時讀取多個 backend docs 來源，或混用 markdown 與 OpenAPI JSON/YAML，可使用陣列：
|
||||
|
||||
```js
|
||||
export default {
|
||||
prototype: "./prototype",
|
||||
backendDocs: ["./apps/backend", "./docs/openapi"],
|
||||
};
|
||||
```
|
||||
|
||||
若只有 prototype、沒有 backend docs，可只指定 prototype：
|
||||
|
||||
```js
|
||||
export default {
|
||||
prototype: "./prototype",
|
||||
};
|
||||
```
|
||||
|
||||
若 `backendDocs` 目錄不存在或沒有 markdown/OpenAPI 文件，`scan` 仍會完成，只是 `.ht/api-catalog.json` 會沒有 endpoints，頁面 spec 的 `apiContract.endpoints` 也會是空陣列。
|
||||
|
||||
`frontend`、`backend`、`output`、`plan` 等欄位不會被 `doctor` 或 `scan` 使用，不需要為本 MVP 加入設定檔。
|
||||
|
||||
## Doctor
|
||||
|
||||
@@ -131,8 +168,11 @@ node packages/html-transform/src/cli.js scan
|
||||
- 記錄 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 策略與舊系統對照。
|
||||
- 讀取 `prototype/*.md` 的對照表與 checklist，擷取 prototype 檔、舊 JSP、舊 PB、對應 Vue view、功能描述與人工 checklist。
|
||||
- 讀取 backend API markdown docs，建立 endpoint catalog、schema 摘要、欄位規則與錯誤格式。
|
||||
- 依 prototype evidence、guide 與 API catalog 建立 `apiContract`。
|
||||
- 依頁面 evidence 建立 `maintenanceContract`，推論頁面型態、操作能力與建議維護頁範本。
|
||||
- 產出 `.ht/app-map.json`，供通用 prompt 判斷 auth、legacy shell、feature page、layout 策略、API 對應與舊系統對照。
|
||||
|
||||
## 產物
|
||||
|
||||
@@ -148,16 +188,44 @@ node packages/html-transform/src/cli.js scan
|
||||
每個 HTML 的 contract artifact：
|
||||
|
||||
```text
|
||||
.ht/api-catalog.json
|
||||
.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/api-catalog.json` 是跨頁面的 backend API catalog，來源是 `backendDocs` 目錄下的 markdown 文件。它會包含：
|
||||
|
||||
- `endpoints`
|
||||
- `schemas`
|
||||
- `fieldRules`
|
||||
- `errorContract`
|
||||
|
||||
`.spec.json` 會包含：
|
||||
|
||||
- `pageContract`：頁面文字、欄位、表格、actions、layout evidence 與 Vuetify checklist。
|
||||
- `apiContract`：與該頁匹配的 API endpoints、用途分類、rejected candidates 與錯誤格式。
|
||||
- `prototypeGuide`：該 prototype 對應的人工 guide、舊 JSP/PB、target view 與 checklist。
|
||||
- `maintenanceContract`：頁面型態、capabilities、recommended template、data model 與 warnings。
|
||||
- `regions`：目前仍保留，目的是相容既有資料形狀；不要把它視為 Stage 2 decomposition。
|
||||
|
||||
`.ht/app-map.json` 是跨頁面的應用結構推論。通用 prompt 應先讀它，再決定每個 prototype 是 `auth`、`legacy-shell-reference`、`feature-page` 或其他角色。MVP 固定策略是 template layout/style 優先，prototype 只提供內容與功能證據。
|
||||
|
||||
route 也會包含 implementation hints，例如：
|
||||
|
||||
```json
|
||||
{
|
||||
"prototype": "venue/applications-list.html",
|
||||
"kind": "feature-page",
|
||||
"pageKind": "maintenance",
|
||||
"recommendedTemplate": "single-record",
|
||||
"primaryEntity": "ApplicationsList",
|
||||
"capabilities": ["back", "search", "edit", "delete", "print"],
|
||||
"apiCount": 8
|
||||
}
|
||||
```
|
||||
|
||||
若 `prototype/*.md` 內有 markdown table 對照 prototype HTML，例如 `venue/query-room.html`，`scan` 會把匹配結果寫進 route：
|
||||
|
||||
```json
|
||||
@@ -168,15 +236,37 @@ node packages/html-transform/src/cli.js scan
|
||||
"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
|
||||
"description": null,
|
||||
"checklist": []
|
||||
},
|
||||
"evidence": {
|
||||
"prototypeGuide": "venue.md"
|
||||
"prototypeGuide": "venue.md",
|
||||
"apiCount": 2,
|
||||
"recommendedTemplate": "none"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
這些 guide 欄位只輔助 route 與舊系統對照理解；HTML capture、DOM summary、UI contract 與 screenshot 仍是畫面內容的主要 evidence。
|
||||
這些 guide 欄位輔助 route、舊系統對照與 checklist 理解；HTML capture、DOM summary、UI contract 與 screenshot 仍是畫面內容的主要 evidence。API catalog 與 `apiContract` 則用來降低 endpoint、DTO 與欄位規則的猜測。
|
||||
|
||||
## 使用方式是否改變
|
||||
|
||||
CLI 使用方式沒有改，仍然是：
|
||||
|
||||
```bash
|
||||
node packages/html-transform/src/cli.js doctor
|
||||
node packages/html-transform/src/cli.js scan
|
||||
```
|
||||
|
||||
有改變的是 `scan` 的輸入與輸出：
|
||||
|
||||
- 新增可選輸入：`backendDocs`，預設 `./apps/backend`。
|
||||
- 新增輸出：`.ht/api-catalog.json`。
|
||||
- `.ht/spec/{page}.spec.json` 新增 `apiContract`、`prototypeGuide`、`maintenanceContract`。
|
||||
- `.ht/app-map.json` route 新增 `pageKind`、`recommendedTemplate`、`capabilities`、`primaryEntity`、`apiCount`。
|
||||
- `.ui-contract.md` 會顯示 page kind、recommended template、prototype checklist 與 API endpoints。
|
||||
|
||||
因此既有 `doctor` / `scan` 指令不用改；但使用 `.ht` 產物的 prompt 或下游工具，應改讀新增欄位。
|
||||
|
||||
## 驗證
|
||||
|
||||
|
||||
Reference in New Issue
Block a user