# 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 中 } /> // 在導航中 { to: '/new-page', label: t('nav.newPage') } ``` --- ## 常用代碼片段 ### 使用 i18n 翻譯 ```typescript const { t } = useTranslation()

{t('key.path')}

``` ### 使用 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 中 Loading...}> ``` ### 優化 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
{props.data}
}) ``` --- ## 測試 (可選) ```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/ (組件)