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

LLM 開發操作指南

文件目的

本專案是給其他 Vue/Vuetify 專案使用的 template。LLM 在協助修改時，主要工作應集中在 src 底下新增或修改頁面、元件、store、service 與 composable，並讓一般頁面自然被 MainLayout 包住。

本文件描述的是後續 LLM 依照 template 修改專案時的預設操作規則，不是目前對話 session 的永久限制。若使用者明確要求修改 template shell 或登入頁入口，可依需求處理。

建議閱讀順序：

1. README.md
2. src/README.md
3. docs/add-page-example.md
4. docs/architecture-strategy.md（新增功能與重構的最高準則）
5. docs/frontend-layering.md（歷史參考，已被 architecture-strategy.md 取代）

預設不可修改的檔案

以下檔案視為 template 核心邊界。LLM 依本文件處理一般功能需求時，不應修改：

• src/components/layouts/MainLayout.vue
• src/views/Login.vue

如果一般功能需求看起來需要修改上述檔案，先停下來回報原因，並改從可修改檔案尋找解法。只有在使用者明確指定要調整 layout shell 或登入頁入口時，才可以修改。

優先修改的位置

一般功能需求應優先落在：

• src/views/*
• src/views/<feature>/*
• src/components/<feature>/*
• src/composables/<feature>/*
• src/stores/*
• src/services/*
• src/router/routes.ts
• src/language/*.json

新增頁面時，通常只需要新增 view、必要的 feature components，並在 src/router/routes.ts 加入 route。

依循 src/ 既有慣例

開始實作前，先檢查需求最接近的既有檔案，並沿用目前 src/ 的責任分工、命名方式、資料流與 import 寫法。不要另起一套資料夾結構、狀態管理方式或 API 呼叫方式。

目前主要資料流是：

router -> AppShell -> layout -> view(Page Driver) -> Page Component -> Section -> Item
                                      ↓
                         page driver / command composable -> store -> service

判斷原則：

• router 決定 route、layout meta、auth meta 與錯誤頁入口
• AppShell 組裝 layout props、全域 UI 與 layout event
• views 承接路由入口、頁面資料協調與頁面事件協調，應維持薄層
• components/pages 組裝完整頁面與 page-level slot
• components/sections 承接容器佈局，例如搜尋區、表格、dialog shell
• components/items 承接單一資料單位或欄位群組呈現
• composables/page-drivers 承接頁面資料協調與 page model 組裝
• composables/commands 承接命令式副作用流程，例如 create/edit/save/delete
• composables 其他子目錄承接可重用流程、頁面狀態機或較複雜的 UI state
• stores 承接跨頁共享狀態、快取與全域顯示狀態
• services 承接 HTTP client、API 模組、token、session 與錯誤處理

新增功能時，優先找相同類型的現有範例再修改：

• 新 route：參考 src/router/routes.ts
• 一般被主 layout 包住的頁面：參考 src/views/Home.vue、src/views/maint/EditableGrid.vue
• 登入相關 UI：參考 src/components/PageLogin.vue 與 src/components/login/*
• 維護頁：優先參考 src/views/maint/SingleRecord.vue、src/components/pages/PageMaintenance.vue、src/components/sections/*、src/components/items/*、src/composables/page-drivers/useSingleRecordMaintenancePage.ts、src/composables/commands/useCrudCommands.ts
• 舊維護頁：EditableGrid.vue、MasterDetailA/B/C.vue 尚未套用完整 Page Driver + Section + Item 分層，參考前先確認是否正在做 Phase 3 遷移。
• 維護頁範本選擇：參考 src/views/maint/README.md
• API 呼叫：參考 src/services/modules/* 與使用它們的 store/composable
• 全域提示：參考 src/stores/snackbar.ts 與 src/composables/useApiCall.ts

Template Core 與 Demo 邊界

一般功能需求應避免先修改 template core。這些檔案支撐 app shell、route/layout、登入、全域狀態與 API 基礎設施：

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

以下內容偏向 demo/example，建立正式專案時可依需求替換或刪除：

• src/views/Home.vue
• src/components/PageIndex.vue
• src/views/maint/*
• src/components/maint/*
• src/components/pages/PageMaintenance.vue
• src/components/sections/*
• src/components/items/*
• src/composables/maint/*
• src/composables/page-drivers/*
• src/composables/commands/*
• src/components/PageMaint.vue
• src/stores/students.ts
• src/stores/semesters.ts
• src/views/FncPage.vue
• src/views/Settings.vue
• src/assets/logo.png
• src/assets/logo.svg
• src/assets/robot-svgrepo-com.svg

maint 是可參考的 demo feature，不是所有新專案都必須保留的核心功能。

移除 demo/example 時，同步清理 src/router/routes.ts、相關 menu/favorites/breadcrumb 流程、語系文案、assets 與 import。

新增一般頁面的流程

1. 在 src/views 或 src/views/<feature> 新增頁面檔案。
2. 若頁面超過單一簡單畫面，將主要 UI 拆到 src/components/<feature>。
3. 若有可重用或狀態較多的流程，放到 src/composables/<feature>。
4. 若資料需要跨頁共享，才新增或修改 src/stores。
5. 在 src/router/routes.ts 新增 route。
6. 一般頁面的 route 必須使用 meta: { layout: 'default' }。

範例：

{
  path: '/reports',
  name: 'reports',
  component: () => import('@/views/reports/Reports.vue'),
  meta: { layout: 'default' },
}

使用 layout: 'default' 的頁面會由 App.vue 放進 MainLayout 的預設 slot，不需要也不可以直接 import 或包裝 MainLayout.vue。

完整範例見 docs/add-page-example.md。

何時使用 layout: 'none'

只有下列頁面應使用 meta: { layout: 'none' }：

• 登入頁
• 錯誤頁
• 維護中頁
• 明確要求不要被主框架包住的獨立頁

不要為了一般功能頁使用 layout: 'none'。

Layout 邊界

MainLayout 只負責 app shell：

• drawer
• app bar
• breadcrumb
• favorites
• toolbar actions
• 主內容 slot

頁面專屬業務流程、資料規則、表單、列表、對話框、查詢條件與 CRUD 行為都不應放進 layout。

如果頁面需要在主內容區呈現特定畫面，請修改該 route 對應的 view 或 feature component。

如果頁面需要影響 breadcrumb、favorites、menu 或 toolbar，優先使用現有 store、route meta 或 App.vue 已經提供的 layout props/event 流程，不要修改 MainLayout.vue。

Login 邊界

src/views/Login.vue 是登入頁入口。一般功能需求預設不修改這個檔案。

若需求是調整登入頁內部區塊，優先檢查並修改：

• src/components/PageLogin.vue
• src/components/login/*
• src/stores/auth.ts
• src/stores/loginAnnouncements.ts
• src/services/modules/auth.ts

若需求明確要求改變登入頁 route、guard 或登入後導向，優先檢查：

• src/router/routes.ts
• src/router/guards.ts
• src/stores/auth.ts

View 與 Component 分工

views 是路由入口，負責：

• 接 route params/query
• 組合頁面資料
• 串接 store、service、composable
• 管理頁面專屬事件
• 組裝頁面主 component

components/<feature> 負責：

• 呈現頁面區塊
• 接 props
• emit 使用者事件
• 拆分表單、列表、工具列、dialog 等 UI

不要把完整功能長期塞在單一 view。當畫面有多個區塊、表單、列表、dialog 或重複 UI 時，應拆到 page / section / item components。

維護頁分層優先順序：

1. views/maint/*.vue：只做 route-level wiring，目標 < 80 行。
2. components/pages/PageMaintenance.vue：組裝維護頁外殼與主要 slot。
3. components/sections/*：管理搜尋、表格、dialog shell 等區塊佈局。
4. components/items/*：管理欄位群組或單一資料呈現，不直接呼叫 store/service。
5. composables/page-drivers/*：集中 page model、分頁、搜尋、表單狀態與事件 wiring。
6. composables/commands/*：集中新增、載入、儲存、刪除等 command 流程。

Router 安排規則

route 集中放在 src/router/routes.ts。不要在 view 或 component 裡臨時建立 route 設定。

一般 route 應包含：

• path
• name
• component
• meta.layout

需要登入才可進入的頁面使用既有 requiresAuth meta。訪客專用頁面使用既有 guestOnly meta。導航守衛流程放在 src/router/guards.ts，不要散落在頁面 component。

Composable 使用規則

只有在邏輯有下列特性時才新增 composable：

• 會被多個元件使用
• 狀態流程明顯
• 有副作用或非簡單 UI 邏輯
• 從 component 抽出後可讓 component 責任更清楚

目前既有 composable 的使用定位：

• src/composables/useApiCall.ts：包裝可重用 API 呼叫狀態與錯誤提示流程
• src/composables/layout/useAdminLayoutState.ts：提供 layout shell 所需的狀態組裝
• src/composables/layout/useThemeToggle.ts：提供主題切換流程
• src/composables/page-drivers/useMaintenancePage.ts：提供通用 maintenance page model 基礎狀態
• src/composables/page-drivers/useSingleRecordMaintenancePage.ts：協調單筆維護 demo 頁面的 page model、section props/events、表單、表格與 command
• src/composables/commands/useCrudCommands.ts：提供 CRUD command 流程，讓 view 不直接執行 store mutation 細節
• src/composables/maint/useMaintenanceCrudFlow.ts：提供維護頁 CRUD 流程狀態
• src/composables/maint/useStudentMaintenanceForm.ts：提供學生維護表單狀態
• src/composables/maint/useEditableStudentGrid.ts：提供 editable grid 狀態

新增 composable 時，用 useXxx.ts 命名。若是頁面資料協調，放在 src/composables/page-drivers；若是命令式副作用流程，放在 src/composables/commands；若只服務單一 feature，放在 src/composables/<feature>；若確定跨 feature 使用，才放在 src/composables 根目錄。

Store 與 Service 資料流規則

只有在資料或狀態跨頁共享時才使用 store。單一頁面的暫時 UI 狀態應留在 view、feature component 或 composable。

store 檔案直接放在 src/stores/*.ts。不要建立 src/stores/stores/* 或其他重複巢狀 store 目錄。

service 放在 src/services，負責外部 API 與 HTTP 細節。component 不應直接處理底層 HTTP client、token、hooks 或錯誤正規化。

資料流優先順序：

1. component 透過 props/emits 與 view 或 page component 溝通。
2. view 或 composable 協調頁面流程。
3. 跨頁共享狀態由 store 管理。
4. store 或 composable 呼叫 service。
5. service 回傳資料，不持有 UI 狀態。

不要讓 service import component、view 或 store。不要讓 component 直接繞過既有 store/composable 去操作 token、session 或 HTTP hooks。

環境變數規則

template 提供 .env.example 作為範本。不要提交實際 .env 或 .env.*.local。

常用變數：

• VITE_API_BASE_URL：API base URL，預設使用 /service/api 搭配 Vite proxy。
• VITE_SKIP_LOGIN：登入示範開關，只有專案明確支援時才使用。
• VITE_DEV_DEFAULT_USER_ID、VITE_DEV_DEFAULT_PASSWORD：本機開發示範帳號，放在本機 env，不要寫進程式。

Vuetify 使用規則

優先使用 Vuetify 原生元件、props、slots 與事件。當需求直接牽涉 Vuetify 元件行為、DOM、可及性輸出或 slot 結構時，先查官方 Vuetify API 文件，再修改實作。

icon 使用 @mdi/js：

<script setup lang="ts">
import { mdiAccount } from '@mdi/js'
</script>

<template>
  <v-icon :icon="mdiAccount" />
</template>

修改前檢查

開始改檔前先確認：

• 是否會碰到禁止修改檔案
• 是否只需要新增或修改 view
• 是否需要新增 route
• 是否需要拆 feature component
• 是否已閱讀 docs/architecture-strategy.md
• 是否已參考 src/ 裡相同類型的既有範例
• 是否符合 Vue 3、Composition API、<script setup lang="ts"> 的既有寫法

完成前驗證

修改完成後，至少執行與變更範圍相符的檢查：

• TypeScript 或 Vue 結構有變更：pnpm type-check
• 需要確認產物可建置：pnpm build
• route、layout 或主要畫面流程有變更：啟動 dev server 並用瀏覽器確認頁面被正確包在主 layout 中

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