API.md

# AI 批改平台 API 文件

## 基本資訊

- **Base URL**: `https://api.example.com`
- **API Version**: `v1`
- **Content-Type**: `application/json`
- **Authentication**: Bearer Token (放在 Authorization header)

---

## API 端點

### 1. 取得可用 Agents 列表

**GET** `/api/agents`

取得所有可用的批改 agents 清單。

#### Request

```http
GET /api/agents HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_TOKEN
```

#### Response

**Status Code**: `200 OK`

```json
{
  "version": 2,
  "agents": [
    {
      "key": "zh_full_edit",
      "name": "中文全文批改",
      "language": "zh-TW",
      "ui": {
        "badge": "ZH",
        "color": "#1565C0"
      },
      "rubric": {
        "overall_weight": 100,
        "criteria": [
          {
            "key": "structure",
            "label": "結構與段落",
            "weight": 25
          },
          {
            "key": "coherence",
            "label": "論證與連貫",
            "weight": 25
          },
          {
            "key": "clarity",
            "label": "表達清晰度",
            "weight": 25
          },
          {
            "key": "mechanics",
            "label": "字詞/標點/語法",
            "weight": 25
          }
        ]
      }
    },
    {
      "key": "en_edit",
      "name": "英文批改",
      "language": "en",
      "ui": {
        "badge": "EN",
        "color": "#2E7D32"
      },
      "rubric": {
        "overall_weight": 100,
        "criteria": [
          {
            "key": "organization",
            "label": "Organization",
            "weight": 20
          },
          {
            "key": "argumentation",
            "label": "Argumentation",
            "weight": 30
          },
          {
            "key": "clarity",
            "label": "Clarity & Style",
            "weight": 25
          },
          {
            "key": "mechanics",
            "label": "Grammar & Spelling",
            "weight": 25
          }
        ]
      }
    }
  ]
}
```

---

### 2. 送出批改請求

**POST** `/api/grade`

送出文章進行 AI 批改。

#### Request

```http
POST /api/grade HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
```

**Body Parameters**

| 參數 | 類型 | 必填 | 說明 |
|------|------|------|------|
| `agent_key` | string | ✓ | Agent 識別碼（如 `zh_full_edit`） |
| `text` | string | ✓ | 要批改的文章全文 |
| `options` | object | ✗ | 額外選項 |
| `options.output_format` | string | ✗ | 輸出格式：`markdown`(預設)、`html`、`diff`、`json` |
| `options.include_scores` | boolean | ✗ | 是否包含評分（預設：true） |
| `options.include_suggestions` | boolean | ✗ | 是否包含改進建議（預設：true） |

**Request Example**

```json
{
  "agent_key": "zh_full_edit",
  "text": "這是一篇關於環保議題的文章。在現代社會中，環境保護已成為全球關注的焦點...",
  "options": {
    "output_format": "markdown",
    "include_scores": true,
    "include_suggestions": true
  }
}
```

#### Response

**Success Response**

**Status Code**: `200 OK`

```json
{
  "success": true,
  "data": {
    "agent_key": "zh_full_edit",
    "timestamp": "2024-01-20T10:30:00Z",
    "processing_time_ms": 3500,
    "result": {
      "summary": "這篇文章探討了環保議題，結構清晰但論述可以更深入...",
      "inline_edits": "這是一篇關於環保議題的文章。在現代社會中，環境保護已成為全球~~關注的焦點~~**矚目的核心議題**...",
      "scores": {
        "overall": 75,
        "criteria": {
          "structure": 80,
          "coherence": 70,
          "clarity": 75,
          "mechanics": 75
        }
      },
      "suggestions": [
        {
          "type": "improvement",
          "section": "introduction",
          "text": "建議在開頭加入更具體的數據或案例，增強說服力"
        },
        {
          "type": "correction",
          "section": "paragraph_2",
          "text": "第二段的轉折詞使用不當，建議改為『然而』"
        }
      ]
    }
  }
}
```

**Processing Response (Long Polling)**

如果處理時間較長，可能會先回傳處理中狀態：

**Status Code**: `202 Accepted`

```json
{
  "success": true,
  "data": {
    "job_id": "job_abc123xyz",
    "status": "processing",
    "message": "批改處理中，請稍候..."
  }
}
```

**Error Response**

**Status Code**: `400 Bad Request`

