skytek_xinliang
799b16578d
Update the LLM development guide to prioritize src/GUIDE.md and add detailed `.spec.json` mapping rules for query, application, and maintenance pages. Clarify how page contracts, API contracts, actions, validation, naming, error handling, and i18n should drive generated composables and page components.docs: expand LLM guide with spec-to-page mapping Update the LLM development guide to prioritize src/GUIDE.md and add detailed `.spec.json` mapping rules for query, application, and maintenance pages. Clarify how page contracts, API contracts, actions, validation, naming, error handling, and i18n should drive generated composables and page components.
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/