skt-vuetify-templates/src/GUIDE.md

Src Guide

src 是 template 使用者主要修改的區域。新增功能時，先從 route view 與 composable 開始，除非需求明確牽涉 app shell、登入、router guard 或 HTTP core，否則不要先改 template core。

資料流

router -> AppShell -> layout -> view -> Section -> Item
                          ↓
             composable -> store -> service

主要目錄

• views/：route entry，維持薄層，只做 route wiring 與 page driver 掛載。詳見 src/views/GUIDE.md。
• components/：Vue UI 元件，依 sections / items / layouts / base 分層。詳見 src/components/GUIDE.md。
• composables/：page driver、command flow、layout flow 與可重用狀態流程。詳見 src/composables/GUIDE.md。
• router/：route、layout meta、auth meta 與 guard。詳見 src/router/GUIDE.md。
• shell/：AppShell、tabs、global overlays。詳見 src/shell/GUIDE.md。
• stores/：跨頁共享狀態與快取。詳見 src/stores/GUIDE.md。
• services/：HTTP client、API module、token/session、錯誤處理。詳見 src/services/GUIDE.md。
• language/：Vue I18n 文案。詳見 src/language/GUIDE.md。

Template Core

一般功能需求預設不修改：

• main.ts
• App.vue
• shell/*
• components/layouts/*
• views/Login.vue
• router/index.ts
• router/guards.ts
• plugins/*
• styles/*
• services/client.ts
• services/interceptors.ts
• services/token.ts
• services/session.ts
• stores/auth.ts
• stores/menu.ts
• stores/breadcrumbs.ts
• stores/favorites.ts
• stores/messages.ts
• stores/snackbar.ts
• stores/app.ts
• composables/layout/*

只有需求明確要求調整 template shell、登入、router guard、HTTP core 或全域狀態時才修改上述檔案。

Demo / Example

下列檔案偏向示範功能，正式專案可依需求替換或移除：

• views/Home.vue
• views/FncPage.vue
• views/Settings.vue
• views/maint/*
• components/maint/MaintShell.vue
• components/maint/*
• components/sections/*
• components/items/*
• composables/page-drivers/*MaintenancePage.ts
• composables/maint/*
• composables/useCrudCommands.ts
• stores/students.ts
• stores/semesters.ts
• demo assets 與 demo language keys

移除 demo 時，同步清理 route、menu/favorites/breadcrumb 流程、語系文案與不再使用的 import。

新功能流程

1. 新增或修改 views/* route entry，直接在 view 裡組裝 page model 與 UI。
2. 若有複雜的資料協調（多 composable、搜尋狀態、CRUD flow、dialog 狀態），新增 composables/page-drivers/useXxxPage.ts。簡單頁面直接在 view 用 computed 組裝。
3. 若畫面有獨立區塊，拆到 components/sections/*。
4. 若區塊內有欄位群組或單筆資料呈現，拆到 components/items/*。
5. 跨頁共享狀態才新增或修改 stores/*。
6. 外部 API 放在 services/modules/*。
7. 在 router/routes.ts 新增 route。

驗證

• Vue / TypeScript 結構變更：pnpm -s type-check
• 需要確認產物：pnpm -s build
• route、layout 或主要畫面流程變更：啟動 dev server 並做瀏覽器檢查，除非使用者明確不需要。