skt-vuetify-templates/docs/llm-development-guide.md

LLM 開發操作指南

文件目的

本專案是給其他 Vue/Vuetify 專案使用的 template。LLM 協助修改時，預設應在 src 底下依分層規則新增或修改頁面、元件、store、service 與 composable。

本文件只保留全域操作順序與導覽。各層細節規範放在 src/**/GUIDE.md，避免重複維護。

建議閱讀順序

1. src/GUIDE.md
2. docs/architecture-strategy.md
3. 依 maintenanceContract.pageKind 閱讀對應的 src/**/GUIDE.md（查 src/GUIDE.md 中的「依 pageKind 選擇起點」表格）
4. docs/add-page-example.md（需要新增頁面時）

frontend-layering.md 是歷史參考，後續以 docs/architecture-strategy.md 與 src/**/GUIDE.md 為準。

GUIDE 索引

範圍	指南
src 總覽、資料流、template core、demo 邊界	src/GUIDE.md
route view 與薄 view 規則	src/views/GUIDE.md
maintenance demo view	src/views/maint/GUIDE.md
Vue component 分層	src/components/GUIDE.md
base 元件	src/components/base/GUIDE.md
section 元件	src/components/sections/GUIDE.md
layout 邊界	src/components/layouts/GUIDE.md
page driver、command、layout composable	src/composables/GUIDE.md
route 與 guard	src/router/GUIDE.md
AppShell、tabs、global overlays	src/shell/GUIDE.md
Pinia store	src/stores/GUIDE.md
HTTP service / ky / API module	src/services/GUIDE.md
domain model 與 page model 型別	src/models/GUIDE.md
跨模組共用 API 型別	src/types/GUIDE.md
i18n 文案	src/language/GUIDE.md

預設修改策略

一般功能需求優先修改：

