feat: 參考backend

2026-05-12 11:03:46 +08:00
parent 10843227a8
commit 58a5a525d7
9 changed files with 1488 additions and 69 deletions
@@ -1,54 +1,173 @@
 # TODO

-## Improve `.ht` Layout Evidence
+## 目前狀態

-Current `scan` evidence is useful for finding page structure, labels, inputs, buttons, tables, screenshots, and app-map hints, but it is still too weak as an implementation constraint for visual layout.
+`html-transform scan` 已從單純 prototype evidence，推進到可輸出 Page Implementation Contract 的第一版。

-Observed problem:
+已完成：

- Generated Vue/Vuetify pages can preserve fields, buttons, routes, and APIs while drifting far from prototype layout.
- Reports may pass pages because functional elements exist, even when form density, alignment, spacing, table structure, and first-screen information density are wrong.
- `desktop-default.png` contains this evidence visually, but the generated JSON/Markdown artifacts do not expose enough layout metrics for deterministic checks.
+- 強化 prototype form/table/action 萃取。
+  - 支援 legacy table-form 的 `<th>/<td>` 欄位 label 推論。
+  - 欄位輸出包含 `label`、`name`、`type`、`required`、`readonly`、`maxLength`、`options`、`defaultValue`、`sourceTable`、`sourceRow`。
+  - action 會輸出 `actionType` 與 `scope`，例如 `search`、`save`、`edit`、`delete`、`print`、`back`、`formAction`、`rowAction`。
+  - table 會輸出 `role`，例如 `searchTable`、`resultTable`、`detailTable`、`printTable`、`layoutTable`。
+- 解析 `prototype/*.md` guide。
+  - 保留 `legacyJsp`、`legacyPb`、`targetView`、`description`。
+  - 解析各 prototype 段落 checklist，寫入 route guide 與 page spec。
+- 解析 backend API 文件。
+  - 從 `apps/backend/API.md` 解析 endpoint index。
+  - 從 `apps/backend/API_Manual.md` 解析 method/path、request/response JSON、field rules、notes、ProblemDetails examples。
+  - 輸出 `.ht/api-catalog.json`。
+- 建立 prototype-to-api matching。
+  - 依 prototype path/module、guide、title/text/actions 與 endpoint path/description tokens 做通用匹配。
+  - 不針對 Venue 寫死規則；Venue 只是目前驗證案例。
+- 產出維護頁 `maintenanceContract`。
+  - 輸出 `pageKind`、`capabilities`、`recommendedTemplate`、`confidence`、`reasons`、`warnings`、`dataModel`。
+  - 可初步分辨 `maintenance`、`query`、`application`、`print`、`chooser`、`layout-reference`。
+- 更新 `.ui-contract.md`。
+  - 加入 page kind、recommended template、capabilities、primary entity、target view、legacy source、prototype checklist、API endpoints。
+- 補測試。
+  - 使用 generic `orders` domain 測試 API catalog、API matching 與 maintenance template 推論，避免只驗證 Venue。

-Future work:
+已驗證：

- Capture bounding boxes for important visible elements:
+```bash
+pnpm --filter html-transform test
+pnpm --filter html-transform run typecheck
+node packages/html-transform/src/cli.js scan
+```
+
+目前 Venue prototype 重新 scan 後的分類：
+
+```text
+applications-list.html  maintenance  single-record
+apply-choose.html       chooser       none
+apply-facility.html     application   master-detail-c
+apply-room-print.html   print         none
+apply-room.html         application   master-detail-c
+query-choose.html       chooser       none
+query-facility.html     query         none
+query-room.html         query         none
+```
+
+## 目標
+
+讓 `html-transform scan` 產出的 `.ht/` artifact 不只描述 prototype 畫面，也能結合 backend API 文件與維護頁範本規則，形成可穩定交給 LLM 生成 Vue/Vuetify 頁面的實作契約。
+
+核心輸出：
+
+- prototype 提供畫面結構、欄位文案、表格、按鈕與舊流程線索。
+- backend API docs 提供 endpoint、request/response DTO、欄位規則、狀態碼與錯誤格式。
+- template guide 或 maint README 提供專案層的頁面範本選擇規則。
+- `.ht/app-map.json`、`.ht/api-catalog.json`、`.ht/spec/{page}.spec.json`、`.ht/spec/{page}.ui-contract.md` 說明頁面型態、資料模型、API 對應、建議範本與信心理由。
+
+## 待辦
+
+### 1. Layout Evidence
+
+目前 `scan` evidence 可以找出頁面結構、labels、inputs、buttons、tables、screenshots 與 app-map hints。`GEN-FE-PROMPT.md` 的 UI 實作規則要求 feature page 使用現代 Vuetify 承載 prototype 的功能與資訊架構，不逐像素複刻舊 HTML/JSP，但仍要保留資訊密度、區塊順序、欄位行列對齊與主要操作流。
+
+待補強：
+
+- 擷取重要可見元素 bounding boxes：
  - headings
  - labels
  - inputs/selects/textareas
  - buttons/links
  - tables
  - section containers
