DATABASE_USAGE.md

# Papers Database 使用说明

## 概述

现在系统已经支持将arXiv文章和评价内容存储到SQLite数据库中，而不是保存在JSON文件中。这样可以更好地管理论文数据，支持查询、统计和标签管理。

## 数据库结构

### papers 表

| 字段 | 类型 | 说明 |
|------|------|------|
| arxiv_id | TEXT PRIMARY KEY | arXiv论文ID |
| title | TEXT NOT NULL | 论文标题 |
| authors | TEXT NOT NULL | 作者列表 |
| abstract | TEXT | 论文摘要 |
| categories | TEXT | 论文分类 |
| published_date | TEXT | 发布日期 |
| evaluation_content | TEXT | 评价内容（JSON格式） |
| evaluation_score | REAL | 总体自动化评分 |
| evaluation_tags | TEXT | 评价标签 |
| is_evaluated | BOOLEAN | 是否已评价 |
| evaluation_date | TIMESTAMP | 评价日期 |
| created_at | TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | 更新时间 |

## 使用方法

### 1. 插入论文

```python
from src.database.db import db

# 插入新论文
db.insert_paper(
    arxiv_id="2508.05629",
    title="Your Paper Title",
    authors="Author 1, Author 2",
    abstract="Paper abstract...",
    categories="cs.AI, cs.LG",
    published_date="2024-08-01"
)
```

### 2. 更新评价

```python
# 更新论文评价
db.update_paper_evaluation(
    arxiv_id="2508.05629",
    evaluation_content='{"overall_automatability": 3, "three_year_feasibility": 75}',
    evaluation_score=3.0,
    evaluation_tags="3yr_feasibility:75%,overall_automatability:3/4"
)
```

### 3. 查询论文

```python
# 获取单个论文
paper = db.get_paper("2508.05629")

# 获取所有已评价的论文
evaluated_papers = db.get_evaluated_papers()

# 获取所有未评价的论文
unevaluated_papers = db.get_unevaluated_papers()

# 搜索论文
search_results = db.search_papers("AI")
```

### 4. 统计信息

```python
# 获取论文统计
count = db.get_papers_count()
print(f"总论文数: {count['total']}")
print(f"已评价: {count['evaluated']}")
print(f"未评价: {count['unevaluated']}")
```

## API 接口

### 获取评价列表
```
GET /api/evals
```

### 检查论文是否已评价
```
GET /api/has-eval/{paper_id}
```

### 获取论文评价
```
GET /api/eval/{paper_id}
```

### 获取论文统计
```
GET /api/papers/status
```

### 插入新论文
```
POST /api/papers/insert
Content-Type: application/json

{
    "arxiv_id": "2508.05629",
    "title": "Paper Title",
    "authors": "Author 1, Author 2",
    "abstract": "Abstract...",
    "categories": "cs.AI",
    "published_date": "2024-08-01"
}
```

### 评价论文
```
POST /api/papers/evaluate/{arxiv_id}
```

## CLI 工具使用

### 评价论文并保存到数据库

```bash
# 使用arxiv_id参数将评价保存到数据库
python cli.py https://arxiv.org/pdf/2508.05629 --arxiv-id 2508.05629

# 同时保存到文件和数据库
python cli.py https://arxiv.org/pdf/2508.05629 --arxiv-id 2508.05629 -o /path/to/output
```

## 迁移现有数据

如果你有现有的JSON评价文件，可以编写脚本将它们导入到数据库中：

```python
import json
import os
from src.database.db import db

def migrate_json_to_db(json_dir="workdir"):
    """将JSON文件迁移到数据库"""
    for filename in os.listdir(json_dir):
        if filename.endswith('.json'):
            filepath = os.path.join(json_dir, filename)
            with open(filepath, 'r') as f:
                data = json.load(f)
            
            # 提取arxiv_id（假设文件名包含arxiv_id）
            arxiv_id = filename.split('_')[0]  # 根据实际文件名格式调整
            
            # 更新数据库中的评价
            if 'response' in data:
                db.update_paper_evaluation(
                    arxiv_id=arxiv_id,
                    evaluation_content=data['response'],
                    evaluation_score=None,  # 需要从内容中解析
                    evaluation_tags=None
                )
                print(f"Migrated {filename} for paper {arxiv_id}")
```

## 优势

1. **结构化存储**: 论文信息和评价内容分开存储，便于查询
2. **标签系统**: 支持为评价添加标签，便于分类和筛选
3. **统计功能**: 可以轻松获取论文统计信息
4. **搜索功能**: 支持按标题、作者、摘要搜索论文
5. **状态管理**: 通过`is_evaluated`字段跟踪评价状态
6. **API支持**: 提供完整的RESTful API接口

## 注意事项

1. 确保在评价论文前先插入论文基本信息
2. 评价内容建议使用JSON格式，便于解析和展示
3. 定期备份数据库文件
4. 可以使用`evaluation_tags`字段存储关键评分信息，便于快速筛选