docs/API_DOCUMENTATION.md

# 书籍API文档

## 概述

这是一套基于SQLite数据库的书籍管理API，提供书籍列表、目录、页面内容查询等功能。

## 快速开始

### 1. 数据导入

首先需要将JSON数据导入到SQLite数据库：

```bash
python import_book_data.py
```

执行成功后，会在当前目录生成 `books.db` 文件。

### 2. 启动应用

```bash
python app.py
```

应用默认运行在 `http://localhost:7860`

## API端点

### 基础信息

- **Base URL**: `http://localhost:7860/api/v2`
- **返回格式**: JSON
- **编码**: UTF-8

---

### 1. 获取书籍列表

获取所有可用的书籍。

**请求**

```
GET /api/v2/books
```

**响应示例**

```json
{
  "success": true,
  "count": 1,
  "books": [
    {
      "book_id": 1,
      "book_name": "书籍ID 10242",
      "source_file": "book_10242.json",
      "total_pages": 64,
      "created_at": "2024-10-16 12:00:00",
      "updated_at": "2024-10-16 12:00:00"
    }
  ]
}
```

---

### 2. 获取书籍信息

获取指定书籍的详细信息。

**请求**

```
GET /api/v2/books/{book_id}
```

**参数**

| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| book_id | int | 是 | 书籍ID |

**响应示例**

```json
{
  "success": true,
  "book": {
    "book_id": 1,
    "book_name": "书籍ID 10242",
    "source_file": "book_10242.json",
    "total_pages": 64,
    "created_at": "2024-10-16 12:00:00",
    "updated_at": "2024-10-16 12:00:00"
  }
}
```

---

### 3. 获取书籍目录

获取书籍的所有页面列表（目录）。

**请求**

```
GET /api/v2/books/{book_id}/catalog
```

**参数**

| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| book_id | int | 是 | 书籍ID |

**响应示例**

```json
{
  "success": true,
  "book_id": 1,
  "book_name": "书籍ID 10242",
  "total_pages": 64,
  "catalog": [
    {
      "page_id": 34428,
      "page_number": 55,
      "origin_img_url": "https://res-100200.kingsunedu.com/...",
      "encrypt_img_url": "https://res-100200.kingsunedu.com/..."
    },
    {
      "page_id": 34429,
      "page_number": 56,
      "origin_img_url": "https://res-100200.kingsunedu.com/...",
      "encrypt_img_url": "https://res-100200.kingsunedu.com/..."
    }
  ]
}
```

---

### 4. 获取单页内容

获取指定页面的完整内容，包括所有文本片段、音频等。

**请求**

```
GET /api/v2/books/{book_id}/pages/{page_num}
```

**参数**

| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| book_id | int | 是 | 书籍ID |
| page_num | int | 是 | 页码 |

**响应示例**

```json
{
  "success": true,
  "book_id": 1,
  "book_name": "书籍ID 10242",
  "page": {
    "page_id": 34428,
    "page_number": 55,
    "origin_img_url": "https://res-100200.kingsunedu.com/...",
    "encrypt_img_url": "https://res-100200.kingsunedu.com/...",
    "piece_count": 15,
    "pieces": [
      {
        "piece_id": 207349,
        "original": "Unit 1",
        "translation": "",
        "origin_sound_url": "https://res-100200.kingsunedu.com/...",
        "encrypt_sound_url": "https://res-100200.kingsunedu.com/...",
        "duration": 2,
        "coordinate": {
          "x": 0.1031,
          "y": 0.1281,
          "width": 0.0857,
          "height": 0.0277
        },
        "is_evaluated": 0,
        "show_translation": 1,
        "rich_original": "",
        "rich_translation": ""
      }
    ]
  }
}
```

---

### 5. 搜索内容

在书籍中搜索关键词。

**请求**

```
GET /api/v2/books/{book_id}/search?keyword={keyword}&limit={limit}
```

**参数**

| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| book_id | int | 是 | 书籍ID |
| keyword | string | 是 | 搜索关键词 |
| limit | int | 否 | 返回结果数量（默认20） |

**响应示例**

