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

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

> **文档版本：** v3.0  
> **创建日期：** 2025-10-29  
> **维护者：** AI智能文献开发团队  
> **最后更新：** 2025-11-23  
> **更新说明：** 新增全文复筛API（5个核心接口）

---

## 📋 文档说明

本文档描述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)  
**说明**: 创建一个新的文献筛选项目

**请求体**:
```json
{
  "projectName": "SGLT2抑制剂系统综述",
  "picoCriteria": {
    "P": "2型糖尿病成人患者",
    "I": "SGLT2抑制剂（empagliflozin、dapagliflozin等）",
    "C": "安慰剂或常规降糖疗法",
    "O": "心血管结局（MACE、心衰住院、心血管死亡）",
    "S": "随机对照试验 (RCT)"
  },
  "inclusionCriteria": "英文文献，RCT研究，2010年后发表",
  "exclusionCriteria": "病例报告，综述，动物实验",
  "screeningConfig": {
    "models": ["deepseek-chat", "qwen-max"],
    "temperature": 0
  }
}
```

**响应示例**:
```json
{
  "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"
  }
}
```

**测试命令**:
```bash
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`  
**认证**: 需要  
**说明**: 获取当前用户的所有筛选项目

**查询参数**: 无

**响应示例**:
```json
{
  "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
      }
    }
  ]
}
```

**测试命令**:
```bash
curl http://localhost:3001/api/v1/asl/projects
```

---

#### 1.3 获取项目详情

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

**路径参数**:
- `projectId`: 项目ID (UUID)

**响应示例**:
```json
{
  "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
    }
  }
}
```

**测试命令**:
```bash
curl http://localhost:3001/api/v1/asl/projects/{projectId}
```

---

#### 1.4 更新项目

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

**路径参数**:
- `projectId`: 项目ID (UUID)

**请求体**（支持部分更新）:
```json
{
  "projectName": "更新后的项目名称",
  "status": "screening",
  "inclusionCriteria": "更新后的纳入标准"
}
```

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

**测试命令**:
```bash
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)

**响应示例**:
```json
{
  "success": true,
  "message": "Project deleted successfully"
}
```

**测试命令**:
```bash
curl -X DELETE http://localhost:3001/api/v1/asl/projects/{projectId}
```

---

### 2. 文献管理 (Literatures)

#### 2.1 导入文献（JSON格式）

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

**请求体**:
```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
    }
  ]
}
```

**响应示例**:
```json
{
  "success": true,
  "data": {
    "importedCount": 2
  }
}
```

**字段说明**:
- `pmid`: PubMed ID (可选)
- `title`: 文献标题 (必填)
- `abstract`: 摘要 (必填)
- `authors`: 作者 (可选)
- `journal`: 期刊 (可选)
- `publicationYear`: 发表年份 (可选)
- `doi`: DOI (可选)

**测试命令**:
```bash
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 |

**响应示例**:
```json
{
  "success": true,
  "data": {
    "importedCount": 15,
    "totalRows": 15
  }
}
```

**测试命令**:
```bash
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）

**响应示例**:
```json
{
  "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
    }
  }
}
```

**测试命令**:
```bash
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)

**响应示例**:
```json
{
  "success": true,
  "message": "Literature deleted successfully"
}
```

