| | |
|---|
| | | # vue-project |
|---|
| | | # Vue Project |
|---|
| | | |
|---|
| | | This template should help get you started developing with Vue 3 in Vite. |
|---|
| | | 基於 Vue 3 + TypeScript + Vite 的現代化前端專案模板。 |
|---|
| | | |
|---|
| | | ## Recommended IDE Setup |
|---|
| | | ## 📁 專案架構 |
|---|
| | | |
|---|
| | | [VS Code](https://code.visualstudio.com/) + [Vue (Official)](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur). |
|---|
| | | 本專案採用 **Feature-Based** 資料夾架構，讓功能模組更加內聚且易於維護。 |
|---|
| | | |
|---|
| | | ## Recommended Browser Setup |
|---|
| | | ### 核心理念 |
|---|
| | | |
|---|
| | | - Chromium-based browsers (Chrome, Edge, Brave, etc.): |
|---|
| | | - [Vue.js devtools](https://chromewebstore.google.com/detail/vuejs-devtools/nhdogjmejiglipccpnnnanhbledajbpd) |
|---|
| | | - [Turn on Custom Object Formatter in Chrome DevTools](http://bit.ly/object-formatters) |
|---|
| | | - Firefox: |
|---|
| | | - [Vue.js devtools](https://addons.mozilla.org/en-US/firefox/addon/vue-js-devtools/) |
|---|
| | | - [Turn on Custom Object Formatter in Firefox DevTools](https://fxdx.dev/firefox-devtools-custom-object-formatters/) |
|---|
| | | - **高內聚性**：將高度耦合的程式碼放在一起,相關的功能邏輯集中管理 |
|---|
| | | - **功能優先**：主要功能放在 `src/features/` 目錄下,每個 feature 作為一個獨立模組 |
|---|
| | | - **就近原則**：每個 feature 內可包含自己的 `stores`, `components`, `utils`, `types` 等 |
|---|
| | | - **靈活組織**：根據複雜度選擇使用單一檔案或建立資料夾 |
|---|
| | | - **共用提升**：高度共用的代碼放在 `src/` 根目錄下(如 `src/hooks/`, `src/stores/`, `src/utils/`) |
|---|
| | | |
|---|
| | | ## Type Support for `.vue` Imports in TS |
|---|
| | | ### 目錄結構 |
|---|
| | | |
|---|
| | | TypeScript cannot handle type information for `.vue` imports by default, so we replace the `tsc` CLI with `vue-tsc` for type checking. In editors, we need [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) to make the TypeScript language service aware of `.vue` types. |
|---|
| | | ``` |
|---|
| | | src/ |
|---|
| | | ├── features/ # 功能模組目錄 |
|---|
| | | │ └── example/ # 範例功能模組 |
|---|
| | | │ ├── index.vue # 主元件 |
|---|
| | | │ ├── api.ts # API 請求 |
|---|
| | | │ └── index.spec.ts # 單元測試 |
|---|
| | | ├── hooks/ # 共用的 Composition API hooks |
|---|
| | | │ └── useRequest.ts # API 請求 hook |
|---|
| | | ├── stores/ # 全域狀態管理 |
|---|
| | | │ ├── axios.ts # Axios 實例與攔截器 |
|---|
| | | │ └── counter.ts # 範例 store |
|---|
| | | ├── mocks/ # MSW mock 資料 |
|---|
| | | │ ├── browser.ts # 瀏覽器環境 mock |
|---|
| | | │ ├── node.ts # Node 環境 mock |
|---|
| | | │ ├── handlers.ts # API handlers |
|---|
| | | │ └── data/ # Mock 資料 |
|---|
| | | ├── router/ # Vue Router 配置 |
|---|
| | | ├── utils/ # 共用工具函數 |
|---|
| | | │ └── cn.ts # Tailwind CSS 類名合併工具 |
|---|
| | | ├── types/ # 全域型別定義 |
|---|
| | | ├── plugins/ # Vue 插件 |
|---|
| | | │ └── icons/ # Iconify 整合 |
|---|
| | | ├── config/ # [選用] 專案全域設定 |
|---|
| | | ├── const/ # [選用] 常數定義 |
|---|
| | | └── assets/ # 靜態資源 |
|---|
| | | ├── css/ |
|---|
| | | └── icons/ # 圖標資源 |
|---|
| | | ``` |
|---|
| | | |
|---|
| | | ## Customize configuration |
|---|
| | | ## 🛠️ 技術棧 |
|---|
| | | |
|---|
| | | See [Vite Configuration Reference](https://vite.dev/config/). |
|---|
| | | ### 核心框架 |
|---|
| | | |
|---|
| | | ## Project Setup |
|---|
| | | - **Vue 3** - 漸進式前端框架 |
|---|
| | | - **TypeScript** - 型別安全的 JavaScript 超集 |
|---|
| | | - **Vite** - 次世代前端建構工具 |
|---|
| | | - **Pinia** - Vue 3 官方狀態管理 |
|---|
| | | |
|---|
| | | ### 開發工具 |
|---|
| | | |
|---|
| | | - **ESLint** - 程式碼品質檢查 |
|---|
| | | - **Prettier** - 程式碼格式化 |
|---|
| | | - **Vitest** - 單元測試框架 |
|---|
| | | - **Playwright** - E2E 測試框架 |
|---|
| | | - **MSW (Mock Service Worker)** - API mocking 工具 |
|---|
| | | |
|---|
| | | ### UI & 樣式 |
|---|
| | | |
|---|
| | | - **Tailwind CSS** - 實用優先的 CSS 框架 |
|---|
| | | - **Iconify** - 統一的圖標解決方案(內建自動整合工具) |
|---|
| | | |
|---|
| | | ## 🔧 核心功能說明 |
|---|
| | | |
|---|
| | | ### Iconify 整合工具 |
|---|
| | | |
|---|
| | | 專案內建自動化的 Iconify 圖標整合工具,會自動掃描專案中使用的圖標並產生對應的 JSON 檔案,實現按需載入,減少打包體積。圖標檔案放在 `src/assets/icons/` 目錄下,建構時會自動處理。 |
|---|
| | | |
|---|
| | | ### API 請求架構 |
|---|
| | | |
|---|
| | | 1. **`useRequest` Hook** - 提供統一的 API 請求介面 |
|---|
| | | 2. **Axios Store** - 管理 Axios 實例與全域攔截器(如 token 注入、錯誤處理等) |
|---|
| | | 3. **MSW** - 開發環境下提供 API mocking,讓前端開發不依賴後端服務 |
|---|
| | | |
|---|
| | | 三者關係: |
|---|
| | | |
|---|
| | | ``` |
|---|
| | | Component → useRequest → Axios Store → Backend API |
|---|
| | | ↓ (開發環境) |
|---|
| | | MSW |
|---|
| | | ``` |
|---|
| | | |
|---|
| | | ### cn 工具函數 |
|---|
| | | |
|---|
| | | `cn` 是基於 `clsx` 和 `tailwind-merge` 的工具函數,用於智能合併 Tailwind CSS 類名,解決類名衝突問題。 |
|---|
| | | |
|---|
| | | ```typescript |
|---|
| | | cn('px-2 py-1', 'px-4') // 輸出: 'py-1 px-4' (後者覆蓋前者) |
|---|
| | | ``` |
|---|
| | | |
|---|
| | | ## 📦 推薦套件 |
|---|
| | | |
|---|
| | | 當專案需求擴展時,以下是可優先選用的套件: |
|---|
| | | |
|---|
| | | ### Vue 生態系統 |
|---|
| | | |
|---|
| | | - **[@vueuse/core](https://vueuse.org/)** - 豐富的 Vue Composition API 工具集,提供大量開箱即用的組合式函數 |
|---|
| | | |
|---|
| | | ### 通用工具 |
|---|
| | | |
|---|
| | | - **[dayjs](https://day.js.org/)** - 輕量級日期處理庫 |
|---|
| | | - **[zod](https://zod.dev/)** - TypeScript-first 的 schema 驗證庫 |
|---|
| | | - **[decimal.js](https://mikemcl.github.io/decimal.js/)** - 任意精度的十進制運算庫,適用於金融等對數值精度要求高的場景 |
|---|
| | | - **[numeral.js](http://numeraljs.com/)** - 強大的數值格式化工具 |
|---|
| | | |
|---|
| | | ### 資料請求 |
|---|
| | | |
|---|
| | | - **[@tanstack/vue-query](https://tanstack.com/query/latest)** - 強大的非同步狀態管理庫,提供快取、重試、輪詢等功能,大幅簡化 API 請求邏輯 |
|---|
| | | |
|---|
| | | ### 表單處理 |
|---|
| | | |
|---|
| | | - **[vee-validate](https://vee-validate.logaretm.com/v4/)** - Vue 3 表單驗證框架,支援多種驗證策略與 schema 整合 |
|---|
| | | |
|---|
| | | ### UI 框架 |
|---|
| | | |
|---|
| | | - **[Element Plus](https://element-plus.org/)** - 成熟的 Vue 3 UI 組件庫(公司慣用選擇) |
|---|
| | | |
|---|
| | | ## 💡 開發心法 |
|---|
| | | |
|---|
| | | ### 1. UI 元件開發策略 |
|---|
| | | |
|---|
| | | **原則**: 除非是複雜或難以實現的元件(如 Table、Popper、DatePicker、VirtualSelect 等),否則盡可能自行開發。 |
|---|
| | | |
|---|
| | | **理由**: |
|---|
| | | |
|---|
| | | - 現在有 AI 輔助,簡單元件開發成本大幅降低 |
|---|
| | | - 自行開發的元件更貼合專案需求,減少不必要的依賴 |
|---|
| | | - 對於複雜元件,直接使用 UI 框架可節省大量時間 |
|---|
| | | |
|---|
| | | ### 2. 商業邏輯與元件分離 |
|---|
| | | |
|---|
| | | **原則**: 盡可能將商業邏輯移至元件之外(如獨立的 composables、utils 或 stores)。 |
|---|
| | | |
|---|
| | | **好處**: |
|---|
| | | |
|---|
| | | - 元件保持簡潔,專注於 UI 呈現 |
|---|
| | | - 商業邏輯可獨立測試,提高程式碼可測試性 |
|---|
| | | - 邏輯可跨元件復用 |
|---|
| | | |
|---|
| | | ### 3. 測試規範 |
|---|
| | | |
|---|
| | | **原則**: 測試不是必須的,但如果寫了測試,就必須保證測試通過才能 commit。 |
|---|
| | | |
|---|
| | | **要求**: |
|---|
| | | |
|---|
| | | - ✅ 所有測試都必須 pass |
|---|
| | | - ❌ 不允許 commit 失敗的測試 |
|---|
| | | - ❌ 如果測試無法修復,請直接刪除,不要留下會誤導的錯誤測試 |
|---|
| | | |
|---|
| | | **執行方式**: 建議使用 Git hooks(如 husky + lint-staged)確保 commit 前測試通過。 |
|---|
| | | |
|---|
| | | ## 🚀 快速開始 |
|---|
| | | |
|---|
| | | ### 安裝依賴 |
|---|
| | | |
|---|
| | | ```sh |
|---|
| | | npm install |
|---|
| | | ``` |
|---|
| | | |
|---|
| | | ### Compile and Hot-Reload for Development |
|---|
| | | ### 開發環境 |
|---|
| | | |
|---|
| | | ```sh |
|---|
| | | npm run dev |
|---|
| | | ``` |
|---|
| | | |
|---|
| | | ### Type-Check, Compile and Minify for Production |
|---|
| | | ### 執行測試 |
|---|
| | | |
|---|
| | | ```sh |
|---|
| | | npm run build |
|---|
| | | ``` |
|---|
| | | |
|---|
| | | ### Run Unit Tests with [Vitest](https://vitest.dev/) |
|---|
| | | |
|---|
| | | ```sh |
|---|
| | | # 單元測試 |
|---|
| | | npm run test:unit |
|---|
| | | ``` |
|---|
| | | |
|---|
| | | ### Run End-to-End Tests with [Playwright](https://playwright.dev) |
|---|
| | | |
|---|
| | | ```sh |
|---|
| | | # Install browsers for the first run |
|---|
| | | # E2E 測試(首次需安裝瀏覽器) |
|---|
| | | npx playwright install |
|---|
| | | |
|---|
| | | # When testing on CI, must build the project first |
|---|
| | | npm run build |
|---|
| | | |
|---|
| | | # Runs the end-to-end tests |
|---|
| | | npm run test:e2e |
|---|
| | | # Runs the tests only on Chromium |
|---|
| | | npm run test:e2e -- --project=chromium |
|---|
| | | # Runs the tests of a specific file |
|---|
| | | npm run test:e2e -- tests/example.spec.ts |
|---|
| | | # Runs the tests in debug mode |
|---|
| | | npm run test:e2e -- --debug |
|---|
| | | ``` |
|---|
| | | |
|---|
| | | ### Lint with [ESLint](https://eslint.org/) |
|---|
| | | ### 程式碼檢查 |
|---|
| | | |
|---|
| | | ```sh |
|---|
| | | npm run lint |
|---|
| | | ``` |
|---|
| | | |
|---|
| | | ## 📚 更多文件 |
|---|
| | | |
|---|
| | | - [Icon 設定指南](docs/icon-setup.md) |
|---|
| | | - [測試指南](docs/testing-guide.md) |
|---|
| | | |
|---|
| | | ## 🔧 IDE 設定建議 |
|---|
| | | |
|---|
| | | - [VS Code](https://code.visualstudio.com/) + [Vue - Official](https://marketplace.visualstudio.com/items?itemName=Vue.volar) |
|---|
| | | - 推薦安裝 [Vue.js devtools](https://devtools.vuejs.org/) 瀏覽器擴充套件 |
|---|
