281 lines
6.4 KiB
Markdown
281 lines
6.4 KiB
Markdown
# PANJIT Document Translator
|
||
|
||
企業級文件翻譯管理系統，提供 Web 化介面，支援多語言文件翻譯、使用者權限管理、任務排隊處理及成本追蹤功能。
|
||
|
||
## 功能特色
|
||
|
||
- 🔐 **LDAP 認證**：整合公司 AD 帳號系統
|
||
- 📄 **多格式支援**：支援 DOCX、PDF、PPTX、XLSX 等格式
|
||
- 🌐 **多語言翻譯**：支援 12+ 種語言互譯
|
||
- ⚡ **非同步處理**：使用 Celery 任務佇列
|
||
- 💰 **成本追蹤**：即時記錄 API 使用成本
|
||
- 📊 **統計報表**：完整的使用量分析和圖表展示
|
||
- 📧 **通知系統**：SMTP 郵件通知
|
||
- 🛡️ **權限管理**：使用者資料隔離
|
||
- 🔍 **即時監控**：系統健康狀態檢查
|
||
- 🎯 **管理後台**：完整的管理員功能和報表匯出
|
||
- 📱 **響應式設計**：支援桌面和行動裝置
|
||
- 🔄 **組合翻譯**：多語言組合檔案輸出
|
||
|
||
## 技術架構
|
||
|
||
### 後端
|
||
- **Python 3.8+** - 主要開發語言
|
||
- **Flask 3.0** - Web 框架
|
||
- **SQLAlchemy** - ORM 資料庫操作
|
||
- **Celery** - 非同步任務處理
|
||
- **Redis** - 快取與訊息佇列
|
||
- **MySQL** - 主要資料庫
|
||
- **LDAP3** - AD 認證
|
||
|
||
### 前端
|
||
- **Vue 3** - 前端框架 (Composition API)
|
||
- **Element Plus** - UI 組件庫
|
||
- **Vite** - 建置工具
|
||
- **Pinia** - 狀態管理
|
||
- **Vue Router** - 路由管理
|
||
- **ECharts** - 數據圖表
|
||
|
||
## 快速開始
|
||
|
||
### 環境需求
|
||
|
||
- Python 3.8 或更高版本
|
||
- Redis Server
|
||
- MySQL Server（使用現有環境）
|
||
- Git
|
||
|
||
### 安裝步驟
|
||
|
||
1. **下載專案**
|
||
```bash
|
||
cd C:\Users\EGG\WORK\data\user_scrip\TOOL\Document_translator_V2
|
||
```
|
||
|
||
2. **配置環境變數**
|
||
```bash
|
||
copy .env.example .env
|
||
# 編輯 .env 檔案設定您的環境變數
|
||
```
|
||
|
||
3. **建立 API 配置檔案**
|
||
```bash
|
||
# 建立 api.txt 檔案並設定 Dify API
|
||
echo base_url:YOUR_DIFY_API_BASE_URL > api.txt
|
||
echo api:YOUR_DIFY_API_KEY >> api.txt
|
||
```
|
||
|
||
4. **啟動開發環境**
|
||
```bash
|
||
# Windows - 後端
|
||
start_dev.bat
|
||
|
||
# 或手動啟動後端
|
||
python -m venv venv
|
||
venv\Scripts\activate
|
||
pip install -r requirements.txt
|
||
python app.py
|
||
```
|
||
|
||
5. **啟動前端**（另開視窗）
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
npm run dev
|
||
|
||
# 或使用提供的腳本
|
||
start_frontend.bat
|
||
```
|
||
|
||
6. **啟動 Celery Worker**（另開視窗）
|
||
```bash
|
||
venv\Scripts\activate
|
||
celery -A celery_app worker --loglevel=info --pool=solo
|
||
```
|
||
|
||
### 系統訪問
|
||
|
||
- **前端界面**: http://127.0.0.1:5173 (開發)
|
||
- **後端 API**: http://127.0.0.1:5000
|
||
- **API 文檔**: http://127.0.0.1:5000/api
|
||
- **健康檢查**: http://127.0.0.1:5000/api/v1/health
|
||
|
||
## API 文檔
|
||
|
||
### 認證相關
|
||
|
||
| 端點 | 方法 | 描述 | 認證 |
|
||
|------|------|------|------|
|
||
| `/api/v1/auth/login` | POST | 使用者登入 | - |
|
||
| `/api/v1/auth/logout` | POST | 使用者登出 | ✓ |
|
||
| `/api/v1/auth/me` | GET | 取得當前使用者 | ✓ |
|
||
|
||
### 檔案管理
|
||
|
||
| 端點 | 方法 | 描述 | 認證 |
|
||
|------|------|------|------|
|
||
| `/api/v1/files/upload` | POST | 上傳檔案 | ✓ |
|
||
| `/api/v1/files/{uuid}/download/{lang}` | GET | 下載翻譯檔案 | ✓ |
|
||
| `/api/v1/files/supported-formats` | GET | 支援的檔案格式 | - |
|
||
|
||
### 任務管理
|
||
|
||
| 端點 | 方法 | 描述 | 認證 |
|
||
|------|------|------|------|
|
||
| `/api/v1/jobs` | GET | 取得任務列表 | ✓ |
|
||
| `/api/v1/jobs/{uuid}` | GET | 任務詳細資訊 | ✓ |
|
||
| `/api/v1/jobs/{uuid}/retry` | POST | 重試失敗任務 | ✓ |
|
||
|
||
### 管理功能
|
||
|
||
| 端點 | 方法 | 描述 | 認證 |
|
||
|------|------|------|------|
|
||
| `/api/v1/admin/stats` | GET | 系統統計 | 管理員 |
|
||
| `/api/v1/admin/jobs` | GET | 所有任務 | 管理員 |
|
||
| `/api/v1/admin/users` | GET | 使用者列表 | 管理員 |
|
||
| `/api/v1/admin/health` | GET | 系統健康狀態 | 管理員 |
|
||
| `/api/v1/admin/export/{type}` | GET | 報表匯出 | 管理員 |
|
||
|
||
## 測試
|
||
|
||
### 執行測試
|
||
|
||
```bash
|
||
# Windows
|
||
run_tests.bat
|
||
|
||
# 或手動執行
|
||
pytest tests/ -v
|
||
pytest tests/ --cov=app --cov-report=html
|
||
```
|
||
|
||
### 測試覆蓋率
|
||
|
||
測試覆蓋率報告會生成到 `htmlcov/index.html`，目標覆蓋率 > 80%。
|
||
|
||
## 資料庫結構
|
||
|
||
### 主要資料表
|
||
|
||
- `dt_users` - 使用者資訊
|
||
- `dt_translation_jobs` - 翻譯任務
|
||
- `dt_job_files` - 檔案記錄
|
||
- `dt_translation_cache` - 翻譯快取
|
||
- `dt_api_usage_stats` - API 使用統計
|
||
- `dt_system_logs` - 系統日誌
|
||
|
||
## 部署指南
|
||
|
||
### 開發環境
|
||
|
||
使用提供的 `start_dev.bat` 腳本快速啟動開發環境。
|
||
|
||
### 生產環境
|
||
|
||
1. **安裝 Gunicorn**
|
||
```bash
|
||
pip install gunicorn
|
||
```
|
||
|
||
2. **配置環境變數**
|
||
```bash
|
||
export FLASK_ENV=production
|
||
export DATABASE_URL=your_production_db_url
|
||
```
|
||
|
||
3. **啟動應用程式**
|
||
```bash
|
||
gunicorn -w 4 -b 0.0.0.0:5000 app:app
|
||
```
|
||
|
||
4. **啟動 Celery**
|
||
```bash
|
||
celery -A app.celery worker -D
|
||
celery -A app.celery beat -D
|
||
```
|
||
|
||
## 監控與維護
|
||
|
||
### 健康檢查
|
||
|
||
系統提供完整的健康檢查端點：
|
||
|
||
- **基本檢查**: `/api/v1/health/ping`
|
||
- **完整檢查**: `/api/v1/health`
|
||
- **系統指標**: `/api/v1/health/metrics`
|
||
|
||
### 日誌管理
|
||
|
||
- **應用日誌**: `logs/app.log`
|
||
- **系統日誌**: 儲存在資料庫 `dt_system_logs` 表
|
||
- **日誌等級**: DEBUG, INFO, WARNING, ERROR, CRITICAL
|
||
|
||
### 自動清理
|
||
|
||
系統會自動執行以下清理任務：
|
||
|
||
- **每日凌晨 2 點**: 清理 7 天以上的舊檔案
|
||
- **每日早上 8 點**: 發送管理員報告
|
||
- **手動清理**: 通過管理員 API 執行
|
||
|
||
## 安全性
|
||
|
||
- ✅ LDAP 認證整合
|
||
- ✅ 使用者工作隔離
|
||
- ✅ 檔案權限控制
|
||
- ✅ SQL 注入防護
|
||
- ✅ 速率限制
|
||
- ✅ 敏感資料保護
|
||
|
||
## 故障排除
|
||
|
||
### 常見問題
|
||
|
||
1. **Redis 連線失敗**
|
||
- 檢查 Redis 服務是否運行
|
||
- 確認 `REDIS_URL` 設定正確
|
||
|
||
2. **LDAP 認證失敗**
|
||
- 檢查 LDAP 設定參數
|
||
- 確認網路連線正常
|
||
|
||
3. **檔案上傳失敗**
|
||
- 檢查 `UPLOAD_FOLDER` 權限
|
||
- 確認檔案大小限制
|
||
|
||
4. **翻譯任務卡住**
|
||
- 檢查 Celery Worker 狀態
|
||
- 查看 Dify API 連線
|
||
|
||
### 除錯模式
|
||
|
||
```bash
|
||
export FLASK_DEBUG=true
|
||
export LOG_LEVEL=DEBUG
|
||
python app.py
|
||
```
|
||
|
||
## 貢獻指南
|
||
|
||
1. Fork 專案
|
||
2. 建立功能分支
|
||
3. 提交變更
|
||
4. 執行測試
|
||
5. 建立 Pull Request
|
||
|
||
## 授權條款
|
||
|
||
本專案僅供 PANJIT 公司內部使用。
|
||
|
||
## 聯繫資訊
|
||
|
||
- **開發團隊**: PANJIT IT Team
|
||
- **維護人員**: System Administrator
|
||
- **問題回報**: 請聯繫系統管理員
|
||
|
||
---
|
||
|
||
**版本**: 2.0.0
|
||
**建立日期**: 2024-01-28
|
||
**最後更新**: 2025-09-03
|
||
**狀態**: 生產就緒 |