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

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

文档版本： v2.0
创建日期： 2025-10-29
维护者： AI智能文献开发团队
最后更新： 2025-11-18
更新说明： 基于实际实现代码更新，所有接口已测试验证

---

📋 文档说明

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

API基础信息:

• Base URL: http://localhost:3001 (开发环境)
• API前缀: /api/v1/asl
• 协议: HTTP/HTTPS
• 数据格式: JSON
• 认证方式: JWT Token (测试阶段支持默认用户)

---

🔌 API设计原则

1. RESTful设计: 遵循RESTful API设计规范
2. 统一响应格式: { success: boolean, data?: any, error?: string }
3. 分页支持: 列表接口支持分页参数
4. 版本控制: API版本化管理 (/api/v1/...)
5. 错误处理: 统一的HTTP状态码和错误消息
6. 模块化路由: /api/v1/asl/... 独立路由空间

---

📡 核心API接口

1. 项目管理 (Projects)

1.1 创建筛选项目

接口: POST /api/v1/asl/projects
认证: 需要 (测试阶段默认用户ID)
说明: 创建一个新的文献筛选项目

请求体:

{
  "projectName": "SGLT2抑制剂系统综述",
  "picoCriteria": {
    "population": "2型糖尿病成人患者",
    "intervention": "SGLT2抑制剂",
    "comparison": "安慰剂或常规降糖疗法",
    "outcome": "心血管结局",
    "studyDesign": "随机对照试验 (RCT)"
  },
  "inclusionCriteria": "英文文献，RCT研究，2010年后发表",
  "exclusionCriteria": "病例报告，综述，动物实验",
  "screeningConfig": {
    "models": ["deepseek-chat", "qwen-max"],
    "temperature": 0
  }
}

响应示例:

{
  "success": true,
  "data": {
    "id": "d67f0b9a-b035-4804-aca1-0bd672c27d81",
    "userId": "asl-test-user-001",
    "projectName": "SGLT2抑制剂系统综述",
    "picoCriteria": {
      "population": "2型糖尿病成人患者",
      "intervention": "SGLT2抑制剂",
      "comparison": "安慰剂或常规降糖疗法",
      "outcome": "心血管结局",
      "studyDesign": "随机对照试验 (RCT)"
    },
    "inclusionCriteria": "英文文献，RCT研究，2010年后发表",
    "exclusionCriteria": "病例报告，综述，动物实验",
    "status": "draft",
    "screeningConfig": {
      "models": ["deepseek-chat", "qwen-max"],
      "temperature": 0
    },
    "createdAt": "2025-11-18T07:30:00.000Z",
    "updatedAt": "2025-11-18T07:30:00.000Z"
  }
}

测试命令:

curl -X POST http://localhost:3001/api/v1/asl/projects \
  -H "Content-Type: application/json" \
  -d '{
    "projectName": "测试项目",
    "picoCriteria": {
      "population": "成人患者",
      "intervention": "药物A",
      "comparison": "安慰剂",
      "outcome": "主要结局",
      "studyDesign": "RCT"
    },
    "inclusionCriteria": "英文文献",
    "exclusionCriteria": "综述"
  }'

---

1.2 获取项目列表

接口: GET /api/v1/asl/projects
认证: 需要
说明: 获取当前用户的所有筛选项目

查询参数: 无

响应示例:

{
  "success": true,
  "data": [
    {
      "id": "d67f0b9a-b035-4804-aca1-0bd672c27d81",
      "userId": "asl-test-user-001",
      "projectName": "SGLT2抑制剂系统综述",
      "picoCriteria": {...},
      "status": "screening",
      "createdAt": "2025-11-18T07:30:00.000Z",
      "updatedAt": "2025-11-18T07:35:00.000Z",
      "_count": {
        "literatures": 3,
        "screeningResults": 3
      }
    }
  ]
}

测试命令:

curl http://localhost:3001/api/v1/asl/projects

---

1.3 获取项目详情

接口: GET /api/v1/asl/projects/:projectId
认证: 需要
说明: 获取指定项目的详细信息

路径参数:

• projectId: 项目ID (UUID)

响应示例:

