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. 下載專案

   cd C:\Users\EGG\WORK\data\user_scrip\TOOL\Document_translator_V2
   

2. 配置環境變數

   copy .env.example .env
   # 編輯 .env 檔案設定您的環境變數
   

3. 建立 API 配置檔案

   # 建立 api.txt 檔案並設定 Dify API
   echo base_url:YOUR_DIFY_API_BASE_URL > api.txt
   echo api:YOUR_DIFY_API_KEY >> api.txt
   

4. 啟動開發環境

   # Windows - 後端
   start_dev.bat
   
   # 或手動啟動後端
   python -m venv venv
   venv\Scripts\activate
   pip install -r requirements.txt
   python app.py
   

5. 啟動前端（另開視窗）

   cd frontend
   npm install
   npm run dev
   
   # 或使用提供的腳本
   start_frontend.bat
   

6. 啟動 Celery Worker（另開視窗）

   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	報表匯出	管理員

測試

執行測試

# 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

   pip install gunicorn
   

2. 配置環境變數

   export FLASK_ENV=production
   export DATABASE_URL=your_production_db_url
   

3. 啟動應用程式

   gunicorn -w 4 -b 0.0.0.0:5000 app:app
   

4. 啟動 Celery

   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 連線

除錯模式

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
狀態: 生產就緒