# 书籍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`