{
  "success": true,
  "data": {
    "id": "d67f0b9a-b035-4804-aca1-0bd672c27d81",
    "userId": "asl-test-user-001",
    "projectName": "SGLT2抑制剂系统综述",
    "picoCriteria": {
      "population": "2型糖尿病成人患者",
      "intervention": "SGLT2抑制剂",
      "comparison": "安慰剂或常规降糖疗法",
      "outcome": "心血管结局",
      "studyDesign": "随机对照试验 (RCT)"
    },
    "inclusionCriteria": "英文文献，RCT研究，2010年后发表",
    "exclusionCriteria": "病例报告，综述，动物实验",
    "status": "screening",
    "screeningConfig": {
      "models": ["deepseek-chat", "qwen-max"],
      "temperature": 0
    },
    "createdAt": "2025-11-18T07:30:00.000Z",
    "updatedAt": "2025-11-18T07:35:00.000Z",
    "_count": {
      "literatures": 3,
      "screeningResults": 3,
      "screeningTasks": 1
    }
  }
}

测试命令:

curl http://localhost:3001/api/v1/asl/projects/{projectId}

---

1.4 更新项目

接口: PUT /api/v1/asl/projects/:projectId
认证: 需要
说明: 更新项目信息

路径参数:

• projectId: 项目ID (UUID)

请求体（支持部分更新）:

{
  "projectName": "更新后的项目名称",
  "status": "screening",
  "inclusionCriteria": "更新后的纳入标准"
}

响应示例:

{
  "success": true,
  "data": {
    "id": "d67f0b9a-b035-4804-aca1-0bd672c27d81",
    "projectName": "更新后的项目名称",
    "status": "screening",
    ...
  }
}

测试命令:

curl -X PUT http://localhost:3001/api/v1/asl/projects/{projectId} \
  -H "Content-Type: application/json" \
  -d '{"status": "screening"}'

---

1.5 删除项目

接口: DELETE /api/v1/asl/projects/:projectId
认证: 需要
说明: 删除项目及所有关联数据（级联删除）

路径参数:

• projectId: 项目ID (UUID)

响应示例:

{
  "success": true,
  "message": "Project deleted successfully"
}

测试命令:

curl -X DELETE http://localhost:3001/api/v1/asl/projects/{projectId}

---

2. 文献管理 (Literatures)

2.1 导入文献（JSON格式）

接口: POST /api/v1/asl/literatures/import
认证: 需要
说明: 批量导入文献（JSON格式）

请求体:

{
  "projectId": "d67f0b9a-b035-4804-aca1-0bd672c27d81",
  "literatures": [
    {
      "pmid": "12345678",
      "title": "Efficacy of SGLT2 inhibitors in type 2 diabetes",
      "abstract": "Background: SGLT2 inhibitors are a new class...",
      "authors": "Smith J, Jones A, Brown B",
      "journal": "New England Journal of Medicine",
      "publicationYear": 2020,
      "doi": "10.1056/NEJMoa1234567"
    },
    {
      "title": "Another study on SGLT2 inhibitors",
      "abstract": "Objective: To evaluate...",
      "authors": "Johnson M",
      "journal": "The Lancet",
      "publicationYear": 2019
    }
  ]
}

响应示例:

{
  "success": true,
  "data": {
    "importedCount": 2
  }
}

字段说明:

• pmid: PubMed ID (可选)
• title: 文献标题 (必填)
• abstract: 摘要 (必填)
• authors: 作者 (可选)
• journal: 期刊 (可选)
• publicationYear: 发表年份 (可选)
• doi: DOI (可选)

测试命令:

curl -X POST http://localhost:3001/api/v1/asl/literatures/import \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "{projectId}",
    "literatures": [
      {
        "title": "测试文献",
        "abstract": "这是测试摘要"
      }
    ]
  }'

---

2.2 导入文献（Excel文件）

接口: POST /api/v1/asl/literatures/import-excel
认证: 需要
说明: 从Excel文件批量导入文献

请求类型: multipart/form-data

表单字段:

• file: Excel文件 (.xlsx)
• projectId: 项目ID

Excel格式要求:

列名（中英文均可）	必填	说明
PMID / pmid / PMID编号	否	PubMed ID
Title / title / 标题	是	文献标题
Abstract / abstract / 摘要	是	摘要
Authors / authors / 作者	否	作者
Journal / journal / 期刊	否	期刊名称
Year / year / 年份	否	发表年份
DOI / doi	否	DOI

响应示例:

{
  "success": true,
  "data": {
    "importedCount": 15,
    "totalRows": 15
  }
}

测试命令:

