update FRONTEND documentation
This commit is contained in:
beabigegg
397
FRONTEND_QUICK_REFERENCE.md
Normal file
397
FRONTEND_QUICK_REFERENCE.md
Normal file
@@ -0,0 +1,397 @@
|
||||
# Tool_OCR 前端快速參考指南
|
||||
|
||||
## 文件位置速查表
|
||||
|
||||
### 主要文件位置
|
||||
```
|
||||
/Users/egg/Projects/Tool_OCR/frontend/
|
||||
├── src/
|
||||
│ ├── App.tsx # 路由定義
|
||||
│ ├── main.tsx # 應用入口
|
||||
│ ├── index.css # 全局樣式
|
||||
│ ├── components/
|
||||
│ │ ├── ui/ # UI 組件庫
|
||||
│ │ ├── Layout.tsx # 主佈局
|
||||
│ │ ├── FileUpload.tsx # 文件上傳
|
||||
│ │ └── ...
|
||||
│ ├── pages/ # 頁面
|
||||
│ ├── store/ # 狀態管理
|
||||
│ ├── services/api.ts # API 客戶端
|
||||
│ ├── types/api.ts # 類型定義
|
||||
│ ├── i18n/ # 國際化
|
||||
│ └── lib/utils.ts # 工具函數
|
||||
├── vite.config.ts # Vite 配置
|
||||
├── tailwind.config.js # Tailwind 配置
|
||||
├── tsconfig.json # TypeScript 配置
|
||||
└── package.json # 依賴管理
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 技術棧速查
|
||||
|
||||
| 功能 | 技術 | 版本 |
|
||||
|-----|------|------|
|
||||
| UI 框架 | React | 19.2.0 |
|
||||
| 語言 | TypeScript | 5.9.3 |
|
||||
| 構建 | Vite | 7.2.2 |
|
||||
| 樣式 | Tailwind CSS | 4.1.17 |
|
||||
| 狀態管理 | Zustand | 5.0.8 |
|
||||
| 數據獲取 | React Query | 5.90.7 |
|
||||
| 路由 | React Router | 7.9.5 |
|
||||
| 國際化 | i18next | 25.6.2 |
|
||||
| HTTP | Axios | 1.13.2 |
|
||||
| 檔案上傳 | react-dropzone | 14.3.8 |
|
||||
|
||||
---
|
||||
|
||||
## 常用命令
|
||||
|
||||
```bash
|
||||
# 開發
|
||||
cd frontend
|
||||
npm run dev # 啟動開發服務器 (localhost:12011)
|
||||
npm run lint # 代碼檢查
|
||||
npm run build # 生產構建
|
||||
|
||||
# 類型檢查
|
||||
npx tsc --noEmit # 檢查 TypeScript 錯誤
|
||||
|
||||
# 格式化
|
||||
npm install -D prettier # (如果需要)
|
||||
npx prettier --write src/ # 格式化代碼
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 路由結構
|
||||
|
||||
```
|
||||
/login → LoginPage (公開)
|
||||
/upload → UploadPage (受保護)
|
||||
/processing → ProcessingPage (受保護)
|
||||
/results → ResultsPage (受保護)
|
||||
/export → ExportPage (受保護)
|
||||
/settings → SettingsPage (受保護)
|
||||
```
|
||||
|
||||
### 添加新路由
|
||||
```typescript
|
||||
// 在 App.tsx 中
|
||||
<Route path="new-page" element={<NewPage />} />
|
||||
|
||||
// 在導航中
|
||||
{ to: '/new-page', label: t('nav.newPage') }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 常用代碼片段
|
||||
|
||||
### 使用 i18n 翻譯
|
||||
```typescript
|
||||
const { t } = useTranslation()
|
||||
<h1>{t('key.path')}</h1>
|
||||
```
|
||||
|
||||
### 使用 Zustand 狀態
|
||||
```typescript
|
||||
const { batchId, setBatchId } = useUploadStore()
|
||||
const { user, logout } = useAuthStore()
|
||||
```
|
||||
|
||||
### 調用 API
|
||||
```typescript
|
||||
const data = await apiClient.uploadFiles(files)
|
||||
const status = await apiClient.getBatchStatus(batchId)
|
||||
```
|
||||
|
||||
### React Query 查詢
|
||||
```typescript
|
||||
const { data, isLoading } = useQuery({
|
||||
queryKey: ['key', id],
|
||||
queryFn: () => apiClient.getData(id),
|
||||
})
|
||||
```
|
||||
|
||||
### Tailwind 樣式
|
||||
```typescript
|
||||
className="flex items-center justify-between p-4 bg-card rounded-lg"
|
||||
className={cn('base', { 'conditional': isActive })}
|
||||
```
|
||||
|
||||
### 提示通知
|
||||
```typescript
|
||||
const { toast } = useToast()
|
||||
toast({
|
||||
title: 'Success',
|
||||
description: 'Action completed',
|
||||
variant: 'success',
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 調試技巧
|
||||
|
||||
### 查看存儲在 localStorage 的狀態
|
||||
```javascript
|
||||
// 在瀏覽器控制台
|
||||
console.log(JSON.parse(localStorage.getItem('auth-storage')))
|
||||
console.log(JSON.parse(localStorage.getItem('tool-ocr-upload-store')))
|
||||
```
|
||||
|
||||
### 查看 React Query 緩存
|
||||
```javascript
|
||||
// 在瀏覽器控制台安裝 React Query DevTools
|
||||
// npm install @tanstack/react-query-devtools
|
||||
```
|
||||
|
||||
### TypeScript 錯誤
|
||||
```bash
|
||||
# 運行編譯器檢查類型
|
||||
npx tsc --noEmit
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 環境變數配置
|
||||
|
||||
### 開發環境 (.env)
|
||||
```env
|
||||
VITE_API_BASE_URL=http://localhost:12010
|
||||
```
|
||||
|
||||
### 使用環境變數
|
||||
```typescript
|
||||
const baseURL = import.meta.env.VITE_API_BASE_URL
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 常見問題
|
||||
|
||||
### Q: 如何添加新的頁面？
|
||||
A:
|
||||
1. 在 `/src/pages` 創建 `NewPage.tsx`
|
||||
2. 在 `App.tsx` 添加路由
|
||||
3. 在 Layout.tsx 導航中添加鏈接
|
||||
|
||||
### Q: 如何修改主題顏色？
|
||||
A:
|
||||
1. 編輯 `src/index.css` 中的 CSS 變數
|
||||
2. 或編輯 `tailwind.config.js`
|
||||
|
||||
### Q: 如何添加新的翻譯？
|
||||
A:
|
||||
1. 編輯 `src/i18n/locales/zh-TW.json`
|
||||
2. 在組件中使用 `t('key.path')`
|
||||
|
||||
### Q: 如何調試 API 請求？
|
||||
A:
|
||||
1. 打開瀏覽器開發者工具 (Network 標籤)
|
||||
2. 檢查 `/api/v1/` 的請求
|
||||
|
||||
### Q: 上傳文件怎樣無法工作？
|
||||
A:
|
||||
1. 檢查後端是否在運行 (localhost:12010)
|
||||
2. 檢查文件格式是否被支持
|
||||
3. 檢查文件大小是否超過 50MB
|
||||
|
||||
### Q: 認證登錄失敗？
|
||||
A:
|
||||
1. 檢查用戶名和密碼
|
||||
2. 檢查後端認證端點 `/api/v1/auth/login`
|
||||
3. 檢查 localStorage 中的 token
|
||||
|
||||
---
|
||||
|
||||
## 依賴更新
|
||||
|
||||
```bash
|
||||
# 檢查過期依賴
|
||||
npm outdated
|
||||
|
||||
# 更新依賴
|
||||
npm update
|
||||
|
||||
# 更新到最新版本
|
||||
npm install --save-latest package-name
|
||||
|
||||
# 清除 node_modules 並重新安裝
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 性能優化
|
||||
|
||||
### 代碼分割
|
||||
```typescript
|
||||
import { lazy, Suspense } from 'react'
|
||||
|
||||
const NewPage = lazy(() => import('./pages/NewPage'))
|
||||
|
||||
// 在 Routes 中
|
||||
<Suspense fallback={<div>Loading...</div>}>
|
||||
<NewPage />
|
||||
</Suspense>
|
||||
```
|
||||
|
||||
### 優化 React Query
|
||||
```typescript
|
||||
const { data } = useQuery({
|
||||
queryKey: ['items'],
|
||||
queryFn: () => apiClient.getItems(),
|
||||
staleTime: 1000 * 60 * 5, // 5 分鐘內不重新獲取
|
||||
gcTime: 1000 * 60 * 10, // 10 分鐘後從緩存中移除
|
||||
})
|
||||
```
|
||||
|
||||
### 優化組件
|
||||
```typescript
|
||||
// 使用 React.memo 避免不必要的重新渲染
|
||||
export default React.memo(function MyComponent(props) {
|
||||
return <div>{props.data}</div>
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 測試 (可選)
|
||||
|
||||
```bash
|
||||
# 安裝測試工具
|
||||
npm install -D vitest @testing-library/react
|
||||
|
||||
# 運行測試
|
||||
npm test
|
||||
|
||||
# 生成覆蓋率報告
|
||||
npm test -- --coverage
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 構建和部署
|
||||
|
||||
```bash
|
||||
# 生產構建
|
||||
npm run build
|
||||
|
||||
# 預覽構建
|
||||
npm run preview
|
||||
|
||||
# 構建後的文件位置
|
||||
# dist/
|
||||
|
||||
# 部署
|
||||
# 將 dist/ 目錄上傳到服務器
|
||||
# 配置 Web 服務器支持 SPA (所有路由都指向 index.html)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 貢獻指南
|
||||
|
||||
### 代碼風格
|
||||
- 使用 TypeScript 進行類型安全
|
||||
- 遵循現有的命名約定
|
||||
- 優先使用 Tailwind CSS
|
||||
- 添加必要的類型定義
|
||||
|
||||
### 提交代碼
|
||||
```bash
|
||||
# 檢查代碼
|
||||
npm run lint
|
||||
|
||||
# 提交
|
||||
git add .
|
||||
git commit -m "description of changes"
|
||||
git push
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 有用的資源
|
||||
|
||||
### 文檔
|
||||
- [React 文檔](https://react.dev)
|
||||
- [Tailwind CSS](https://tailwindcss.com)
|
||||
- [React Router](https://reactrouter.com)
|
||||
- [Zustand](https://github.com/pmndrs/zustand)
|
||||
- [React Query](https://tanstack.com/query)
|
||||
- [i18next](https://www.i18next.com)
|
||||
|
||||
### 工具
|
||||
- [Vite 文檔](https://vitejs.dev)
|
||||
- [TypeScript 文檔](https://www.typescriptlang.org)
|
||||
- [ESLint 文檔](https://eslint.org)
|
||||
|
||||
### IDE 擴展 (VS Code)
|
||||
- Tailwind CSS IntelliSense
|
||||
- Thunder Client (API 測試)
|
||||
- React Developer Tools
|
||||
- Redux DevTools (狀態檢查)
|
||||
|
||||
---
|
||||
|
||||
## 快速開始
|
||||
|
||||
```bash
|
||||
# 1. 進入前端目錄
|
||||
cd /Users/egg/Projects/Tool_OCR/frontend
|
||||
|
||||
# 2. 安裝依賴
|
||||
npm install
|
||||
|
||||
# 3. 啟動開發服務器
|
||||
npm run dev
|
||||
|
||||
# 4. 打開瀏覽器
|
||||
# 訪問 http://localhost:12011
|
||||
|
||||
# 5. 登錄
|
||||
# 使用後端提供的帳號密碼
|
||||
|
||||
# 6. 開始使用
|
||||
# 上傳檔案 → 處理 → 查看結果 → 匯出
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 常用快捷鍵
|
||||
|
||||
### VS Code
|
||||
- `Ctrl+Shift+F` (或 `Cmd+Shift+F` 在 Mac) - 全文搜索
|
||||
- `Ctrl+K Ctrl+X` - 刪除行
|
||||
- `Alt+Up/Down` - 移動行
|
||||
- `Ctrl+/` - 註解行
|
||||
|
||||
### 瀏覽器開發者工具
|
||||
- `F12` 或 `Ctrl+Shift+I` - 打開開發者工具
|
||||
- `Ctrl+Shift+C` - 元素檢查器
|
||||
- `Ctrl+Shift+M` - 響應式設計模式
|
||||
|
||||
---
|
||||
|
||||
## 總結速記
|
||||
|
||||
**架構**：React 19 + TypeScript + Vite
|
||||
**樣式**：Tailwind CSS 4
|
||||
**狀態**：Zustand (輕量) + React Query (數據)
|
||||
**路由**：React Router v7
|
||||
**API**：Axios 單例客戶端
|
||||
**國際化**：i18next (繁體中文)
|
||||
**開發端口**：12011
|
||||
**後端 API**：localhost:12010
|
||||
|
||||
**核心文件**：
|
||||
- App.tsx (路由)
|
||||
- main.tsx (入口)
|
||||
- services/api.ts (API)
|
||||
- store/*.ts (狀態)
|
||||
- pages/ (頁面)
|
||||
- components/ (組件)
|
||||
|
||||
Reference in New Issue
Block a user