docs: update README.md to enhance project structure and core concepts

yuwen

2天前 d9ec9bbb8420f23f8752c86f71ed2ec598b52173

docs: update README.md to enhance project structure and core concepts

 README.md

@@ -1,73 +1,199 @@
# 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/) 瀏覽器擴充套件