```json
{
  "success": false,
  "error": {
    "code": "INVALID_AGENT",
    "message": "指定的 agent_key 不存在",
    "details": {
      "agent_key": "invalid_agent",
      "available_agents": ["zh_full_edit", "en_edit"]
    }
  }
}
```

---

### 3. 查詢批改狀態（選用）

**GET** `/api/grade/{job_id}`

查詢長時間處理的批改任務狀態。

#### Request

```http
GET /api/grade/job_abc123xyz HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_TOKEN
```

#### Response

**Processing**

```json
{
  "success": true,
  "data": {
    "job_id": "job_abc123xyz",
    "status": "processing",
    "progress": 65,
    "message": "正在分析文章結構..."
  }
}
```

**Completed**

```json
{
  "success": true,
  "data": {
    "job_id": "job_abc123xyz",
    "status": "completed",
    "result": {
      // 同上方批改結果格式
    }
  }
}
```

---

## 錯誤碼

| HTTP 狀態碼 | 錯誤碼 | 說明 |
|------------|--------|------|
| 400 | `INVALID_AGENT` | 無效的 agent_key |
| 400 | `EMPTY_TEXT` | 文章內容為空 |
| 400 | `TEXT_TOO_LONG` | 文章超過長度限制（預設 10000 字） |
| 401 | `UNAUTHORIZED` | 未提供或無效的 API Token |
| 403 | `FORBIDDEN` | 無權限使用此 agent |
| 429 | `RATE_LIMIT` | 超過速率限制 |
| 500 | `INTERNAL_ERROR` | 伺服器內部錯誤 |
| 503 | `SERVICE_UNAVAILABLE` | OpenAI API 暫時無法使用 |

---

## 速率限制

- **預設限制**：每分鐘 10 次請求
- **Response Headers**：
  - `X-RateLimit-Limit`: 速率限制上限
  - `X-RateLimit-Remaining`: 剩餘請求次數
  - `X-RateLimit-Reset`: 重置時間（Unix timestamp）

---

## WebSocket API（即時批改 - 選用）

**Endpoint**: `wss://api.example.com/ws/grade`

### Connection

```javascript
const ws = new WebSocket('wss://api.example.com/ws/grade');
ws.onopen = () => {
  // 發送認證
  ws.send(JSON.stringify({
    type: 'auth',
    token: 'YOUR_API_TOKEN'
  }));
};
```

### 送出批改

```javascript
ws.send(JSON.stringify({
  type: 'grade',
  data: {
    agent_key: 'zh_full_edit',
    text: '文章內容...'
  }
}));
```

### 接收進度更新

```javascript
ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  
  switch(message.type) {
    case 'progress':
      console.log(`進度: ${message.progress}%`);
      break;
    case 'partial':
      console.log('部分結果:', message.data);
      break;
    case 'complete':
      console.log('批改完成:', message.data);
      break;
    case 'error':
      console.error('錯誤:', message.error);
      break;
  }
};
```

---

## SDK 範例

### JavaScript/TypeScript

```typescript
import { GradingClient } from '@example/grading-sdk';

const client = new GradingClient({
  apiKey: 'YOUR_API_TOKEN',
  baseUrl: 'https://api.example.com'
});

// 取得 agents
const agents = await client.getAgents();

// 送出批改
const result = await client.grade({
  agentKey: 'zh_full_edit',
  text: '文章內容...',
  options: {
    outputFormat: 'markdown',
    includeScores: true
  }
});

console.log(result.summary);
console.log(result.scores);
```

### Python

```python
from grading_sdk import GradingClient

client = GradingClient(
    api_key="YOUR_API_TOKEN",
    base_url="https://api.example.com"
)

# 取得 agents
agents = client.get_agents()

# 送出批改
result = client.grade(
    agent_key="zh_full_edit",
    text="文章內容...",
    options={
        "output_format": "markdown",
        "include_scores": True
    }
)

print(result["summary"])
print(result["scores"])
```

---

## 測試環境

- **Staging URL**: `https://staging-api.example.com`
- **測試 Token**: 請聯繫管理員取得

---

## 更新紀錄

| 版本 | 日期 | 更新內容 |
|------|------|----------|
| v1.0.0 | 2024-01-20 | 初版發布 |
| v1.1.0 | 2024-02-01 | 新增 WebSocket 即時批改 |
| v1.2.0 | 2024-02-15 | 支援批次批改 |

---

## 聯絡資訊

- **技術支援**: support@example.com
- **API 狀態頁**: https://status.example.com
- **開發者論壇**: https://forum.example.com/api