skytek_xinliang
8af82f5900
Update documentation rules for GUIDE.md files to keep higher-level guides focused on constraints, conventions, and indexes. Add base and section component guides to the LLM development index, clarify component layering responsibilities, and fix architecture references from README to GUIDE.md.docs: reorganize component guide structure and indexes Update documentation rules for GUIDE.md files to keep higher-level guides focused on constraints, conventions, and indexes. Add base and section component guides to the LLM development index, clarify component layering responsibilities, and fix architecture references from README to GUIDE.md.
skt-vuetify-templates
Vue 3 + Vite + Vuetify template，目標是讓新專案可以直接在 src 裡新增 views、components、stores、services 與 composables，並讓一般頁面自動被主框架 layout 包住。
Stack
- Vue 3 + Vite
- Vuetify
- TypeScript
- Pinia
- Vue Router
- Vue I18n
- pnpm
Quick Start
pnpm install
pnpm dev
開發伺服器預設使用 vite.config.mts 的 port 3700。
Template 使用方式
一般功能開發從 src 開始：
- 在
src/views或src/views/<feature>新增頁面。 - 在
src/router/routes.ts新增 route。 - 一般頁面使用
meta: { layout: 'default' }。 - 畫面區塊拆到
src/components/<feature>。 - 複雜流程放到
src/composables/<feature>。 - 跨頁共享狀態放到
src/stores/*.ts。 - API module 放到
src/services/modules/<domain>.ts。
更完整的入口說明見 src/README.md。
新增頁面
最小 route 範例：
{
path: '/reports',
name: 'reports',
component: () => import('@/views/reports/Reports.vue'),
meta: { layout: 'default', requiresAuth: true },
}
完整範例見 docs/add-page-example.md。
Layout
App.vue 會根據 route.meta.layout 選擇 layout：
default：使用src/components/layouts/MainLayout.vuenone：使用src/components/layouts/PlainLayout.vue
一般功能頁使用 default。登入頁、錯誤頁、維護中頁、明確要求獨立顯示的頁面才使用 none。
API 與環境變數
複製 .env.example 作為本機設定起點：
cp .env.example .env
client.ts 會優先使用 VITE_API_BASE_URL，否則預設 /service/api。開發模式下，Vite proxy 會將 /service/* 轉送到後端。
實際 .env 與 .env.*.local 不應提交。production API URL 應由使用專案自己的部署環境提供。
Project Structure
src/main.ts：app entry。src/App.vue：app shell 組裝層，依 route meta 切換 layout。src/router：routes、history、guards。src/views：route views。src/components：layout、page component、feature/domain components。src/composables：可重用流程與 UI state。src/stores：Pinia stores。src/services：HTTP client、API modules、token/session/error。src/plugins：Vuetify、Pinia、I18n、Router 註冊。src/styles：Vuetify SASS settings 與 themes。src/language：i18n JSON。
Template Core
template core 是 app shell、router、layout、plugins、styles、services 基礎設施與全域 stores。一般專案會保留它們。
Documentation
- src/README.md：
src開發入口。 - docs/frontend-layering.md：目前前端分層與責任邊界。
- docs/llm-development-guide.md：給 LLM 的操作規則。
- docs/add-page-example.md：新增頁面範例。
- src/components/README.md
- src/services/README.md
- src/plugins/README.md
- src/styles/README.md
Scripts
pnpm devpnpm buildpnpm previewpnpm build-onlypnpm type-checkpnpm formatpnpm mcppnpm mcp:revert
Verification
完成修改後至少執行：
pnpm type-check
pnpm build
若變更 route、layout 或主要 UI flow，再啟動 dev server 並用瀏覽器確認。
Vuetify
- Vuetify docs: https://vuetifyjs.com/
- Installation guide: https://vuetifyjs.com/en/getting-started/installation/