398 lines
8.0 KiB
Markdown
398 lines
8.0 KiB
Markdown
# 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/ (組件)
|
||
|