skt-vuetify-templates/src/README.md

Src 開發入口

src 是 template 使用者主要修改的區域。新增功能時，先從 views 與 router/routes.ts 開始，除非需求明確牽涉 app shell，否則不要先改 layout。

常見開發流程

1. 在 src/views 或 src/views/<feature> 新增 route view。
2. 在 src/router/routes.ts 加入 route。
3. 一般頁面使用 meta: { layout: 'default' }，讓內容被 MainLayout 包住。
4. 畫面超過單一簡單區塊時，拆到 src/components/<feature>。
5. 可重用流程或較複雜 UI state 放到 src/composables/<feature>。
6. 跨頁共享狀態放到 src/stores/*.ts。
7. API 呼叫放到 src/services/modules/<domain>.ts。

主要資料流

router -> App.vue -> layout -> view -> component -> composable/store -> service

責任分工：

• router：route、layout meta、auth meta 與錯誤頁入口。
• App.vue：根據 route meta 組裝 layout、全域 UI 與 layout event。
• views：路由入口、頁面資料協調與頁面事件協調。
• components：畫面呈現、props/emits 與可拆分 UI 區塊。
• composables：可重用流程、頁面狀態機或較複雜 UI state。
• stores：跨頁共享狀態、快取與全域顯示狀態。
• services：HTTP client、API 模組、token、session 與錯誤處理。

Template Core

一般功能開發時，優先視為 template core：

App shell：

• src/main.ts
• src/App.vue

Layout：

• src/components/layouts/MainLayout.vue
• src/components/layouts/PlainLayout.vue
• src/components/layouts/main-layout/*

Login entry：

• src/views/Login.vue

Router core：

• src/router/index.ts
• src/router/guards.ts

Plugin / theme core：

• src/plugins/*
• src/styles/*

HTTP core：

• 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

Global stores：

• src/stores/auth.ts
• src/stores/menu.ts
• src/stores/breadcrumbs.ts
• src/stores/favorites.ts
• src/stores/messages.ts
• src/stores/snackbar.ts

Layout composables：

• src/composables/layout/*

這些檔案支撐 app shell、登入、路由、全域狀態與 API 基礎設施。只有需求明確要求修改 template core 時才調整。

src/router/routes.ts 是功能開發時可新增 route 的入口，但不要改壞既有 layout meta、auth meta 與 catch-all route 規則。

登入 route 入口是 src/views/Login.vue。若只是調整登入畫面內容，優先修改 src/components/PageLogin.vue 與 src/components/login/*。

src/services/modules/auth.ts 與 src/services/modules/menu.ts 是預設後端契約的 API adapter。接新後端時常需要調整，但不要把 UI 狀態放進 service module。

Demo / Example

以下內容偏向示範資料與範例頁，建立新專案時可依需求替換或刪除：

• src/views/Home.vue
• src/components/PageIndex.vue
• src/views/maint/*
• src/components/maint/*
• src/composables/maint/*
• src/components/PageMaint.vue
• src/stores/students.ts
• src/stores/semesters.ts
• src/views/FncPage.vue
• src/views/Settings.vue
• src/language/*.json 中與 starter home、maint、學生資料相關的文案
• src/assets/logo.png
• src/assets/logo.svg
• src/assets/robot-svgrepo-com.svg

刪除 demo/example 時，也要同步清理：

• src/router/routes.ts
• src/stores/menu.ts 中依賴的選單資料流程
• 相關 src/language/*.json 文案
• 不再被 import 的 demo components、composables、stores 與 assets

新頁面最小範例

// src/router/routes.ts
{
  path: '/reports',
  name: 'reports',
  component: () => import('@/views/reports/Reports.vue'),
  meta: { layout: 'default', requiresAuth: true },
}

<!-- src/views/reports/Reports.vue -->
<script setup lang="ts">
import ReportsTable from '@/components/reports/ReportsTable.vue'
</script>

<template>
  <ReportsTable />
</template>

更多範例見 docs/add-page-example.md。

文件導覽

• docs/add-page-example.md：新增頁面範例。
• docs/frontend-layering.md：完整分層與責任邊界。
• docs/llm-development-guide.md：LLM 操作邊界。

驗證

pnpm type-check
pnpm build