feat: 增進 app-map

README.md

@@ -4,7 +4,7 @@ HTML Transform 是 prototype evidence 工具。現行 MVP 只做兩件事：
 
 - `doctor`：檢查執行 `scan` 需要的前置條件。
 - `scan`：讀取 HTML prototype，產生瀏覽器證據與頁面級 UI Contract。
-- `app-map.json`：推論每個 prototype 的頁面角色與 layout 使用策略。
+- `app-map.json`：推論每個 prototype 的頁面角色與 layout 使用策略，並用 `prototype/*.md` 的人工 domain guide 輔助補上舊系統對照。
 
 不提供 `plan`、`run`、`diff`、`verify`、`go`、`status`。這些舊骨架已移除，避免把尚未完成的自動化流程誤認成可用功能。
 
@@ -83,27 +83,23 @@ pnpm --filter html-transform exec playwright-cli install-browser chromium
 
 ## 設定檔
 
-沒有設定檔時，預設讀取：
+設定檔不是工具執行的絕對必要條件；沒有設定檔時，工具會使用內建預設並讀取：
 
 ```text
 packages/prototype/
 ```
 
-本 repo 根目錄目前使用：
+本 repo 的 HTML prototype 位於根目錄 `./prototype`，不是 `./packages/prototype`。因此從 repo 根目錄執行 `node packages/html-transform/src/cli.js scan` 時，需要根目錄 `ht.config.mjs` 覆寫 `prototype` 路徑。
+
+本 repo 根目錄目前使用最小設定：
 
 ```js
 export default {
-  prototype: './prototype',
-  frontend: './apps/frontend/hwu-re',
-  backend: './apps/backend',
-  output: './output',
-  plan: {
-    interactiveReview: false
-  }
+  prototype: './prototype'
 }
 ```
 
-目前 MVP 只使用 `prototype`。其他欄位可以留著給外部工作流參考，但 `packages/html-transform` 不會執行 frontend/backend/output 相關步驟。
+目前 MVP 只使用 `prototype`。`scan` 會讀取其中的 HTML prototype，也會讀取 `prototype/*.md` 作為 app-map 的輔助 domain guide。`frontend`、`backend`、`output`、`plan` 等欄位不會被 `doctor` 或 `scan` 使用，不需要為本 MVP 加入設定檔。
 
 ## Doctor
 
@@ -135,7 +131,8 @@ node packages/html-transform/src/cli.js scan
 - 記錄 resource failure 與 console error/warning。
 - 建立頁面級 `pageContract`。
 - 驗證 contract 與 DOM evidence 是否明顯衝突。
-- 產出 `.ht/app-map.json`，供通用 prompt 判斷 auth、legacy shell、feature page 與 layout 策略。
+- 讀取 `prototype/*.md` 的對照表，擷取 prototype 檔、舊 JSP、舊 PB、對應 Vue view 或功能描述。
+- 產出 `.ht/app-map.json`，供通用 prompt 判斷 auth、legacy shell、feature page、layout 策略與舊系統對照。
 
 ## 產物
 
@@ -161,6 +158,26 @@ node packages/html-transform/src/cli.js scan
 
 `.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：
+
+```json
+{
+  "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 後至少執行：