# 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