skytek_xinliang
174 lines
6.8 KiB
Markdown
174 lines
6.8 KiB
Markdown
# 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 時的輸出行為
|