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。

環境變數（.env 檔案）

Vite 會依 mode 自動載入對應層級的 .env 檔案，優先順序由高到低：

.env.[mode].local     ← 本機覆蓋，不提交（最高優先）
.env.[mode]           ← mode 專用
.env.local            ← 本機覆蓋，不提交
.env                  ← 所有 mode 通用

專案實際使用與版本控制規則：

檔案	用途	Git
.env.example	範本檔，列出所有可用變數與說明	提交
.env	所有 Vite 指令皆載入（serve / build）	忽略
.env.development	vite serve（mode=development）載入	忽略
.env.development.local	本機開發機密值（帳號密碼等）	忽略
.env.production	vite build（mode=production）載入	忽略

新增環境變數時應遵守的順序：

1. 在 .env 或 .env.development 中新增變數並給定預設值
2. 在 .env.example 中加入該變數的說明與格式，供其他開發者參考
3. 若變數包含機密資訊（帳號、密碼、token），僅放在 .env.development.local，不要寫入 .env.example 的預設值

現有變數說明：

變數	適用檔案	說明
VITE_PROXY_TARGET	.env, .env.development, .env.development.local	dev server proxy 目標後端 URL
VITE_API_BASE_URL	.env, .env.development, .env.production	API 請求 base URL，dev 用相對路徑走 proxy，prod 用完整 URL
VITE_SKIP_LOGIN	.env.development	登入示範開關，true 時略過登入流程
VITE_DEV_DEFAULT_USER_ID	.env.development.local	本機開發示範帳號
VITE_DEV_DEFAULT_PASSWORD	.env.development.local	本機開發示範密碼

修改前檢查

• 是否碰到 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 並用瀏覽器確認，除非使用者明確不需要。

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