feat: 新增 OCRmyPDF 轉換引擎 (v0.1.14)
## 新功能 - OCRmyPDF 轉換引擎:將掃描版 PDF 轉換為可搜尋 PDF - 支援 7 種語言:en, zh-TW, zh, ja, ko, de, fr - 與 PDFMathTranslate 風格一致的 UI 格式 (pdf-<lang>) - 自動偵測頁面方向並旋轉 - 自動校正傾斜 - 跳過已有文字層的頁面 - 詳細的 5 階段處理進度輸出 ## 建置 - Dockerfile:安裝 ocrmypdf 與 Tesseract OCR 語言包 ## 文件 - 更新 OCR 功能文件 - 文件目錄結構改為中文名稱 ## 測試 - 修復 BabelDOC 和 PDFMathTranslate 測試的 OCR mock - 所有 345 個測試通過
This commit is contained in:
parent
f24eec070c
commit
a06df23b1d
53 changed files with 1427 additions and 675 deletions
128
docs/API/總覽.md
Normal file
128
docs/API/總覽.md
Normal file
|
|
@ -0,0 +1,128 @@
|
|||
# API 總覽
|
||||
|
||||
ConvertX-CN 提供選用的 API Server,支援 REST 和 GraphQL 兩種 API 介面。
|
||||
|
||||
---
|
||||
|
||||
## 功能特色
|
||||
|
||||
- 🔐 **JWT 認證**:安全的 API 存取控制
|
||||
- 🌐 **REST + GraphQL**:雙協議支援
|
||||
- 🔍 **智慧建議**:轉換失敗時推薦替代引擎
|
||||
- 🛠️ **20+ 轉換引擎**:與 Web UI 共用完整轉換器
|
||||
|
||||
---
|
||||
|
||||
## 快速啟用
|
||||
|
||||
API Server 是**選用功能**,不影響 Web UI 使用。
|
||||
|
||||
### 啟用方式
|
||||
|
||||
```bash
|
||||
docker compose --profile api up -d
|
||||
```
|
||||
|
||||
### 服務端口
|
||||
|
||||
| 服務 | 端口 | 說明 |
|
||||
| ---------- | ---- | -------------- |
|
||||
| Web UI | 3000 | 網頁介面 |
|
||||
| API Server | 3001 | REST & GraphQL |
|
||||
|
||||
---
|
||||
|
||||
## API 端點
|
||||
|
||||
### REST API
|
||||
|
||||
- **Base URL**: `http://localhost:3001/api/v1`
|
||||
- **Content-Type**: `application/json` 或 `multipart/form-data`
|
||||
|
||||
### GraphQL API
|
||||
|
||||
- **Endpoint**: `http://localhost:3001/graphql`
|
||||
- **Playground**: `http://localhost:3001/graphql`(開發模式)
|
||||
|
||||
---
|
||||
|
||||
## 認證
|
||||
|
||||
所有 API 請求(除健康檢查外)都需要 JWT Bearer Token:
|
||||
|
||||
```http
|
||||
Authorization: Bearer <your-jwt-token>
|
||||
```
|
||||
|
||||
### Token 結構
|
||||
|
||||
```json
|
||||
{
|
||||
"sub": "user-id",
|
||||
"exp": 1234567890,
|
||||
"iat": 1234567890,
|
||||
"email": "user@example.com",
|
||||
"roles": ["user"]
|
||||
}
|
||||
```
|
||||
|
||||
> API Server 只負責驗證 JWT,不負責產生 JWT。Token 應由獨立的認證服務產生。
|
||||
|
||||
---
|
||||
|
||||
## 環境變數
|
||||
|
||||
| 變數 | 說明 | 預設值 |
|
||||
| --------------- | ------------ | ---------------- |
|
||||
| `API_HOST` | 監聽地址 | `0.0.0.0` |
|
||||
| `API_PORT` | 監聽埠 | `3001` |
|
||||
| `JWT_SECRET` | JWT 驗證密鑰 | (需自行設定) |
|
||||
| `UPLOAD_DIR` | 上傳目錄 | `./data/uploads` |
|
||||
| `OUTPUT_DIR` | 輸出目錄 | `./data/output` |
|
||||
| `MAX_FILE_SIZE` | 最大檔案大小 | `104857600` |
|
||||
|
||||
---
|
||||
|
||||
## 快速範例
|
||||
|
||||
### 健康檢查
|
||||
|
||||
```bash
|
||||
curl http://localhost:3001/health
|
||||
```
|
||||
|
||||
回應:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "healthy",
|
||||
"version": "0.1.0",
|
||||
"timestamp": "2026-01-23T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### 列出引擎
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: Bearer <token>" \
|
||||
http://localhost:3001/api/v1/engines
|
||||
```
|
||||
|
||||
### 轉換檔案
|
||||
|
||||
```bash
|
||||
curl -X POST \
|
||||
-H "Authorization: Bearer <token>" \
|
||||
-F "file=@document.docx" \
|
||||
-F "engine=libreoffice" \
|
||||
-F "output_format=pdf" \
|
||||
http://localhost:3001/api/v1/convert
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 相關文件
|
||||
|
||||
- [API 端點詳細說明](端點.md)
|
||||
- [API 規格文件](../../api-server/docs/API_SPEC.md)
|
||||
- [架構說明](../../api-server/docs/ARCHITECTURE.md)
|
||||
Loading…
Add table
Add a link
Reference in a new issue