curl -X POST http://localhost:3001/api/v1/asl/literatures/import-excel \
  -F "file=@literatures.xlsx" \
  -F "projectId={projectId}"

---

2.3 获取文献列表

接口: GET /api/v1/asl/projects/:projectId/literatures
认证: 需要
说明: 获取项目的文献列表（支持分页）

路径参数:

• projectId: 项目ID (UUID)

查询参数:

• page: 页码（默认: 1）
• limit: 每页数量（默认: 50，最大: 100）

响应示例:

{
  "success": true,
  "data": {
    "literatures": [
      {
        "id": "lit-uuid-001",
        "projectId": "d67f0b9a-b035-4804-aca1-0bd672c27d81",
        "pmid": "12345678",
        "title": "Efficacy of SGLT2 inhibitors...",
        "abstract": "Background: SGLT2 inhibitors...",
        "authors": "Smith J, Jones A",
        "journal": "NEJM",
        "publicationYear": 2020,
        "doi": "10.1056/NEJMoa1234567",
        "createdAt": "2025-11-18T07:32:00.000Z",
        "screeningResults": [
          {
            "conflictStatus": "none",
            "finalDecision": "include"
          }
        ]
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 3,
      "totalPages": 1
    }
  }
}

测试命令:

curl "http://localhost:3001/api/v1/asl/projects/{projectId}/literatures?page=1&limit=50"

---

2.4 删除文献

接口: DELETE /api/v1/asl/literatures/:literatureId
认证: 需要
说明: 删除指定文献（级联删除筛选结果）

路径参数:

• literatureId: 文献ID (UUID)

响应示例:

{
  "success": true,
  "message": "Literature deleted successfully"
}

测试命令:

curl -X DELETE http://localhost:3001/api/v1/asl/literatures/{literatureId}

---

3. 筛选任务管理 (Screening Tasks)

注意: 以下接口为待实现功能（Week 2计划）

3.1 启动筛选任务

接口: POST /api/v1/asl/projects/:projectId/screening/start
认证: 需要
说明: 启动AI筛选任务（异步执行）

请求体:

{
  "taskType": "title_abstract",
  "models": ["deepseek-chat", "qwen-max"],
  "concurrency": 3
}

响应示例:

{
  "success": true,
  "data": {
    "taskId": "task-uuid-001",
    "status": "running",
    "totalItems": 100,
    "startedAt": "2025-11-18T08:00:00.000Z"
  }
}

---

3.2 获取筛选进度

接口: GET /api/v1/asl/tasks/:taskId/progress
认证: 需要
说明: 获取筛选任务进度

响应示例:

{
  "success": true,
  "data": {
    "taskId": "task-uuid-001",
    "status": "running",
    "totalItems": 100,
    "processedItems": 45,
    "successItems": 40,
    "failedItems": 2,
    "conflictItems": 3,
    "progress": 45,
    "estimatedEndAt": "2025-11-18T08:15:00.000Z"
  }
}

---

3.3 获取筛选结果

接口: GET /api/v1/asl/projects/:projectId/results
认证: 需要
说明: 获取筛选结果列表

查询参数:

• page: 页码（默认: 1）
• limit: 每页数量（默认: 50）
• conflictOnly: 只显示冲突项（布尔值）
• finalDecision: 筛选决策（include / exclude / pending）

响应示例:

{
  "success": true,
  "data": {
    "results": [
      {
        "id": "result-uuid-001",
        "literatureId": "lit-uuid-001",
        "literature": {
          "title": "...",
          "abstract": "..."
        },
        "dsConclusion": "include",
        "qwenConclusion": "include",
        "conflictStatus": "none",
        "finalDecision": "include",
        "createdAt": "2025-11-18T08:05:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 100,
      "totalPages": 2
    }
  }
}

---

3.4 审核冲突文献

接口: POST /api/v1/asl/results/review
认证: 需要
说明: 批量审核冲突文献

请求体:

{
  "projectId": "d67f0b9a-b035-4804-aca1-0bd672c27d81",
  "reviews": [
    {
      "resultId": "result-uuid-001",
      "finalDecision": "include"
    },
    {
      "resultId": "result-uuid-002",
      "finalDecision": "exclude",
      "exclusionReason": "不符合PICO标准中的干预措施"
    }
  ]
}

响应示例:

{
  "success": true,
  "data": {
    "reviewedCount": 2
  }
}

---

📋 响应格式规范

1. 成功响应

格式:

{
  "success": true,
  "data": {
    // 响应数据
  }
}

HTTP状态码:

• 200 - 成功（GET、PUT）
• 201 - 创建成功（POST）

---

2. 错误响应

格式:

{
  "success": false,
  "error": "错误描述"
}

或（详细错误）:

{
  "error": "Missing required fields"
}

常见HTTP状态码:

• 400 - 请求参数错误
• 401 - 未授权
• 403 - 无权限
• 404 - 资源不存在
• 500 - 服务器内部错误

错误示例:

// 400 - 参数错误
{
  "error": "Missing required fields"
}

// 404 - 资源不存在
{
  "error": "Project not found"
}

// 500 - 服务器错误
{
  "error": "Failed to create project"
}

---

3. 分页响应

格式:

{
  "success": true,
  "data": {
    "items": [...],  // 或 literatures、results 等
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 150,
      "totalPages": 3
    }
  }
}

分页参数:

• page: 当前页码（从1开始）
• limit: 每页数量
• total: 总记录数
• totalPages: 总页数

---

🔐 认证授权

当前状态（测试模式）

测试用户:

• 用户ID: asl-test-user-001
• 邮箱: asl-test@example.com
• 权限: 完全访问

实现方式:

• 优先从JWT中获取userId
• JWT不存在时使用默认测试用户ID

生产环境（待实现）

认证流程:

1. 用户登录获取JWT Token
2. 请求头携带Token: Authorization: Bearer {token}
3. 中间件验证Token并提取userId
4. 控制器使用userId查询用户数据

中间件示例:

// 待实现
fastify.addHook('preHandler', async (request, reply) => {
  const token = request.headers.authorization?.replace('Bearer ', '');
  if (!token) {
    return reply.status(401).send({ error: 'Unauthorized' });
  }
  const userId = await verifyJWT(token);
  (request as any).userId = userId;
});

---

🧪 API测试

快速测试脚本

测试所有API:

cd AIclinicalresearch/backend
npx tsx scripts/test-asl-api.ts

测试结果:

🚀 开始测试 ASL 模块 API...
📍 测试 1/7: 健康检查              ✅
📍 测试 2/7: 创建筛选项目          ✅
📍 测试 3/7: 获取项目列表          ✅
📍 测试 4/7: 获取项目详情          ✅
📍 测试 5/7: 导入文献              ✅
📍 测试 6/7: 获取文献列表          ✅
📍 测试 7/7: 更新项目              ✅
═══════════════════════════════════
🎉 所有测试通过！(7/7 - 100%)
═══════════════════════════════════

Postman集合

导入说明:

1. 创建新的Collection: ASL API
2. 设置环境变量:
   • base_url: http://localhost:3001
   • api_prefix: /api/v1/asl
3. 导入下方接口

示例请求 (Postman):

POST {{base_url}}{{api_prefix}}/projects
Headers:
  Content-Type: application/json
Body (raw JSON):
{
  "projectName": "测试项目",
  "picoCriteria": {...},
  "inclusionCriteria": "英文文献",
  "exclusionCriteria": "综述"
}

---

📊 性能指标

响应时间目标

接口类型	目标响应时间	说明
单个查询	< 100ms	项目详情、文献详情
列表查询	< 200ms	项目列表、文献列表
创建/更新	< 300ms	创建项目、更新项目
批量导入	< 2s	导入100篇文献
LLM筛选	4-6s/篇	双模型并行筛选

并发能力

• API服务器: 支持100+并发请求
• LLM筛选: 并发数为3（可配置）
• 数据库连接池: 17个连接

---

🔄 版本历史

v2.0 (2025-11-18)

• ✅ 实现10个核心API端点
• ✅ 完成项目管理功能
• ✅ 完成文献管理功能
• ✅ 添加测试脚本和文档
• ✅ 所有接口测试通过

v1.0 (2025-10-29)

• 初始API设计规范
• 定义接口结构

---

⏳ 后续规划

Week 2

• 实现筛选任务API (3个接口)
• 实现冲突审核API (2个接口)
• 添加SSE进度推送
• 集成异步任务队列

Week 3-4

• 添加JWT认证中间件
• 实现权限控制
• 添加API限流
• 完善错误处理

---

文档版本： v2.0
最后更新： 2025-11-18
维护者： AI智能文献开发团队

---

📚 相关文档

• 数据库设计文档
• API测试报告
• Week 1完成报告