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.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.
This commit is contained in:
skytek_xinliang
@@ -1,115 +1,153 @@
|
||||
# skt-vuetify-templates
|
||||
|
||||
Scaffolded with Vuetify CLI.
|
||||
Vue 3 + Vite + Vuetify template，目標是讓新專案可以直接在 `src` 裡新增 views、components、stores、services 與 composables，並讓一般頁面自動被主框架 layout 包住。
|
||||
|
||||
## ❗️ Documentation
|
||||
## Stack
|
||||
|
||||
- Primary docs: https://vuetifyjs.com/
|
||||
- Getting started guide: https://vuetifyjs.com/en/getting-started/installation/
|
||||
- Community support: https://community.vuetifyjs.com/
|
||||
- Issue tracker: https://issues.vuetifyjs.com/
|
||||
|
||||
## 🧱 Stack
|
||||
|
||||
- Framework: Vue 3 + Vite
|
||||
- UI Library: Vuetify
|
||||
- Language: TypeScript
|
||||
- Package manager: pnpm
|
||||
|
||||
## 🧭 Start Here
|
||||
|
||||
- Main entry: `src/main.ts`
|
||||
- Main app component: `src/App.vue`
|
||||
- Main styles: `src/styles/`
|
||||
- Plugin setup: `src/plugins/`
|
||||
|
||||
## 📁 Project Structure
|
||||
|
||||
- `src/main.ts` — application entry point
|
||||
- `src/App.vue` — root component
|
||||
- `src/components/` — reusable Vue components
|
||||
- `src/plugins/` — plugin registration and setup
|
||||
- `src/styles/` — global styles and theme settings
|
||||
- `public/` — static public files
|
||||
|
||||
## ✨ Enabled Features
|
||||
|
||||
- ESLint
|
||||
- Vuetify MCP
|
||||
- Vue 3 + Vite
|
||||
- Vuetify
|
||||
- TypeScript
|
||||
- Pinia
|
||||
- Vue I18n
|
||||
- Vue Router
|
||||
- Vue I18n
|
||||
- pnpm
|
||||
|
||||
## 💿 Install
|
||||
|
||||
Use your selected package manager (pnpm) to install dependencies:
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
## 🚀 Quick Start
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
## 🏗️ Build
|
||||
開發伺服器預設使用 `vite.config.mts` 的 port `3700`。
|
||||
|
||||
```bash
|
||||
pnpm build
|
||||
## 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 },
|
||||
}
|
||||
```
|
||||
|
||||
## 🧪 Available Scripts
|
||||
完整範例見 [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 lint`
|
||||
- `pnpm lint:fix`
|
||||
- `pnpm format`
|
||||
- `pnpm mcp`
|
||||
- `pnpm mcp:revert`
|
||||
|
||||
## 💪 Support Vuetify Development
|
||||
## Verification
|
||||
|
||||
This project uses Vuetify - an MIT licensed Open Source project. We are glad to welcome contributors and any support for ongoing development:
|
||||
|
||||
- Contribute to Vuetify and ecosystem projects: https://github.com/vuetifyjs
|
||||
- Request enterprise support: https://support.vuetifyjs.com/
|
||||
- Sponsor on GitHub: https://github.com/sponsors/vuetifyjs
|
||||
- Support on Open Collective: https://opencollective.com/vuetify
|
||||
|
||||
## playwright
|
||||
完成修改後至少執行：
|
||||
|
||||
```bash
|
||||
pnpm exec playwright test
|
||||
# Runs the end-to-end tests.
|
||||
|
||||
pnpm exec playwright test --ui
|
||||
# Starts the interactive UI mode.
|
||||
|
||||
pnpm exec playwright test --project=chromium
|
||||
# Runs the tests only on Desktop Chrome.
|
||||
|
||||
pnpm exec playwright test example
|
||||
# Runs the tests in a specific file.
|
||||
|
||||
pnpm exec playwright test --debug
|
||||
# Runs the tests in debug mode.
|
||||
|
||||
pnpm exec playwright codegen
|
||||
# Auto generate tests with Codegen.
|
||||
pnpm type-check
|
||||
pnpm build
|
||||
```
|
||||
|
||||
We suggest that you begin by typing:
|
||||
若變更 route、layout 或主要 UI flow，再啟動 dev server 並用瀏覽器確認。
|
||||
|
||||
```bash
|
||||
pnpm exec playwright test
|
||||
```
|
||||
## Vuetify
|
||||
|
||||
And check out the following files:
|
||||
- ./tests/e2e/example.spec.ts - Example end-to-end test
|
||||
- ./playwright.config.ts - Playwright Test configuration
|
||||
- Vuetify docs: https://vuetifyjs.com/
|
||||
- Installation guide: https://vuetifyjs.com/en/getting-started/installation/
|
||||
|
||||
Reference in New Issue
Block a user