305 lines
7.4 KiB
Markdown
305 lines
7.4 KiB
Markdown
# PANJIT Document Translator - 前端系統
|
|
|
|
## 系統概述
|
|
|
|
本系統是 PANJIT 企業級文件翻譯管理系統的前端部分，基於 Vue 3 + Vite + Element Plus 開發，提供現代化的 Web 界面用於文件翻譯任務管理。
|
|
|
|
## 技術架構
|
|
|
|
### 核心技術
|
|
- **框架**: Vue 3.3+ (Composition API)
|
|
- **建構工具**: Vite 4.0+
|
|
- **UI 框架**: Element Plus 2.3+
|
|
- **狀態管理**: Pinia 2.0+
|
|
- **路由管理**: Vue Router 4.0+
|
|
- **HTTP 客戶端**: Axios 1.0+
|
|
- **圖表庫**: ECharts 5.4+
|
|
- **WebSocket**: Socket.IO Client 4.7+
|
|
|
|
### 開發工具
|
|
- **代碼檢查**: ESLint + Prettier
|
|
- **樣式預處理**: Sass (SCSS)
|
|
- **自動導入**: unplugin-auto-import
|
|
- **組件自動導入**: unplugin-vue-components
|
|
|
|
## 項目結構
|
|
|
|
```
|
|
frontend/
|
|
├── public/ # 靜態資源
|
|
├── src/
|
|
│ ├── components/ # 可複用組件
|
|
│ ├── layouts/ # 佈局組件
|
|
│ ├── views/ # 頁面組件
|
|
│ │ ├── LoginView.vue # 登入頁面
|
|
│ │ ├── HomeView.vue # 首頁
|
|
│ │ ├── UploadView.vue # 檔案上傳
|
|
│ │ ├── JobListView.vue # 任務列表
|
|
│ │ ├── JobDetailView.vue # 任務詳情
|
|
│ │ ├── HistoryView.vue # 歷史記錄
|
|
│ │ ├── ProfileView.vue # 個人設定
|
|
│ │ ├── AdminView.vue # 管理後台
|
|
│ │ └── NotFoundView.vue # 404 頁面
|
|
│ ├── stores/ # Pinia 狀態管理
|
|
│ │ ├── auth.js # 認證狀態
|
|
│ │ ├── jobs.js # 任務狀態
|
|
│ │ └── admin.js # 管理員狀態
|
|
│ ├── services/ # API 服務
|
|
│ │ ├── auth.js # 認證 API
|
|
│ │ ├── jobs.js # 任務 API
|
|
│ │ └── admin.js # 管理員 API
|
|
│ ├── utils/ # 工具函數
|
|
│ │ ├── request.js # HTTP 請求封裝
|
|
│ │ └── websocket.js # WebSocket 服務
|
|
│ ├── style/ # 全局樣式
|
|
│ │ ├── main.scss # 主樣式文件
|
|
│ │ ├── variables.scss # SCSS 變數
|
|
│ │ ├── mixins.scss # SCSS 混合器
|
|
│ │ ├── components.scss # 組件樣式
|
|
│ │ └── layouts.scss # 佈局樣式
|
|
│ ├── router/ # 路由配置
|
|
│ ├── App.vue # 根組件
|
|
│ └── main.js # 應用入口
|
|
├── package.json # 項目配置
|
|
├── vite.config.js # Vite 配置
|
|
├── .eslintrc.js # ESLint 配置
|
|
└── .prettierrc # Prettier 配置
|
|
```
|
|
|
|
## 快速開始
|
|
|
|
### 環境需求
|
|
- Node.js 16.0+
|
|
- npm 8.0+ 或 yarn 1.22+
|
|
|
|
### 安裝與啟動
|
|
|
|
1. **安裝依賴**
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
```
|
|
|
|
2. **啟動開發服務器**
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
3. **使用啟動腳本 (Windows)**
|
|
```bash
|
|
# 從項目根目錄執行
|
|
start_frontend.bat
|
|
```
|
|
|
|
### 建構生產版本
|
|
|
|
1. **建構命令**
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
2. **使用建構腳本 (Windows)**
|
|
```bash
|
|
# 從項目根目錄執行
|
|
build_frontend.bat
|
|
```
|
|
|
|
3. **預覽建構結果**
|
|
```bash
|
|
npm run preview
|
|
```
|
|
|
|
## 核心功能
|
|
|
|
### 1. 使用者認證
|
|
- AD 帳號登入
|
|
- Session 管理
|
|
- 權限驗證 (一般使用者/管理員)
|
|
|
|
### 2. 檔案上傳
|
|
- 拖拽上傳支援
|
|
- 多檔案批量上傳
|
|
- 檔案格式驗證 (.docx, .doc, .pptx, .xlsx, .xls, .pdf)
|
|
- 檔案大小限制 (25MB)
|
|
- 即時上傳進度顯示
|
|
|
|
### 3. 任務管理
|
|
- 任務列表查看
|
|
- 任務狀態篩選
|
|
- 任務詳情查看
|
|
- 即時狀態更新 (WebSocket)
|
|
- 檔案下載
|
|
|
|
### 4. 管理員功能
|
|
- 系統統計面板
|
|
- 使用者管理
|
|
- 成本報表
|
|
- 系統監控
|
|
- 資料匯出
|
|
|
|
### 5. 個人設定
|
|
- 個人資料管理
|
|
- 翻譯偏好設定
|
|
- 使用統計查看
|
|
|
|
## 關鍵特性
|
|
|
|
### WebSocket 即時更新
|
|
系統使用 WebSocket 技術實現任務狀態的即時更新：
|
|
- 自動訂閱任務狀態變化
|
|
- 即時進度更新
|
|
- 完成通知提醒
|
|
|
|
### 響應式設計
|
|
- 支援桌面、平板、手機多種設備
|
|
- 使用 CSS Grid 和 Flexbox 佈局
|
|
- 適配 Element Plus 組件斷點
|
|
|
|
### 狀態管理
|
|
使用 Pinia 進行全局狀態管理：
|
|
- 使用者認證狀態
|
|
- 任務列表狀態
|
|
- 管理員數據狀態
|
|
|
|
### API 集成
|
|
- 統一的 HTTP 請求封裝
|
|
- 自動錯誤處理
|
|
- 請求攔截器和響應攔截器
|
|
- 檔案上傳進度追蹤
|
|
|
|
## 開發規範
|
|
|
|
### 程式碼風格
|
|
- 使用 ESLint + Prettier 確保代碼一致性
|
|
- Vue 3 Composition API 風格
|
|
- 單檔案組件 (.vue)
|
|
- TypeScript 型別註釋 (漸進式)
|
|
|
|
### 命名規範
|
|
- 組件名: PascalCase (如: `FileUploader.vue`)
|
|
- 檔案名: kebab-case (如: `job-list-view.vue`)
|
|
- 變數名: camelCase
|
|
- 常數名: UPPER_SNAKE_CASE
|
|
|
|
### 組件開發
|
|
- 使用 Composition API
|
|
- 響應式資料使用 `ref` 和 `reactive`
|
|
- 邏輯抽取到 composables
|
|
- 適當的組件拆分
|
|
|
|
## 環境配置
|
|
|
|
### 開發環境變數 (.env)
|
|
```
|
|
VITE_APP_TITLE=PANJIT Document Translator
|
|
VITE_API_BASE_URL=http://127.0.0.1:5000/api/v1
|
|
VITE_WS_BASE_URL=ws://127.0.0.1:5000
|
|
VITE_MAX_FILE_SIZE=26214400
|
|
```
|
|
|
|
### 生產環境配置
|
|
- 修改 API 地址指向生產服務器
|
|
- 啟用 HTTPS
|
|
- 配置適當的快取策略
|
|
|
|
## 部署說明
|
|
|
|
### Nginx 配置範例
|
|
```nginx
|
|
server {
|
|
listen 80;
|
|
server_name your-domain.com;
|
|
|
|
root /path/to/frontend/dist;
|
|
index index.html;
|
|
|
|
# 處理 Vue Router 的 history 模式
|
|
location / {
|
|
try_files $uri $uri/ /index.html;
|
|
}
|
|
|
|
# 代理 API 請求
|
|
location /api/ {
|
|
proxy_pass http://127.0.0.1:5000;
|
|
proxy_set_header Host $host;
|
|
proxy_set_header X-Real-IP $remote_addr;
|
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
}
|
|
|
|
# WebSocket 支援
|
|
location /socket.io/ {
|
|
proxy_pass http://127.0.0.1:5000;
|
|
proxy_http_version 1.1;
|
|
proxy_set_header Upgrade $http_upgrade;
|
|
proxy_set_header Connection "upgrade";
|
|
}
|
|
|
|
# 靜態資源快取
|
|
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
|
|
expires 1y;
|
|
add_header Cache-Control "public, immutable";
|
|
}
|
|
}
|
|
```
|
|
|
|
## 效能優化
|
|
|
|
### 建構優化
|
|
- 代碼分割 (Code Splitting)
|
|
- Tree Shaking
|
|
- 資源壓縮
|
|
- 圖片優化
|
|
|
|
### 運行時優化
|
|
- 虛擬滾動 (大列表)
|
|
- 懶加載 (Lazy Loading)
|
|
- 組件快取
|
|
- 防抖節流處理
|
|
|
|
## 故障排除
|
|
|
|
### 常見問題
|
|
|
|
1. **依賴安裝失敗**
|
|
- 檢查 Node.js 版本 (需要 16+)
|
|
- 清除 npm 快取: `npm cache clean --force`
|
|
- 刪除 node_modules 重新安裝
|
|
|
|
2. **開發服務器啟動失敗**
|
|
- 檢查端口 3000 是否被占用
|
|
- 檢查 .env 配置是否正確
|
|
|
|
3. **API 請求失敗**
|
|
- 確認後端服務是否正常運行
|
|
- 檢查 CORS 設定
|
|
- 檢查網路連接
|
|
|
|
4. **WebSocket 連接失敗**
|
|
- 確認後端 WebSocket 服務是否啟用
|
|
- 檢查防火牆設定
|
|
- 檢查代理配置
|
|
|
|
## 更新日誌
|
|
|
|
### v1.0.0 (2024-01-28)
|
|
- 初始版本發布
|
|
- 完整的前端功能實現
|
|
- 響應式設計支援
|
|
- WebSocket 即時更新
|
|
- 完善的錯誤處理
|
|
|
|
## 技術支援
|
|
|
|
如遇到技術問題，請聯繫：
|
|
- **開發團隊**: PANJIT IT Team
|
|
- **郵箱**: ymirliu@panjit.com.tw
|
|
|
|
## 授權聲明
|
|
|
|
本系統僅供 PANJIT 公司內部使用，不得用於商業用途或對外分發。
|
|
|
|
---
|
|
|
|
**更新時間**: 2024-01-28
|
|
**版本**: v1.0.0
|
|
**維護團隊**: PANJIT IT Team |