skytek_xinliang
87fbc1dda8
Add env example defaults for Vite API and login settings, document template structure and page creation flow, and align agent guidance with current LLM development rules. Also allow committing the env example while keeping local env files ignored.docs: refresh project guidance and environment setup Add env example defaults for Vite API and login settings, document template structure and page creation flow, and align agent guidance with current LLM development rules. Also allow committing the env example while keeping local env files ignored.
154 lines
4.2 KiB
Markdown
154 lines
4.2 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
pnpm install
|
||
pnpm dev
|
||
```
|
||
|
||
開發伺服器預設使用 `vite.config.mts` 的 port `3700`。
|
||
|
||
## Template 使用方式
|
||
|
||
一般功能開發從 `src` 開始：
|
||
|
||
1. 在 `src/views` 或 `src/views/<feature>` 新增頁面。
|
||
2. 在 `src/router/routes.ts` 新增 route。
|
||
3. 一般頁面使用 `meta: { layout: 'default' }`。
|
||
4. 畫面區塊拆到 `src/components/<feature>`。
|
||
5. 複雜流程放到 `src/composables/<feature>`。
|
||
6. 跨頁共享狀態放到 `src/stores/*.ts`。
|
||
7. API module 放到 `src/services/modules/<domain>.ts`。
|
||
|
||
更完整的入口說明見 [src/README.md](./src/README.md)。
|
||
|
||
## 新增頁面
|
||
|
||
最小 route 範例：
|
||
|
||
```ts
|
||
{
|
||
path: '/reports',
|
||
name: 'reports',
|
||
component: () => import('@/views/reports/Reports.vue'),
|
||
meta: { layout: 'default', requiresAuth: true },
|
||
}
|
||
```
|
||
|
||
完整範例見 [docs/add-page-example.md](./docs/add-page-example.md)。
|
||
|
||
## Layout
|
||
|
||
`App.vue` 會根據 `route.meta.layout` 選擇 layout：
|
||
|
||
- `default`：使用 `src/components/layouts/MainLayout.vue`
|
||
- `none`：使用 `src/components/layouts/PlainLayout.vue`
|
||
|
||
一般功能頁使用 `default`。登入頁、錯誤頁、維護中頁、明確要求獨立顯示的頁面才使用 `none`。
|
||
|
||
## API 與環境變數
|
||
|
||
複製 `.env.example` 作為本機設定起點：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
常用設定：
|
||
|
||
```env
|
||
VITE_API_BASE_URL=/service/api
|
||
VITE_SKIP_LOGIN=false
|
||
VITE_DEV_DEFAULT_USER_ID=
|
||
VITE_DEV_DEFAULT_PASSWORD=
|
||
```
|
||
|
||
`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 與 Demo
|
||
|
||
template core 是 app shell、router、layout、plugins、styles、services 基礎設施與全域 stores。一般專案會保留它們。
|
||
|
||
demo/example 主要是 maintenance 與學生資料範例：
|
||
|
||
- `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/assets/*` 中的品牌或展示素材
|
||
|
||
建立正式專案時可依需求替換或刪除 demo/example。刪除時同步清理 routes、menu、language、assets 與引用。
|
||
|
||
## Documentation
|
||
|
||
- [src/README.md](./src/README.md)：`src` 開發入口。
|
||
- [docs/frontend-layering.md](./docs/frontend-layering.md)：目前前端分層與責任邊界。
|
||
- [docs/llm-development-guide.md](./docs/llm-development-guide.md)：給 LLM 的操作規則。
|
||
- [docs/add-page-example.md](./docs/add-page-example.md)：新增頁面範例。
|
||
- [src/components/README.md](./src/components/README.md)
|
||
- [src/services/README.md](./src/services/README.md)
|
||
- [src/plugins/README.md](./src/plugins/README.md)
|
||
- [src/styles/README.md](./src/styles/README.md)
|
||
|
||
## Scripts
|
||
|
||
- `pnpm dev`
|
||
- `pnpm build`
|
||
- `pnpm preview`
|
||
- `pnpm build-only`
|
||
- `pnpm type-check`
|
||
- `pnpm format`
|
||
- `pnpm mcp`
|
||
- `pnpm mcp:revert`
|
||
|
||
## Verification
|
||
|
||
完成修改後至少執行：
|
||
|
||
```bash
|
||
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/
|