# Tool_OCR V2 API (現況)

Base URL：`http://localhost:${BACKEND_PORT:-8000}/api/v2`  
認證：所有業務端點需 Bearer Token（JWT）。

## 認證
- `POST /auth/login`：{ username, password } → `access_token`, `expires_in`, `user`.
- `POST /auth/logout`：可傳 `session_id`，未傳則登出全部。
- `GET /auth/me`：目前使用者資訊。
- `GET /auth/sessions`：列出登入 Session。
- `POST /auth/refresh`：刷新 access token。

## 任務流程摘要
1) 上傳檔案 → `POST /upload` (multipart file) 取得 `task_id`。  
2) 啟動處理 → `POST /tasks/{task_id}/start`（ProcessingOptions 可控制 dual track、force_track、layout/預處理/table 偵測）。  
3) 查詢狀態與 metadata → `GET /tasks/{task_id}`、`/metadata`。  
4) 下載結果 → `/download/json | /markdown | /pdf | /unified`。  
5) 進階：`/analyze` 先看推薦軌道；`/preview/preprocessing` 取得預處理前後預覽。

## 核心端點
- `POST /upload`  
  - 表單欄位：`file` (必填)；驗證副檔名於允許清單。  
  - 回傳：`task_id`, `filename`, `file_size`, `file_type`, `status` (pending)。
- `POST /tasks/`  
  - 僅建立 Task meta（不含檔案），通常不需使用。
- `POST /tasks/{task_id}/start`  
  - Body `ProcessingOptions`：`use_dual_track`(default true), `force_track`(ocr|direct), `language`(default ch), `layout_model`(chinese|default|cdla), `preprocessing_mode`(auto|manual|disabled) + `preprocessing_config`, `table_detection`.
- `POST /tasks/{task_id}/cancel`、`POST /tasks/{task_id}/retry`。
- `GET /tasks`  
  - 查詢參數：`status`(pending|processing|completed|failed)、`filename`、`date_from`/`date_to`、`page`、`page_size`、`order_by`、`order_desc`。
- `GET /tasks/{task_id}`：詳細資料與路徑、處理軌道、統計。  
- `GET /tasks/stats`：當前使用者任務統計。  
- `POST /tasks/{task_id}/analyze`：預先分析文件並給出推薦軌道/信心/文件類型/抽樣統計。  
- `GET /tasks/{task_id}/metadata`：處理結果的統計與說明。  
- 下載：  
  - `GET /tasks/{task_id}/download/json`  
  - `GET /tasks/{task_id}/download/markdown`  
  - `GET /tasks/{task_id}/download/pdf`（若無 PDF 則即時生成）  
  - `GET /tasks/{task_id}/download/unified`（UnifiedDocument JSON）
- 預處理預覽：  
  - `POST /tasks/{task_id}/preview/preprocessing`（body：page/mode/config）  
  - `GET /tasks/{task_id}/preview/image?type=original|preprocessed&page=1`

## 翻譯（需已完成 OCR）
Prefix：`/translate`
- `POST /{task_id}`：開始翻譯，body `{ target_lang, source_lang }`，回傳 202。若已存在會直接回 Completed。  
- `GET /{task_id}/status`：翻譯進度。  
- `GET /{task_id}/result?lang=xx`：翻譯 JSON。  
- `GET /{task_id}/translations`：列出已產生的翻譯。  
- `DELETE /{task_id}/translations/{lang}`：刪除翻譯。  
- `POST /{task_id}/pdf?lang=xx`：下載翻譯後版面保持 PDF。

## 管理端（需要管理員）
Prefix：`/admin`
- `GET /stats`：系統層統計。  
- `GET /users`、`GET /users/top`。  
- `GET /audit-logs`、`GET /audit-logs/user/{user_id}/summary`。

## 健康檢查
- `/health`：服務狀態、GPU/Memory 管理資訊。  
- `/`：簡易 API 入口說明。

## 回應結構摘要
- Task 回應常見欄位：`task_id`, `status`, `processing_track`, `document_type`, `processing_time_ms`, `page_count`, `element_count`, `file_size`, `mime_type`, `result_json_path` 等。  
- 下載端點皆以檔案回應（Content-Disposition 附檔名）。  
- 錯誤格式：`{ "detail": "...", "error_code": "...", "timestamp": "..." }`（部分錯誤僅有 `detail`）。

## 使用範例
上傳並啟動：
```bash
# 上傳
curl -X POST "http://localhost:8000/api/v2/upload" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@demo_docs/edit.pdf"

# 啟動處理（force_track=ocr 舉例）
curl -X POST "http://localhost:8000/api/v2/tasks/$TASK_ID/start" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"force_track":"ocr","language":"ch"}'

# 查詢與下載
curl -X GET "http://localhost:8000/api/v2/tasks/$TASK_ID/metadata" -H "Authorization: Bearer $TOKEN"
curl -L "http://localhost:8000/api/v2/tasks/$TASK_ID/download/json" -H "Authorization: Bearer $TOKEN" -o result.json
```

翻譯並下載翻譯 PDF：
```bash
curl -X POST "http://localhost:8000/api/v2/translate/$TASK_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target_lang":"en","source_lang":"auto"}'

curl -X GET "http://localhost:8000/api/v2/translate/$TASK_ID/status" -H "Authorization: Bearer $TOKEN"
curl -L "http://localhost:8000/api/v2/translate/$TASK_ID/pdf?lang=en" \
  -H "Authorization: Bearer $TOKEN" -o translated.pdf
```