From d9ec9bbb8420f23f8752c86f71ed2ec598b52173 Mon Sep 17 00:00:00 2001
From: yuwen <yuwen@i-mps.com>
Date: 星期五, 30 一月 2026 09:04:32 +0800
Subject: [PATCH] docs: update README.md to enhance project structure and core concepts
---
README.md | 208 +++++++++++++++++++++++++++++++++++++++++----------
1 files changed, 167 insertions(+), 41 deletions(-)
diff --git a/README.md b/README.md
index 2cff5bf..7344658 100644
--- a/README.md
+++ b/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/) 瀏覽器擴充套件
--
Gitblit v1.8.0