- Group form fields into likely rows and columns using bounding boxes.
- Detect table/list layout:
-  - table count
-  - table order
-  - header labels
-  - whether multiple tables are stacked vertically
- Capture first-viewport density:
+- 用 bounding boxes 將表單欄位分群成可能的 rows / columns。
+- 擷取 first-viewport density：
  - visible section count
  - visible form field count
  - visible table/header count
  - approximate occupied content area
- Emit layout hints into `.ht/spec/{page}.spec.json`, for example:
+- 在 `.ht/spec/{page}.spec.json` 輸出：
  - `layoutEvidence.sections`
  - `layoutEvidence.formRows`
  - `layoutEvidence.tables`
  - `layoutEvidence.primaryActions`
  - `layoutEvidence.firstViewport`
- Render layout hints into `.ht/spec/{page}.ui-contract.md` so LLMs see layout constraints without manually inferring everything from screenshots.
- Add validation warnings for likely layout-critical structures:
-  - stacked tables
-  - dense row-based forms
-  - query toolbar with adjacent submit button
-  - multi-row detail tables
+- 在 `.ht/spec/{page}.ui-contract.md` 呈現 layout hints。

-Non-goals:
+Non-goals：

- Do not require pixel-perfect HTML/JSP reproduction.
- Do not copy legacy CSS.
- Do not encode exact colors/fonts as hard constraints unless needed for functional recognition.
+- 不要求 pixel-perfect HTML/JSP reproduction。
+- 不複製 legacy CSS。
+- 除非是功能辨識必要，不把精確 colors/fonts 編成硬限制。

-Goal:
+### 2. API Matching 品質

- Preserve information architecture, form density, field alignment, table/list relationships, and operation flow while still allowing a modern Vue/Vuetify implementation.
+目前 API matching 是通用 token scoring，已可用，但仍偏粗。
+
+待補強：
+
+- 降低同 module 但不同 page 的誤配風險。
+- 把 guide 的 `targetView`、JSP/PB method、prototype path 與 endpoint path 做更細的權重拆分。
+- 將 matched endpoints 分成用途：
+  - `lookup`
+  - `search`
+  - `detail`
+  - `create`
+  - `update`
+  - `delete`
+  - `print`
+  - `customAction`
+- 在 `apiContract` 裡輸出 rejected candidates 與 rejection reason，方便檢查錯配。
+
+### 3. Maintenance Contract 精準度
+
+目前 `maintenanceContract` 已能初步推薦範本，但仍是 heuristic。
+
+待補強：
+
+- 加入 row action rule：
+  - 從 prototype checklist、button disabled、API notes 推論 `enabledWhen`。
+  - 例如 `aprvYn === 'Z'` 才能 edit/delete。
+- 更精準拆出：
+  - `searchFields`
+  - `formFields`
+  - `tableColumns`
+  - `detailCollections`
+  - `rowActions`
+- 將 `recommendedTemplate` 與特定前端專案範本解耦。
+  - 通用輸出保留 `single-record`、`master-detail-c` 等抽象 template id。
+  - 專案若有自己的 README 或 guide，再由 prompt 對應到實際檔案。
+- 加 validation warnings：
+  - `maintenance` 頁缺少 search/table/action。
+  - 有 `edit/delete` action 但沒有對應 API endpoint。
+  - request schema 有欄位但 prototype 找不到對應欄位。
+  - prototype 有欄位但 API schema 找不到對應欄位。
+  - row action 有狀態限制但未產出 `enabledWhen`。
+
+### 4. Backend Docs 通用性
+
+目前 backend docs 預設讀 `./apps/backend`，且 parser 針對 markdown heading、table、code fence 做通用解析。
+
+待補強：
+
+- 允許 config 指定多個 backend docs 來源。
+- 支援 OpenAPI JSON/YAML 作為輸入來源。
+- 支援沒有 `API.md` index、只有 manual 的情境。
+- 支援不同語言的章節標籤，例如 `Request body`、`Response body`、`Validation`。
+
+### 5. UI Contract Markdown
+
+目前 `.ui-contract.md` 已加入主要 contract 摘要。
+
+待補強：
+
+- 輸出 field rules 與 schema 摘要。
+- 輸出 row action rules。
+- 輸出 layout evidence。
+- 對 `recommendedTemplate: none` 的頁面明確標示原因，例如 chooser/query/print/layout-reference。
+
+### 6. 文件與範例
+
+待補強：
+
+- 加一個最小 fixture，示範非 Venue domain 如何產出 api catalog 與 maintenance contract。
+- 在 README 補充 config 範例：
+  - 只指定 `prototype`
+  - 同時指定 `prototype` 與 `backendDocs`
+  - 沒有 backend docs 時的輸出行為