• src/views/*
• src/components/pages/*
• src/components/sections/*
• src/components/items/*
• src/composables/page-drivers/*
• src/composables/commands/*
• src/stores/*
• src/services/modules/*
• src/router/routes.ts
• src/language/*.json

除非使用者明確要求，避免先修改 template core。template core 清單與 demo/example 邊界見 src/GUIDE.md。

常用判斷

• 新 route：讀 src/router/GUIDE.md。
• 一般頁面：讀 src/views/GUIDE.md、src/components/GUIDE.md、src/composables/GUIDE.md。
• 維護頁：讀 src/views/maint/GUIDE.md。
• 查詢/列表頁（篩選 + 表格）：讀 src/components/sections/GUIDE.md（SectionQueryPage）。
• 申請/填寫頁（送出按鈕）：讀 src/components/sections/GUIDE.md（SectionFormPage）。
• layout / AppShell / tabs / global overlay：讀 src/shell/GUIDE.md 與 src/components/layouts/GUIDE.md。
• API 串接：讀 src/services/GUIDE.md。
• 跨頁共享狀態：讀 src/stores/GUIDE.md。
• 定義 page model 或 domain model 型別：讀 src/models/GUIDE.md。
• 共用 API 型別定義：讀 src/types/GUIDE.md。
• 錯誤頁：讀 src/views/GUIDE.md（ErrorShell 模式）與 src/router/GUIDE.md（錯誤頁路由慣例）。
• 語系文案：讀 src/language/GUIDE.md。

修改前檢查

• 是否碰到 template core。
• 是否已有同類型範例可沿用。
• 是否需要新增 route。
• 是否應拆成 page / section / item。
• 是否應新增 page driver 或 command composable。
• 是否需要 store，或只需要頁面內 state。
• 是否應定義新的 model 型別（src/models/）。
• 是否需要更新語系、menu、breadcrumb、favorites。

從視覺特徵選擇 section 元件

當收到 prototype 截圖或設計稿時，依畫面特徵選擇 section 外殼：

特徵	選擇
有「送出/存檔」按鈕，且畫面為填寫表單（欄位 + 配合事項 + 動作按鈕）	SectionFormPage
有「查詢」按鈕，且畫面為篩選條件 + 結果表格/列表	SectionQueryPage
純粹表格列表（無送出/查詢按鈕，只有 CRUD 操作）	不用 section 外殼，直接組合 v-data-table
混合結構（有查詢也有表單填寫）	評估是否拆成兩頁；若必須同頁，不用通用外殼

判斷順序：先看有無「送出/存檔」→ 再看有無「查詢」→ 其餘視為一般列表頁。

.spec.json 對照指南

當 LLM 依照 GEN-FE-PROMPT 讀取 .ht/spec/{page}.spec.json 後，依 maintenanceContract.pageKind 決定對應的 demo 與 composable 界面，再將 .spec.json 的 evidence 欄位對應到 composable 的 reactive state、computed 與 API calls。

query（查詢頁）→ SectionQueryPage

參考：src/views/demos/SectionQueryPageDemo.vue、src/components/pages/PageSectionQueryPageDemo.vue、src/composables/page-drivers/useSectionsDemoPage.ts

架構：

View (薄層) → composable (page driver) → PageSectionQueryPageDemo → SectionQueryPage

composable 必須回傳：

名稱	型別	對應 .spec.json 來源
queryFilters	Ref<{ 每個欄位 }>	pageContract.forms[0].fields — 每個 field 建一個 key，型別依 field.type（text→string, select→string | null，選項取自 field.options）
pageModel	ComputedRef<{ title, ... }>	title 來自 pageContract.title；backLabel 固定為 '返回'
handleQuerySearch()	函式	觸發 apiContract.endpoints 中 usage=search 的 API call；呼叫時機對應 bddContract.scenarios 中 type=query 的 When
handleQueryBack()	函式	對應 pageContract.actions 中 actionType=back
表格資料	在 pageModel 中	tables[].headers 對應表格欄；sampleRows 對應欄位格式

page component props：

• v-model:query-filters — 雙向綁定 queryFilters
• :page — 傳入 pageModel

page component emits：

• @search → 呼叫 handleQuerySearch
• @back → 呼叫 handleQueryBack

application（申請/表單頁）→ SectionFormPage

參考：src/views/demos/SectionFormPageDemo.vue、src/components/pages/PageSectionFormPageDemo.vue

架構：

View (薄層) → composable (page driver) → PageSectionFormPageDemo → SectionFormPage

composable 必須回傳：

名稱	型別	對應 .spec.json 來源
demoForm（應改名為 formState）	Ref<{ 每個欄位 }>	pageContract.forms[0].fields — text/select 建 key；不可編輯的 readonly 欄位不放進 formState，改從 pageModel 單向顯示
pageModel	ComputedRef	title 來自 pageContract.title
handleFormSubmit()	函式	觸發 apiContract.endpoints 中 usage=create 的 POST endpoint；呼叫前驗證 apiCatalog.fieldRules；呼叫時機對應 bddContract.scenarios 中 type=application-submit 的 When/Then
resetDemoForm()（改為 resetForm）	函式	對應 pageContract.actions 中 actionType=reset
handleFormBack()	函式	對應 actionType=back

提交 payload 規則：

• apiCatalog.fieldRules 中的 field 與 rule 決定必填、長度、格式驗證
• 型別轉換依 field.type：number 欄位不可包成 string 送出

page component emits：

• @submit → 呼叫 handleFormSubmit
• @reset → 呼叫 resetForm
• @back → 呼叫 handleFormBack

maintenance（維護/CRUD 頁）→ maint/*

參考：src/views/maint/README.md — 依資料結構選擇最接近的範本（EditableGrid / SingleRecord / MasterDetail A/B/C）

composable 必須回傳：

名稱	對應 .spec.json 來源
search filters	pageContract.forms[0].fields
table data / headers	pageContract.tables[].headers + search API response
row action handlers	maintenanceContract.rowActions — 每個 action 對應一個 handler；enabledWhen 決定啟用條件（如 aprvYn === 'Z' 時才能修改）
create/update/delete calls	apiContract.endpoints 中對應的 POST/PUT/DELETE

row action 狀態規則：

• enabledWhen 直接轉為 template 中的 :disabled 或 v-if 條件
• maintenanceContract.businessRules 中的額外限制一併套用

通用規則

entity 命名： 所有 composable、component、store 的名稱以 maintenanceContract.dataModel.primaryEntity 為 entity 名，例如 primaryEntity=FacilityApply → useFacilityApplyPage.ts → PageFacilityApply.vue。

API 串接： 在 src/services/modules/ 新增對應 entity 的 API module，method 名稱對齊 apiContract.endpoints[].usage（search/create/update/delete/print），path 對齊 endpoint.path。

錯誤處理： 檢查 apiContract.errorHandling.format — 若為 ProblemDetailsWithValidationErrors，須處理 errors 物件中的逐欄錯誤訊息；若為 ProblemDetails，只顯示 detail。

語系文案： 欄位 label 與按鈕文字取自 pageContract.forms[].fields[].label 和 pageContract.actions[].label，放入 src/language/ 對應語系 key。

完成前驗證

• Vue / TypeScript 結構有變更：pnpm -s type-check
• 需要確認產物可建置：pnpm -s build
• Markdown 或大量搬移：git diff --check
• route、layout 或主要畫面流程有變更：啟動 dev server 並用瀏覽器確認，除非使用者明確不需要。

如果無法執行驗證，回報原因，不要宣稱已驗證。