275 lines
8.2 KiB
Markdown
275 lines
8.2 KiB
Markdown
# AstroResearch REST API Documentation / REST API 接口文档
|
||
|
||
AstroResearch 后端服务运行于 Rust Axum 框架之上，默认基准 URL 为 `http://localhost:8000/api`。
|
||
|
||
---
|
||
|
||
## 1. 共享类型定义 (TypeScript Type Definitions)
|
||
|
||
为了前后端类型一致，以下是主要的 TypeScript 数据接口定义：
|
||
|
||
```typescript
|
||
// 标准文献元数据
|
||
export interface StandardPaper {
|
||
bibcode: string;
|
||
title: string;
|
||
authors: string[];
|
||
year: string;
|
||
pub_journal: string;
|
||
keywords: string[];
|
||
abstract_text: string;
|
||
doi: string;
|
||
arxiv_id: string;
|
||
citation_count: number;
|
||
reference_count: number;
|
||
is_downloaded: boolean;
|
||
has_markdown: boolean;
|
||
has_translation: boolean;
|
||
}
|
||
|
||
// 笔记记录
|
||
export interface NoteRecord {
|
||
id: number;
|
||
bibcode: string;
|
||
paragraph_index: number;
|
||
note_text: string;
|
||
highlight_color: string; // 'yellow' | 'green' | 'blue' | 'pink'
|
||
selected_text: string;
|
||
created_at: string;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 接口分模块详述 (API Endpoints)
|
||
|
||
### 2.1 检索与引文导出模块 (Search & Citations Export)
|
||
|
||
#### 2.1.1 跨源文献统一搜索
|
||
- **Endpoint**: `GET /api/search`
|
||
- **Description**: 同时从 NASA ADS 与 arXiv XML 接口检索文献，返回去重并标准化后的文献元数据。
|
||
- **Query Parameters**:
|
||
- `q` (string, required): 检索关键词。
|
||
- `source` (string, optional): 指定源，取值为 `all` | `ads` | `arxiv`，默认 `all`。
|
||
- `rows` (number, optional): 返回条数限制。
|
||
- **Response Schema (`Vec<StandardPaper>`)**:
|
||
- HTTP `200 OK`
|
||
- **cURL 示例**:
|
||
```bash
|
||
curl -G "http://localhost:8000/api/search" \
|
||
--data-urlencode "q=Hertzsprung-Russell diagram" \
|
||
--data-urlencode "source=all"
|
||
```
|
||
|
||
#### 2.1.2 批量引文 BibTeX 导出
|
||
- **Endpoint**: `POST /api/export`
|
||
- **Description**: 将选中的文献 Bibcode 批量提交给 NASA ADS 接口，返回拼接的标准 BibTeX 文本。
|
||
- **Request Body**:
|
||
```json
|
||
{
|
||
"bibcodes": ["2024arXiv241011663H", "1984AJ.....89..374B"]
|
||
}
|
||
```
|
||
- **Response Schema**:
|
||
```json
|
||
{
|
||
"bibtex": "@ARTICLE{2024arXiv241011663H, ...}\n\n@ARTICLE{1984AJ.....89..374B, ...}"
|
||
}
|
||
```
|
||
- **cURL 示例**:
|
||
```bash
|
||
curl -X POST "http://localhost:8000/api/export" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"bibcodes": ["2024arXiv241011663H"]}'
|
||
```
|
||
|
||
---
|
||
|
||
### 2.2 馆藏管理与物理文件模块 (Library & Local Storage)
|
||
|
||
#### 2.2.1 获取馆藏文献列表
|
||
- **Endpoint**: `GET /api/library`
|
||
- **Description**: 查询本地 SQLite 数据库中已收藏入库的所有文献列表，后端会自动**实时感应物理文件是否存在**来修正 `is_downloaded` / `has_markdown` 等布尔状态。
|
||
- **Response Schema (`Vec<StandardPaper>`)**:
|
||
- HTTP `200 OK`
|
||
- **cURL 示例**:
|
||
```bash
|
||
curl "http://localhost:8000/api/library"
|
||
```
|
||
|
||
#### 2.2.2 触发并行文献下载
|
||
- **Endpoint**: `POST /api/download`
|
||
- **Description**: 触发后台线程拉取文献的 PDF 及 HTML。如果是 arXiv 来源优先官方 HTML 兜底 ar5iv，并支持强制更新。
|
||
- **Request Body**:
|
||
```json
|
||
{
|
||
"bibcode": "2024arXiv241011663H",
|
||
"force": false
|
||
}
|
||
```
|
||
- **Response Schema (`StandardPaper`)**: Returns the updated paper structure with `is_downloaded: true`.
|
||
- **cURL 示例**:
|
||
```bash
|
||
curl -X POST "http://localhost:8000/api/download" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"bibcode": "2024arXiv241011663H", "force": true}'
|
||
```
|
||
|
||
#### 2.2.3 触发文献结构化解析
|
||
- **Endpoint**: `POST /api/parse`
|
||
- **Description**: 将本地下载的 HTML/PDF 清洗为 Markdown。支持 `force` 强制重新执行。
|
||
- **Request Body**:
|
||
```json
|
||
{
|
||
"bibcode": "2024arXiv241011663H",
|
||
"force": false
|
||
}
|
||
```
|
||
- **Response Schema**:
|
||
```json
|
||
{
|
||
"markdown": "# 论文标题\n\n## 1. 绪论\n..."
|
||
}
|
||
```
|
||
- **cURL 示例**:
|
||
```bash
|
||
curl -X POST "http://localhost:8000/api/parse" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"bibcode": "2024arXiv241011663H", "force": false}'
|
||
```
|
||
|
||
---
|
||
|
||
### 2.3 阅读器与翻译模块 (Reader & LLM Translation)
|
||
|
||
#### 2.3.1 获取文献阅读详情
|
||
- **Endpoint**: `GET /api/paper`
|
||
- **Description**: 获取某篇文献的标准元数据和已缓存的英文正文 Markdown 以及翻译后 Markdown。
|
||
- **Query Parameters**:
|
||
- `bibcode` (string, required): 文献唯一标识符。
|
||
- **Response Schema**:
|
||
```json
|
||
{
|
||
"paper": { ... },
|
||
"english_content": "# Abstract...", // 若未解析，返回 null
|
||
"translation_content": "# 摘要..." // 若未翻译，返回 null
|
||
}
|
||
```
|
||
- **cURL 示例**:
|
||
```bash
|
||
curl "http://localhost:8000/api/paper?bibcode=2024arXiv241011663H"
|
||
```
|
||
|
||
#### 2.3.2 触发 LLM 对照翻译
|
||
- **Endpoint**: `POST /api/translate`
|
||
- **Description**: 将英文 Markdown 提取本地词典名词注入 Glossary 提示词，并调用大模型进行学术翻译，最后写回本地物理文件并入库。
|
||
- **Request Body**:
|
||
```json
|
||
{
|
||
"bibcode": "2024arXiv241011663H",
|
||
"force": false
|
||
}
|
||
```
|
||
- **Response Schema**:
|
||
```json
|
||
{
|
||
"translation": "# 翻译结果..."
|
||
}
|
||
```
|
||
- **cURL 示例**:
|
||
```bash
|
||
curl -X POST "http://localhost:8000/api/translate" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"bibcode": "2024arXiv241011663H"}'
|
||
```
|
||
|
||
---
|
||
|
||
### 2.4 引文网络拓扑模块 (Citation Galaxy Map)
|
||
|
||
#### 2.4.1 查询文献的引文拓扑
|
||
- **Endpoint**: `GET /api/citations`
|
||
- **Description**: 获取某篇文献的参考文献 (References) 和施引文献 (Citations) 的 Bibcode 数组列表，用于渲染拓扑关系网。
|
||
- **Query Parameters**:
|
||
- `bibcode` (string, required): 目标文献 Bibcode。
|
||
- **Response Schema**:
|
||
```json
|
||
{
|
||
"bibcode": "2024arXiv241011663H",
|
||
"title": "...",
|
||
"citation_count": 12,
|
||
"reference_count": 48,
|
||
"references": ["bibcode1", "bibcode2"],
|
||
"citations": ["bibcode3", "bibcode4"]
|
||
}
|
||
```
|
||
- **cURL 示例**:
|
||
```bash
|
||
curl "http://localhost:8000/api/citations?bibcode=2024arXiv241011663H"
|
||
```
|
||
|
||
---
|
||
|
||
### 2.5 笔记高亮模块 (Notes & Highlights)
|
||
|
||
#### 2.5.1 创建笔记与高亮
|
||
- **Endpoint**: `POST /api/notes`
|
||
- **Description**: 对指定文献的特定段落位置创建高亮选段，并记录文字备注。
|
||
- **Request Body**:
|
||
```json
|
||
{
|
||
"bibcode": "2024arXiv241011663H",
|
||
"paragraph_index": 12,
|
||
"note_text": "这是一个重要的物理模型",
|
||
"highlight_color": "yellow", // 'yellow' | 'green' | 'blue' | 'pink'
|
||
"selected_text": "the standard model of galaxy formation"
|
||
}
|
||
```
|
||
- **Response Schema (`NoteRecord`)**: Returns the created note details containing auto-incremented `id` and creation timestamp.
|
||
- **cURL 示例**:
|
||
```bash
|
||
curl -X POST "http://localhost:8000/api/notes" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"bibcode": "2024arXiv241011663H", "paragraph_index": 12, "note_text": "My Note", "highlight_color": "green", "selected_text": "original text"}'
|
||
```
|
||
|
||
#### 2.5.2 获取单篇文献下的全部笔记
|
||
- **Endpoint**: `GET /api/notes`
|
||
- **Description**: 查询某篇文献关联的所有笔记。
|
||
- **Query Parameters**:
|
||
- `bibcode` (string, required): 目标文献。
|
||
- **Response Schema (`Vec<NoteRecord>`)**:
|
||
- HTTP `200 OK`
|
||
- **cURL 示例**:
|
||
```bash
|
||
curl "http://localhost:8000/api/notes?bibcode=2024arXiv241011663H"
|
||
```
|
||
|
||
#### 2.5.3 删除笔记
|
||
- **Endpoint**: `DELETE /api/notes`
|
||
- **Description**: 物理删除指定 ID 的笔记高亮记录。
|
||
- **Query Parameters**:
|
||
- `id` (number, required): 笔记记录的唯一自增 id。
|
||
- **Response Schema**:
|
||
```json
|
||
{
|
||
"status": "success"
|
||
}
|
||
```
|
||
- **cURL 示例**:
|
||
```bash
|
||
curl -X DELETE "http://localhost:8000/api/notes?id=5"
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 常见 HTTP 状态码与异常处理 (Error Codes)
|
||
|
||
系统基于标准的 HTTP Status Codes 返回错误原因，响应的 Response Body 中通常为纯文本提示（String）：
|
||
|
||
| 状态码 | 错误类型 | 触发常见场景及原因说明 |
|
||
| :--- | :--- | :--- |
|
||
| **`400 Bad Request`** | 业务请求不合规 | - 文献未下载/解析却直接调用 `translate`。<br>- 未在 `.env` 中提供 `ADS_API_KEY` 时调用 `export`。 |
|
||
| **`404 Not Found`** | 资源未找到 | - 数据库中没有该 Bibcode 的收藏记录。 |
|
||
| **`500 Internal Error`**| 服务器内部错误 | - 第三方 LLM / ADS 接口通信超时或返回异常。<br>- 本地磁盘 IO 失败（如写入文件权限受阻）。<br>- 数据库查询异常。 |
|