skytek_xinliang
4d66718b05
Add VITE_PROXY_TARGET to the example environment file and use it in the Vite dev proxy configuration with a localhost fallback. Expand the LLM development guide with env file loading order, version-control rules, and variable descriptions. Also clean up ignored local tool paths in .gitignore and remove duplicated README env examples.chore: document env files and configure proxy target Add VITE_PROXY_TARGET to the example environment file and use it in the Vite dev proxy configuration with a localhost fallback. Expand the LLM development guide with env file loading order, version-control rules, and variable descriptions. Also clean up ignored local tool paths in .gitignore and remove duplicated README env examples.
129 lines
3.6 KiB
Markdown
129 lines
3.6 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
|
||
```
|
||
|
||
`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/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/
|