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

LLM 開發操作指南

文件目的

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

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

建議閱讀順序

1. README.md
2. docs/architecture-strategy.md
3. src/GUIDE.md
4. 依變更範圍閱讀對應的 src/**/GUIDE.md
5. docs/add-page-example.md（需要新增頁面時）

docs/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
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。
• 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。

完成前驗證

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

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