feat(i18n): add multilingual support with translations for English, Japanese, and Simplified Chinese
- Create README.md for internationalization (i18n) documentation - Add English translation for main README and quick start guide - Add Japanese translation for main README - Add Simplified Chinese translation for main README - Introduce sample Docker Compose configurations for various deployment scenarios - Implement CI/CD documentation for testing and deployment workflows - Establish end-to-end testing guidelines and strategies - Create test strategy documentation outlining unit, integration, and E2E tests
This commit is contained in:
Your Name
parent
b3b382d1e0
commit
da856d89ff
42 changed files with 4901 additions and 263 deletions
261
docs/api/endpoints.md
Normal file
261
docs/api/endpoints.md
Normal file
|
|
@ -0,0 +1,261 @@
|
|||
# API 端點
|
||||
|
||||
本文件列出 ConvertX API Server 的所有可用端點。
|
||||
|
||||
---
|
||||
|
||||
## REST API
|
||||
|
||||
Base URL: `http://localhost:3001/api/v1`
|
||||
|
||||
---
|
||||
|
||||
### 健康檢查
|
||||
|
||||
#### `GET /health`
|
||||
|
||||
檢查 API Server 運作狀態。**不需要認證**。
|
||||
|
||||
**回應**
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "healthy",
|
||||
"version": "0.1.0",
|
||||
"timestamp": "2026-01-23T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 引擎管理
|
||||
|
||||
#### `GET /api/v1/engines`
|
||||
|
||||
列出所有可用的轉換引擎。
|
||||
|
||||
**Headers**
|
||||
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**回應**
|
||||
|
||||
```json
|
||||
{
|
||||
"engines": [
|
||||
{
|
||||
"id": "ffmpeg",
|
||||
"name": "FFmpeg",
|
||||
"description": "Audio and video conversion",
|
||||
"supported_input_formats": ["mp4", "webm", "avi", ...],
|
||||
"supported_output_formats": ["mp4", "webm", "mp3", ...]
|
||||
},
|
||||
...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### `GET /api/v1/engines/{engine_id}`
|
||||
|
||||
取得特定引擎的詳細資訊。
|
||||
|
||||
**參數**
|
||||
|
||||
| 參數 | 類型 | 說明 |
|
||||
| --------- | ------ | ------- |
|
||||
| engine_id | string | 引擎 ID |
|
||||
|
||||
**回應**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "libreoffice",
|
||||
"name": "LibreOffice",
|
||||
"description": "Office document conversion",
|
||||
"supported_input_formats": ["doc", "docx", "xls", ...],
|
||||
"supported_output_formats": ["pdf", "odt", "txt", ...]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 檔案轉換
|
||||
|
||||
#### `POST /api/v1/convert`
|
||||
|
||||
上傳檔案並執行轉換。
|
||||
|
||||
**Headers**
|
||||
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
**參數**
|
||||
|
||||
| 參數 | 類型 | 必填 | 說明 |
|
||||
| ------------- | ------ | ---- | ------------ |
|
||||
| file | file | ✓ | 要轉換的檔案 |
|
||||
| engine | string | ✓ | 轉換引擎 ID |
|
||||
| output_format | string | ✓ | 目標格式 |
|
||||
|
||||
**範例**
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
**成功回應**
|
||||
|
||||
```json
|
||||
{
|
||||
"job_id": "abc123",
|
||||
"status": "completed",
|
||||
"output_file": "http://localhost:3001/api/v1/files/abc123/output.pdf"
|
||||
}
|
||||
```
|
||||
|
||||
**失敗回應（含建議）**
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "UNSUPPORTED_CONVERSION",
|
||||
"message": "Engine 'ffmpeg' does not support .docx input",
|
||||
"suggestions": [
|
||||
{
|
||||
"engine": "libreoffice",
|
||||
"supported_output_formats": ["pdf", "odt", "txt"]
|
||||
},
|
||||
{
|
||||
"engine": "pandoc",
|
||||
"supported_output_formats": ["pdf", "html", "markdown"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 檔案下載
|
||||
|
||||
#### `GET /api/v1/files/{job_id}/{filename}`
|
||||
|
||||
下載轉換後的檔案。
|
||||
|
||||
**參數**
|
||||
|
||||
| 參數 | 類型 | 說明 |
|
||||
| -------- | ------ | -------- |
|
||||
| job_id | string | 任務 ID |
|
||||
| filename | string | 檔案名稱 |
|
||||
|
||||
---
|
||||
|
||||
## GraphQL API
|
||||
|
||||
Endpoint: `http://localhost:3001/graphql`
|
||||
|
||||
---
|
||||
|
||||
### Schema 概覽
|
||||
|
||||
```graphql
|
||||
type Query {
|
||||
health: HealthStatus!
|
||||
engines: [Engine!]!
|
||||
engine(id: ID!): Engine
|
||||
job(id: ID!): ConversionJob
|
||||
}
|
||||
|
||||
type Mutation {
|
||||
convert(input: ConvertInput!): ConversionJob!
|
||||
}
|
||||
|
||||
type Engine {
|
||||
id: ID!
|
||||
name: String!
|
||||
description: String!
|
||||
supportedInputFormats: [String!]!
|
||||
supportedOutputFormats: [String!]!
|
||||
}
|
||||
|
||||
type ConversionJob {
|
||||
id: ID!
|
||||
status: JobStatus!
|
||||
inputFile: String!
|
||||
outputFile: String
|
||||
engine: String!
|
||||
createdAt: DateTime!
|
||||
completedAt: DateTime
|
||||
}
|
||||
|
||||
enum JobStatus {
|
||||
PENDING
|
||||
PROCESSING
|
||||
COMPLETED
|
||||
FAILED
|
||||
}
|
||||
|
||||
input ConvertInput {
|
||||
fileId: ID!
|
||||
engine: String!
|
||||
outputFormat: String!
|
||||
}
|
||||
```
|
||||
|
||||
### 查詢範例
|
||||
|
||||
#### 列出引擎
|
||||
|
||||
```graphql
|
||||
query {
|
||||
engines {
|
||||
id
|
||||
name
|
||||
supportedInputFormats
|
||||
supportedOutputFormats
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 查詢任務狀態
|
||||
|
||||
```graphql
|
||||
query {
|
||||
job(id: "abc123") {
|
||||
id
|
||||
status
|
||||
outputFile
|
||||
completedAt
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 錯誤代碼
|
||||
|
||||
| 錯誤碼 | HTTP 狀態 | 說明 |
|
||||
| ------------------------ | --------- | ------------------ |
|
||||
| `MISSING_AUTH_HEADER` | 401 | 缺少 Authorization |
|
||||
| `INVALID_TOKEN` | 401 | Token 無效 |
|
||||
| `TOKEN_EXPIRED` | 401 | Token 已過期 |
|
||||
| `ENGINE_NOT_FOUND` | 404 | 引擎不存在 |
|
||||
| `UNSUPPORTED_CONVERSION` | 400 | 不支援的轉換 |
|
||||
| `FILE_TOO_LARGE` | 413 | 檔案過大 |
|
||||
| `CONVERSION_FAILED` | 500 | 轉換失敗 |
|
||||
|
||||
---
|
||||
|
||||
## 相關文件
|
||||
|
||||
- [API 總覽](overview.md)
|
||||
- [API 規格文件](../../api-server/docs/API_SPEC.md)
|
||||
128
docs/api/overview.md
Normal file
128
docs/api/overview.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 端點詳細說明](endpoints.md)
|
||||
- [API 規格文件](../../api-server/docs/API_SPEC.md)
|
||||
- [架構說明](../../api-server/docs/ARCHITECTURE.md)
|
||||
Loading…
Add table
Add a link
Reference in a new issue