AIclinicalresearch/docs/03-业务模块/ASL-AI智能文献/02-技术设计/02-API设计规范.md

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

---

📋 响应格式规范

成功响应

{
  "code": 200,
  "message": "success",
  "data": {...}
}

错误响应

{
  "code": 400,
  "message": "错误描述",
  "error": {
    "code": "ERROR_CODE",
    "details": "..."
  }
}

分页响应

{
  "code": 200,
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 100,
      "totalPages": 5
    }
  }
}

---

⏳ 待完善内容

后续将补充：

• 完整的API文档（所有接口详细说明）
• 请求/响应示例
• 错误码定义
• 接口测试用例

---

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