# 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** - 前端框架
- **Element Plus** - UI 組件庫
- **Vite** - 建置工具

## 快速開始

### 環境需求

- 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. **啟動 Celery Worker**（另開視窗）
   ```bash
   venv\Scripts\activate
   celery -A app.celery worker --loglevel=info --pool=solo
   ```

### 系統訪問

- **主應用程式**: 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 | 使用者列表 | 管理員 |

## 測試

### 執行測試

```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
- **問題回報**: 請聯繫系統管理員

---

**版本**: 1.0.0  
**建立日期**: 2024-01-28  
**最後更新**: 2024-01-28