html-transform/TODO.md

TODO

目前狀態

html-transform scan 已從單純 prototype evidence，推進到可輸出 Page Implementation Contract 的第一版。

已完成：

• 強化 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。

已驗證：

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

目前 Venue prototype 重新 scan 後的分類：

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
• 用 bounding boxes 將表單欄位分群成可能的 rows / columns。
• 擷取 first-viewport density：
  • visible section count
  • visible form field count
  • visible table/header count
  • approximate occupied content area
• 在 .ht/spec/{page}.spec.json 輸出：
  • layoutEvidence.sections
  • layoutEvidence.formRows
  • layoutEvidence.tables
  • layoutEvidence.primaryActions
  • layoutEvidence.firstViewport
• 在 .ht/spec/{page}.ui-contract.md 呈現 layout hints。

Non-goals：

• 不要求 pixel-perfect HTML/JSP reproduction。
• 不複製 legacy CSS。
• 除非是功能辨識必要，不把精確 colors/fonts 編成硬限制。

2. API Matching 品質

目前 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 時的輸出行為