**测试命令**:
```bash
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筛选任务（异步执行）

**请求体**:
```json
{
  "taskType": "title_abstract",
  "models": ["deepseek-chat", "qwen-max"],
  "concurrency": 3
}
```

**响应示例**:
```json
{
  "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`  
**认证**: 需要  
**说明**: 获取筛选任务进度

**响应示例**:
```json
{
  "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）

**响应示例**:
```json
{
  "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`  
**认证**: 需要  
**说明**: 批量审核冲突文献

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

**响应示例**:
```json
{
  "success": true,
  "data": {
    "reviewedCount": 2
  }
}
```

---

### 4. 全文复筛管理 (Fulltext Screening)

> **状态**: ✅ Day 5实现中（2025-11-23）

#### 4.1 创建全文复筛任务

**接口**: `POST /api/v1/asl/fulltext-screening/tasks`  
**认证**: 需要  
**说明**: 创建全文复筛任务，对标题初筛通过的文献进行12字段评估

**请求体**:
```json
{
  "projectId": "proj-123",
  "literatureIds": ["lit-001", "lit-002", "lit-003"],
  "modelA": "deepseek-v3",
  "modelB": "qwen-max",
  "promptVersion": "v1.0.0"
}
```

**字段说明**:
- `projectId`: 项目ID（必填）
- `literatureIds`: 待筛选文献ID列表（必填，需要是标题初筛通过的文献）
- `modelA`: 模型A名称（可选，默认: deepseek-v3）
- `modelB`: 模型B名称（可选，默认: qwen-max）
- `promptVersion`: Prompt版本（可选，默认: v1.0.0）

**响应示例**:
```json
{
  "success": true,
  "data": {
    "taskId": "fst-20251123-001",
    "projectId": "proj-123",
    "status": "pending",
    "totalCount": 3,
    "modelA": "deepseek-v3",
    "modelB": "qwen-max",
    "createdAt": "2025-11-23T10:00:00.000Z",
    "message": "任务创建成功，正在后台处理"
  }
}
```

**业务规则**:
1. 验证所有文献是否属于该项目
2. 检查文献是否有可用的PDF（`pdfStatus === 'ready'`）
3. 任务创建后立即返回，后台异步处理
4. 如果部分文献PDF未就绪，仅处理PDF就绪的文献

**错误响应**:
```json
{
  "success": false,
  "error": "部分文献PDF未就绪，无法开始全文复筛"
}
```

**测试命令**:
```bash
curl -X POST http://localhost:3001/api/v1/asl/fulltext-screening/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "proj-123",
    "literatureIds": ["lit-001", "lit-002"],
    "modelA": "deepseek-v3",
    "modelB": "qwen-max"
  }'
```

---

#### 4.2 获取任务进度

**接口**: `GET /api/v1/asl/fulltext-screening/tasks/:taskId`  
**认证**: 需要  
**说明**: 获取全文复筛任务的详细进度信息

**路径参数**:
- `taskId`: 任务ID

**响应示例**:
```json
{
  "success": true,
  "data": {
    "taskId": "fst-20251123-001",
    "projectId": "proj-123",
    "status": "processing",
    
    "progress": {
      "totalCount": 30,
      "processedCount": 15,
      "successCount": 13,
      "failedCount": 1,
      "degradedCount": 1,
      "pendingCount": 15,
      "progressPercent": 50
    },
    
    "statistics": {
      "totalTokens": 450000,
      "totalCost": 2.25,
      "avgTimePerLit": 18500
    },
    
    "time": {
      "startedAt": "2025-11-23T10:00:00.000Z",
      "estimatedEndAt": "2025-11-23T10:12:30.000Z",
      "elapsedSeconds": 270
    },
    
    "models": {
      "modelA": "deepseek-v3",
      "modelB": "qwen-max"
    },
    
    "updatedAt": "2025-11-23T10:04:30.000Z"
  }
}
```

**字段说明**:
- `status`: 任务状态
  - `pending`: 待处理
  - `processing`: 处理中
  - `completed`: 已完成
  - `failed`: 失败
  - `cancelled`: 已取消
- `successCount`: 双模型都成功的文献数
- `degradedCount`: 仅一个模型成功的文献数（降级模式）
- `failedCount`: 双模型都失败的文献数
- `totalCost`: 累计成本（单位：元）

**测试命令**:
```bash
curl http://localhost:3001/api/v1/asl/fulltext-screening/tasks/fst-20251123-001
```

---

#### 4.3 获取任务结果

**接口**: `GET /api/v1/asl/fulltext-screening/tasks/:taskId/results`  
**认证**: 需要  
**说明**: 获取全文复筛任务的详细结果，支持筛选和分页

**路径参数**:
- `taskId`: 任务ID

**查询参数**:
- `filter`: 结果筛选（可选）
  - `all`: 全部（默认）
  - `conflict`: 仅冲突项
  - `pending`: 待审核
  - `reviewed`: 已审核
- `page`: 页码（默认: 1）
- `pageSize`: 每页数量（默认: 20，最大: 100）
- `sortBy`: 排序字段（可选: `priority`, `createdAt`）
- `sortOrder`: 排序方向（`asc` | `desc`，默认: `desc`）

**响应示例**:
```json
{
  "success": true,
  "data": {
    "taskId": "fst-20251123-001",
    "total": 30,
    "filtered": 3,
    
    "results": [
      {
        "resultId": "fsr-001",
        "literatureId": "lit-001",
        "literature": {
          "pmid": "12345678",
          "title": "Effect of SGLT2 inhibitors on cardiovascular outcomes",
          "authors": "Smith JA, et al.",
          "journal": "Lancet",
          "year": 2023,
          "doi": "10.1016/..."
        },
        
        "modelAResult": {
          "modelName": "deepseek-v3",
          "status": "success",
          "fields": {
            "field1_source": {
              "assessment": "完整",
              "evidence": "第一作者Smith JA, Lancet 2023",
              "location": "第1页",
              "confidence": 0.98
            },
            "field2_studyType": {
              "assessment": "完整",
              "evidence": "多中心随机对照试验",
              "location": "Methods第2页",
              "confidence": 0.95
            },
            "field5_population": {
              "assessment": "完整",
              "evidence": "纳入500例2型糖尿病患者，年龄58±12岁",
              "location": "Methods第3页",
              "confidence": 0.92
            },
            "field9_outcomes": {
              "assessment": "完整",
              "evidence": "主要结局eGFR变化：-15.2±3.5 ml/min vs -8.1±2.9 ml/min",
              "location": "Results第5页表2",
              "confidence": 0.96
            }
          },
          "overall": {
            "decision": "include",
            "reason": "12字段完整，关键数据可提取",
            "dataQuality": "high",
            "confidence": 0.94
          },
          "tokens": 15000,
          "cost": 0.015
        },
        
        "modelBResult": {
          "modelName": "qwen-max",
          "status": "success",
          "fields": { /* 同上结构 */ },
          "overall": {
            "decision": "include",
            "confidence": 0.92
          },
          "tokens": 15200,
          "cost": 0.061
        },
        
        "validation": {
          "medicalLogicIssues": [],
          "evidenceChainIssues": []
        },
        
        "conflict": {
          "isConflict": false,
          "severity": "none",
          "conflictFields": [],
          "overallConflict": false
        },
        
        "review": {
          "finalDecision": null,
          "reviewedBy": null,
          "reviewedAt": null,
          "reviewNotes": null,
          "priority": 50
        },
        
        "processing": {
          "isDegraded": false,
          "degradedModel": null,
          "processedAt": "2025-11-23T10:02:15.000Z"
        }
      },
      
      {
        "resultId": "fsr-002",
        "literatureId": "lit-005",
        "literature": { /* ... */ },
        
        "modelAResult": {
          "modelName": "deepseek-v3",
          "status": "success",
          "fields": {
            "field9_outcomes": {
              "assessment": "缺失",
              "evidence": "未报告具体数值，仅有P值",
              "location": "Results第4页",
              "confidence": 0.88
            }
          },
          "overall": {
            "decision": "exclude",
            "reason": "关键字段field9数据不完整，无法Meta分析",
            "confidence": 0.85
          }
        },
        
        "modelBResult": {
          "overall": {
            "decision": "include",
            "reason": "虽然主要结局在Discussion报告，但数据完整"
          }
        },
        
        "conflict": {
          "isConflict": true,
          "severity": "high",
          "conflictFields": ["field9"],
          "overallConflict": true,
          "details": {
            "field9": {
              "modelA": "缺失",
              "modelB": "完整",
              "importance": "critical"
            }
          }
        },
        
        "review": {
          "finalDecision": null,
          "priority": 95
        }
      }
    ],
    
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "totalPages": 2
    },
    
    "summary": {
      "totalResults": 30,
      "conflictCount": 3,
      "pendingReview": 3,
      "reviewed": 27,
      "avgPriority": 62
    }
  }
}
```

**12字段说明**:
- `field1_source`: 文献来源（作者、期刊、年份等）
- `field2_studyType`: 研究类型（RCT、队列研究等）
- `field3_studyDesign`: 研究设计细节
- `field4_diagnosis`: 疾病诊断标准
- `field5_population`: 人群特征（样本量、基线等）⭐
- `field6_baseline`: 基线数据⭐
- `field7_intervention`: 干预措施⭐
- `field8_control`: 对照措施
- `field9_outcomes`: 结局指标⭐⭐⭐ 最关键
- `field10_statistics`: 统计方法
- `field11_quality`: 质量评价（随机化、盲法等）⭐⭐
- `field12_other`: 其他信息

**测试命令**:
```bash
# 获取所有结果
curl "http://localhost:3001/api/v1/asl/fulltext-screening/tasks/fst-20251123-001/results"

# 仅获取冲突项
curl "http://localhost:3001/api/v1/asl/fulltext-screening/tasks/fst-20251123-001/results?filter=conflict"

# 分页查询
curl "http://localhost:3001/api/v1/asl/fulltext-screening/tasks/fst-20251123-001/results?page=2&pageSize=10"
```

---

#### 4.4 人工审核决策

**接口**: `PUT /api/v1/asl/fulltext-screening/results/:resultId/decision`  
**认证**: 需要  
**说明**: 对单个全文复筛结果进行人工审核决策

**路径参数**:
- `resultId`: 结果ID

**请求体**:
```json
{
  "finalDecision": "exclude",
  "exclusionReason": "关键字段field9（结局指标）数据不完整",
  "reviewNotes": "虽然报告了P<0.05，但缺少均值±SD，无法用于Meta分析"
}
```

**字段说明**:
- `finalDecision`: 最终决策（必填）
  - `include`: 纳入
  - `exclude`: 排除
- `exclusionReason`: 排除原因（`finalDecision === 'exclude'` 时必填）
- `reviewNotes`: 审核备注（可选）

**响应示例**:
```json
{
  "success": true,
  "data": {
    "resultId": "fsr-002",
    "finalDecision": "exclude",
    "exclusionReason": "关键字段field9（结局指标）数据不完整",
    "reviewedBy": "user-001",
    "reviewedAt": "2025-11-23T10:30:00.000Z"
  }
}
```

**测试命令**:
```bash
curl -X PUT http://localhost:3001/api/v1/asl/fulltext-screening/results/fsr-002/decision \
  -H "Content-Type: application/json" \
  -d '{
    "finalDecision": "exclude",
    "exclusionReason": "结局指标数据不完整",
    "reviewNotes": "缺少均值和标准差"
  }'
```

---

#### 4.5 导出Excel

**接口**: `GET /api/v1/asl/fulltext-screening/tasks/:taskId/export`  
**认证**: 需要  
**说明**: 导出全文复筛结果为Excel文件（3个Sheet）

**路径参数**:
- `taskId`: 任务ID

**响应**: 
- Content-Type: `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
- Content-Disposition: `attachment; filename="fulltext_screening_results_{taskId}.xlsx"`

**Excel结构**:

**Sheet 1: 纳入文献列表**
| 列名 | 说明 |
|------|------|
| 序号 | 1, 2, 3... |
| PMID | PubMed ID |
| 文献来源 | 第一作者+年份 |
| 标题 | 文献标题 |
| 期刊 | 期刊名称 |
| 年份 | 发表年份 |
| DOI | DOI编号 |
| 最终决策 | 纳入 |
| 数据质量 | 高/中/低 |
| 可提取性 | 可提取/部分可提取/不可提取 |
| 模型一致性 | 一致/不一致 |
| 是否人工审核 | 是/否 |

**Sheet 2: 排除文献列表**
| 列名 | 说明 |
|------|------|
| 序号 | 1, 2, 3... |
| PMID | PubMed ID |
| 文献来源 | 第一作者+年份 |
| 标题 | 文献标题 |
| 排除原因 | 详细排除原因 |
| 排除字段 | field5, field9等 |
| 是否冲突 | 是/否 |
| 审核人 | 用户ID |
| 审核时间 | 2025-11-23 10:30 |

**Sheet 3: PRISMA统计**
| 统计项 | 数量 | 百分比 |
|--------|------|--------|
| 全文复筛总数 | 30 | 100% |
| 最终纳入 | 18 | 60% |
| 最终排除 | 12 | 40% |
| - 结局指标缺失/不完整 | 5 | 16.7% |
| - 人群特征不符 | 3 | 10% |
| - 干预措施不明确 | 2 | 6.7% |
| - 研究质量问题 | 1 | 3.3% |
| - 其他原因 | 1 | 3.3% |
| 模型冲突数 | 3 | 10% |
| 人工审核数 | 3 | 10% |

**成本统计（额外Sheet）**:
| 项目 | 值 |
|------|-----|
| 总Token数 | 450,000 |
| 总成本（元） | ¥2.25 |
| 平均成本/篇 | ¥0.075 |
| 模型组合 | DeepSeek-V3 + Qwen-Max |
| 处理时间 | 8分30秒 |

**测试命令**:
```bash
curl -O -J http://localhost:3001/api/v1/asl/fulltext-screening/tasks/fst-20251123-001/export
```

---

## 📋 响应格式规范

### 1. 成功响应

**格式**:
```json
{
  "success": true,
  "data": {
    // 响应数据
  }
}
```

**HTTP状态码**: 
- `200` - 成功（GET、PUT）
- `201` - 创建成功（POST）

---

### 2. 错误响应

**格式**:
```json
{
  "success": false,
  "error": "错误描述"
}
```

或（详细错误）:
```json
{
  "error": "Missing required fields"
}
```

**常见HTTP状态码**:
- `400` - 请求参数错误
- `401` - 未授权
- `403` - 无权限
- `404` - 资源不存在
- `500` - 服务器内部错误

**错误示例**:
```json
// 400 - 参数错误
{
  "error": "Missing required fields"
}

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

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

---

### 3. 分页响应

**格式**:
```json
{
  "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`查询用户数据

**中间件示例**:
```typescript
// 待实现
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**:
```bash
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个连接

---

## 🔄 版本历史

### v3.0 (2025-11-23)
- ✅ 新增全文复筛管理API（5个接口）
  - 创建任务、获取进度、获取结果、人工审核、导出Excel
- ✅ 支持12字段详细评估
- ✅ 支持双模型对比和冲突检测
- ✅ 完整的Excel导出功能（3 Sheets）
- ✅ 调整文档结构（5大模块）

### v2.1 (2025-11-21)
- ✅ 新增统计API接口
- ✅ 更新PICOS格式说明
- ✅ 添加云原生架构标注

### 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限流
- [ ] 完善错误处理

---

---

### 5. 统计API (Statistics)

#### 5.1 获取项目统计数据（云原生：后端聚合）

**接口**: `GET /api/v1/asl/projects/:projectId/statistics`  
**认证**: 需要  
**说明**: 获取项目的筛选统计数据（总数、纳入率、排除率、排除原因分析等）

**路径参数**:
- `projectId`: 项目ID

**响应示例**:
```json
{
  "success": true,
  "data": {
    "total": 199,
    "included": 85,
    "excluded": 90,
    "pending": 24,
    "conflict": 24,
    "reviewed": 175,
    "exclusionReasons": {
      "P不匹配（人群）": 40,
      "I不匹配（干预）": 25,
      "S不匹配（研究设计）": 15,
      "其他原因": 10
    },
    "includedRate": "42.7",
    "excludedRate": "45.2",
    "pendingRate": "12.1"
  }
}
```

**特点**：
- ✅ 云原生：后端Prisma聚合查询（6个并行查询）
- ✅ 性能：<500ms（199篇文献）
- ✅ 减少网络传输：从MB级降到KB级

**测试命令**:
```bash
curl http://localhost:3001/api/v1/asl/projects/55941145-bba0-4b15-bda4-f0a398d78208/statistics
```---**文档版本：** v3.0  
**最后更新：** 2025-11-23（Day 5: 全文复筛API）  
**维护者：** AI智能文献开发团队**本次更新**：
- ✅ 新增全文复筛管理API（5个核心接口）
- ✅ 详细的12字段评估文档
- ✅ 双模型对比和冲突检测说明
- ✅ Excel导出格式规范
- ✅ 完整的请求/响应示例---## 📚 相关文档- [数据库设计文档](./01-数据库设计.md)
- [API测试报告](../../../backend/ASL-API-测试报告.md)
- [Week 1完成报告](../05-开发记录/2025-11-18-Week1完成报告.md)