# 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。

已驗證：

```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
- 用 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 時的輸出行為