# AI智能文献模块 - API设计规范

> **文档版本：** v1.0  
> **创建日期：** 2025-10-29  
> **维护者：** AI智能文献开发团队  
> **最后更新：** 2025-10-29

---

## 📋 文档说明

本文档描述AI智能文献模块的API设计规范，包括接口定义、请求响应格式、错误处理等。

---

## 🔌 API设计原则

1. **RESTful设计**: 遵循RESTful API设计规范
2. **统一响应格式**: 统一的成功/错误响应结构
3. **分页支持**: 列表接口支持分页
4. **版本控制**: API版本化管理
5. **认证授权**: 所有接口需要JWT认证

---

## 📡 核心API接口

### 1. 项目管理

#### 创建筛选项目
```
POST /api/literature/projects
Request Body:
{
  "projectName": "string",
  "picoCriteria": {...},
  "inclusionCriteria": "string",
  "exclusionCriteria": "string"
}
Response:
{
  "code": 200,
  "data": {
    "id": "uuid",
    "projectName": "string",
    ...
  }
}
```

#### 获取项目列表
```
GET /api/literature/projects?page=1&pageSize=10
```

#### 获取项目详情
```
GET /api/literature/projects/:projectId
```

#### 更新项目
```
PUT /api/literature/projects/:projectId
```

#### 删除项目
```
DELETE /api/literature/projects/:projectId
```

### 2. 文献管理

#### 导入文献（Excel）
```
POST /api/literature/projects/:projectId/items/import
Content-Type: multipart/form-data
Body: file (Excel文件)
Response:
{
  "code": 200,
  "data": {
    "importedCount": 100,
    "items": [...]
  }
}
```

#### 获取文献列表
```
GET /api/literature/projects/:projectId/items?page=1&pageSize=50
```

#### 获取文献详情
```
GET /api/literature/projects/:projectId/items/:itemId
```

### 3. 标题摘要初筛

#### 启动筛选任务
```
POST /api/literature/projects/:projectId/screening/start
Request Body:
{
  "screeningType": "title_abstract",
  "modelConfig": {
    "ds": true,
    "q3": true
  }
}
Response:
{
  "code": 200,
  "data": {
    "taskId": "uuid",
    "status": "running"
  }
}
```

#### 获取筛选结果
```
GET /api/literature/projects/:projectId/screening/results
Query Params:
  - page: 页码
  - pageSize: 每页数量
  - conflictOnly: 只显示冲突项
  - decision: include/exclude/pending
```

#### 更新最终决策
```
PUT /api/literature/projects/:projectId/screening/results/:resultId
Request Body:
{
  "finalDecision": "include", // include/exclude
  "exclusionReason": "string" // 排除时必填
}
```

#### 批量更新决策
```
POST /api/literature/projects/:projectId/screening/results/batch-update
Request Body:
{
  "itemIds": ["uuid1", "uuid2", ...],
  "finalDecision": "include",
  "exclusionReason": "string"
}
```

### 4. 任务管理

#### 获取任务状态
```
GET /api/literature/projects/:projectId/tasks/:taskId
Response:
{
  "code": 200,
  "data": {
    "id": "uuid",
    "status": "running", // pending/running/completed/failed
    "totalItems": 100,
    "processedItems": 45,
    "progress": 45
  }
}
```

#### 任务进度流式推送（SSE）
```
GET /api/literature/projects/:projectId/tasks/:taskId/progress
Accept: text/event-stream
```

---

## 📋 响应格式规范

### 成功响应
```json
{
  "code": 200,
  "message": "success",
  "data": {...}
}
```

### 错误响应
```json
{
  "code": 400,
  "message": "错误描述",
  "error": {
    "code": "ERROR_CODE",
    "details": "..."
  }
}
```

### 分页响应
```json
{
  "code": 200,
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 100,
      "totalPages": 5
    }
  }
}
```

---

## ⏳ 待完善内容

后续将补充：
- 完整的API文档（所有接口详细说明）
- 请求/响应示例
- 错误码定义
- 接口测试用例

---

**文档版本：** v1.0  
**最后更新：** 2025-10-29