```json
{
  "success": true,
  "book_id": 1,
  "keyword": "hello",
  "count": 3,
  "results": [
    {
      "page_id": 34428,
      "page_number": 55,
      "piece_id": 207350,
      "original": "Hello, how are you?",
      "translation": "你好，你好吗？"
    }
  ]
}
```

---

### 6. 获取统计信息

获取书籍的统计数据。

**请求**

```
GET /api/v2/books/{book_id}/statistics
```

**参数**

| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| book_id | int | 是 | 书籍ID |

**响应示例**

```json
{
  "success": true,
  "statistics": {
    "book_id": 1,
    "total_pages": 64,
    "total_pieces": 850,
    "total_audio": 820
  }
}
```

---

## 错误响应

所有API在出错时返回统一格式：

```json
{
  "success": false,
  "error": "错误信息描述"
}
```

**常见错误码**

- `400` - 请求参数错误
- `404` - 资源不存在
- `500` - 服务器内部错误

---

## 使用示例

### cURL

```bash
# 获取书籍列表
curl http://localhost:7860/api/v2/books

# 获取书籍目录
curl http://localhost:7860/api/v2/books/1/catalog

# 获取第55页内容
curl http://localhost:7860/api/v2/books/1/pages/55

# 搜索内容
curl "http://localhost:7860/api/v2/books/1/search?keyword=hello&limit=10"

# 获取统计信息
curl http://localhost:7860/api/v2/books/1/statistics
```

### Python

```python
import requests

base_url = "http://localhost:7860/api/v2"

# 获取书籍列表
response = requests.get(f"{base_url}/books")
books = response.json()
print(books)

# 获取第55页内容
book_id = 1
page_num = 55
response = requests.get(f"{base_url}/books/{book_id}/pages/{page_num}")
page_data = response.json()
print(page_data)

# 搜索
response = requests.get(f"{base_url}/books/{book_id}/search", params={
    'keyword': 'hello',
    'limit': 10
})
search_results = response.json()
print(search_results)
```

### JavaScript

```javascript
const baseUrl = 'http://localhost:7860/api/v2';

// 获取书籍列表
fetch(`${baseUrl}/books`)
  .then(response => response.json())
  .then(data => console.log(data));

// 获取第55页内容
const bookId = 1;
const pageNum = 55;
fetch(`${baseUrl}/books/${bookId}/pages/${pageNum}`)
  .then(response => response.json())
  .then(data => console.log(data));

// 搜索
fetch(`${baseUrl}/books/${bookId}/search?keyword=hello&limit=10`)
  .then(response => response.json())
  .then(data => console.log(data));
```

---

## 数据库结构

### books 表
- `book_id`: 书籍ID（主键）
- `book_name`: 书籍名称
- `source_file`: 源文件名
- `total_pages`: 总页数
- `created_at`: 创建时间
- `updated_at`: 更新时间

### pages 表
- `page_id`: 页面ID（主键）
- `book_id`: 所属书籍ID（外键）
- `page_number`: 页码
- `origin_img_url`: 原始图片URL
- `encrypt_img_url`: 加密图片URL
- `created_at`: 创建时间

### pieces 表
- `piece_id`: 片段ID（主键）
- `page_id`: 所属页面ID（外键）
- `original`: 原文
- `translation`: 翻译
- `origin_sound_url`: 原始音频URL
- `encrypt_sound_url`: 加密音频URL
- `duration`: 音频时长
- `coordinate_x/y/width/height`: 坐标信息
- `is_evaluated`: 是否可评测
- `show_translation`: 是否显示翻译
- `rich_original`: 富文本原文
- `rich_translation`: 富文本翻译
- `created_at`: 创建时间

---

## 注意事项

1. 首次使用前必须运行 `import_book_data.py` 导入数据
2. 数据库文件 `books.db` 会在导入时自动创建
3. 所有API响应都是UTF-8编码的JSON格式
4. 页码从实际页码开始（如本例中从55开始）
5. 音频URL有时效性，可能需要定期更新

---

## 支持

如有问题，请查看日志文件 `logs/app.log`