# 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/