# RPA 对接约定（CNKI/万方检索）

本文档用于终端 RPA（影刀）配置参考，说明任务拉取、状态回传与结果上报协议。当前后端已提供完整 REST API，可直接通过 HTTP 调用。

## 1. 基本信息
- 基础地址（Base URL）：根据部署而定，例如 `http://localhost:8080/api`
- 注意：后端配置了 context-path `/api`，所有接口路径需要加上此前缀
- 鉴权：当前环境默认放开 CORS，无鉴权头；生产建议加网关或 Token 认证
- 编码：UTF-8，JSON 请求与响应

## 2. 名词与对象
- Inquiry（查询请求）：一次客户问题受理流程的载体
- RpaTask（RPA 任务）：面向某一数据源（CNKI/WANFANG）的具体检索任务，1 条检索式 = 1 个任务
- SearchResultItem（检索结果项）：RPA 回传的单条文献信息，归属某个 Inquiry

## 3. 任务流转状态
- PENDING → RUNNING → COMPLETED | FAILED
- 失败可被重新拉取并重试（见 4.4）

## 4. API 说明

### 4.1 为某查询创建 RPA 任务（用于前端/调试）
POST `/api/rpa-tasks/inquiry/{inquiryId}/create`

Request Body：
```json
{
  "source": "CNKI",          
  "queryExpressions": [       
    "阿莫西林 AND 不良反应",
    "Amoxicillin adverse events"
  ]
}
```

Response（200）：
```json
{
  "success": true,
  "message": "Success",
  "data": [
    {
      "id": 123,
      "inquiryId": 88,
      "source": "CNKI",
      "status": "PENDING",
      "queryExpression": "阿莫西林 AND 不良反应",
      "remark": null,
      "createdAt": "2025-10-30T12:00:00",
      "startedAt": null,
      "finishedAt": null
    }
  ],
  "timestamp": 1727683200000
}
```

错误响应（400）：
```json
{
  "success": false,
  "message": "数据源不能为空",
  "timestamp": 1727683200000
}
```

### 4.2 获取所有RPA任务（用于管理页面）
GET `/api/rpa-tasks`

说明：返回所有RPA任务，按创建时间倒序排列。

Response（200）：
```json
{
  "success": true,
  "data": [
    {
      "id": 123,
      "inquiryId": 88,
      "source": "CNKI",
      "status": "PENDING",
      "queryExpression": "阿莫西林 AND 不良反应",
      "createdAt": "2025-10-30T12:00:00"
    }
  ]
}
```

### 4.3 获取指定查询的所有RPA任务
GET `/api/rpa-tasks/inquiry/{inquiryId}`

说明：返回指定查询的所有RPA任务，按ID升序排列。

Response（200）：
```json
{
  "success": true,
  "data": [
    {
      "id": 123,
      "inquiryId": 88,
      "source": "CNKI",
      "status": "PENDING",
      "queryExpression": "阿莫西林 AND 不良反应",
      "createdAt": "2025-10-30T12:00:00"
    }
  ]
}
```

### 4.4 RPA 轮询获取待执行任务
GET `/api/rpa-tasks/pending?source=CNKI`

说明：返回 `PENDING` 与 `FAILED` 的任务（失败可重试）。RPA 应按顺序逐个领取。

参数：
- `source`（必填）：数据源，值为 `CNKI` 或 `WANFANG`（不区分大小写，自动转换）

Response（200）：
```json
{
  "success": true,
  "data": [
    {
      "id": 123,
      "inquiryId": 88,
      "source": "CNKI",
      "status": "PENDING",
      "queryExpression": "阿莫西林 AND 不良反应",
      "createdAt": "2025-10-30T12:00:00"
    }
  ]
}
```

### 4.5 RPA 标记任务开始
POST `/api/rpa-tasks/{taskId}/start`

Response（200）：
```json
{
  "success": true,
  "data": {
    "id": 123,
    "status": "RUNNING",
    "startedAt": "2025-10-30T12:01:00"
  }
}
```

### 4.6 RPA 回传检索结果
POST `/api/rpa-tasks/{taskId}/results`
      
Request Body：数组，单项结构如下（尽可能填充，字段均为可选）：
```json
[
  {
    "title": "文献题目",
    "authors": "作者A; 作者B",          
    "source": "CNKI",                   
    "sourceUrl": "https://...",        
    "publicationDate": "2023-09-01",   
    "summary": "摘要...",
    "content": "全文内容（可选）",
    "doi": "10.xxxx/xxx（可选）",
    "pmid": "12345678（可选）",
    "metadata": "{}（可选，后端会注入rpaTaskId和queryExpression）"
  }
]
```
说明：
- 后端会自动补全 `inquiryRequestId`（根据任务关联的查询ID）
- 如果 `source` 为空，会自动设置为任务的数据源
- 后端会在 `metadata` 中注入 `{ rpaTaskId, queryExpression }` 以便前端按任务分组展示
- 如果 `metadata` 已存在，会保留原有内容

Response（200）：
```json
{
  "success": true,
  "data": [
    {
      "id": 999,
      "inquiryRequestId": 88,
      "title": "文献题目",
      "authors": "作者A; 作者B",
      "source": "CNKI",
      "sourceUrl": "https://...",
      "publicationDate": "2023-09-01",
      "summary": "摘要...",
      "metadata": "{\"rpaTaskId\":123,\"queryExpression\":\"阿莫西林 AND 不良反应\"}",
      "status": "ACTIVE",
      "includeInResponse": false,
      "needDownload": false,
      "createdAt": "2025-10-30T12:02:00"
    }
  ]
}
```
任务成功回传后，任务状态将置为 `COMPLETED`。

### 4.7 RPA 回传结果（CNKI字符串格式）
POST `/api/rpa-tasks/{taskId}/results/text`

说明：接收CNKI引用格式的字符串，后端自动解析为检索结果项。适用于影刀RPA机器人返回的CNKI引用格式数据。

Request Body（字符串格式）：
```
[1]王冰冰. 注射用醋酸曲普瑞林序贯地诺孕素治疗卵巢子宫内膜异位症的临床效果[J].临床合理用药,2025,18(30):125-127.DOI:10.15887/j.cnki.13-1389/r.2025.30.034.
[2]黄婉茹,黄小盼,林少勇. 醋酸曲普瑞林联合重组人生长激素治疗大骨龄特发性中枢性性早熟女童的效果观察[J].大医生,2025,10(19):62-64.
```

格式说明：
- `[序号]`：文献序号
- `作者.`：作者信息（以.结尾）
- `标题[J].`：文章标题和文献类型[J]（期刊）
- `期刊名,`：期刊名称（以,结尾）
- `年份,`：发表年份（以,结尾）
- `卷(期):页码`：卷号、期号和页码（如18(30):125-127）
- `.DOI:xxx`：DOI号（可选，以.DOI:开头）

特殊处理：
- 如果 `rawResult` 为空或null，表示未检索到文献，任务仍会标记为完成（状态：COMPLETED），但返回空结果列表
- 后端会自动解析字符串，提取以下字段：
  - `title`：文章题目
  - `authors`：作者
  - `summary`：期刊名称
  - `publicationDate`：发表年份
  - `content`：卷期页码信息（格式：卷:18, 期:30, 页码:125-127）
  - `doi`：DOI号
  - `sourceUrl`：DOI链接（如果有DOI，自动构造 https://dx.doi.org/{doi}）
  - `source`：自动设置为"CNKI"

Response（200）：
```json
{
  "success": true,
  "data": [
    {
      "id": 999,
      "inquiryRequestId": 88,
      "title": "注射用醋酸曲普瑞林序贯地诺孕素治疗卵巢子宫内膜异位症的临床效果",
      "authors": "王冰冰",
      "source": "CNKI",
      "summary": "临床合理用药",
      "publicationDate": "2025",
      "content": "卷:18, 期:30, 页码:125-127",
      "doi": "10.15887/j.cnki.13-1389/r.2025.30.034",
      "sourceUrl": "https://dx.doi.org/10.15887/j.cnki.13-1389/r.2025.30.034",
      "metadata": "{\"rpaTaskId\":123,\"queryExpression\":\"阿莫西林 AND 不良反应\"}"
    }
  ]
}
```

### 4.8 RPA 标记任务失败（可重试）
POST `/api/rpa-tasks/{taskId}/fail?reason=网络错误`

参数：
- `reason`（可选）：失败原因说明

Response（200）：
```json
{
  "success": true,
  "data": {
    "id": 123,
    "inquiryId": 88,
    "source": "CNKI",
    "status": "FAILED",
    "queryExpression": "阿莫西林 AND 不良反应",
    "remark": "网络错误",
    "createdAt": "2025-10-30T12:00:00",
    "startedAt": "2025-10-30T12:01:00",
    "finishedAt": "2025-10-30T12:05:00"
  }
}
```

## 5. 参数验证与错误处理

### 5.1 创建任务参数验证
- `inquiryId`：必须为有效数字，且对应的查询请求存在
- `source`：必须为 `CNKI` 或 `WANFANG`（不区分大小写，自动转换为大写）
- `queryExpressions`：必须为非空数组，每个检索式不能为空字符串
- 空的检索式会被自动跳过，但至少需要有一个有效检索式才能创建任务

### 5.2 错误响应格式
所有接口在发生错误时会返回统一的错误响应：
```json
{
  "success": false,
  "message": "错误描述信息",
  "timestamp": 1727683200000
}
```

常见HTTP状态码：
- `400 Bad Request`：参数验证失败（如数据源为空、检索式列表为空等）
- `500 Internal Server Error`：服务器内部错误（如数据库连接失败等）

### 5.3 异常处理说明
- `IllegalArgumentException`：参数验证失败，返回 400 状态码
- `RuntimeException`：业务逻辑错误（如任务不存在），返回 500 状态码

## 6. 建议的轮询与执行策略
- 轮询频率：每 60 秒调用一次 4.4 接口（获取待处理任务）；若无任务可适当退避
- 领取策略：
  1) 调用 4.4 拉取待处理任务列表；2) 取第一条 `taskId` 调用 4.5 标记开始；3) 执行检索；
  4) 根据返回数据格式选择接口：
     - 如果返回JSON格式数组，调用 4.6 接口（标准格式）
     - 如果返回CNKI引用格式字符串，调用 4.7 接口（字符串格式，自动解析）
  5) 异常则调用 4.8 标记失败（可重试）
- 并发建议：同一来源每台终端控制在 1~2 并发，避免目标站封禁

## 7. 字段说明（摘要）

### 7.1 RpaTaskDTO 字段
- `id`：任务ID（Long）
- `inquiryId`：关联的查询请求ID（Long）
- `source`：数据源，值为 `CNKI` 或 `WANFANG`（String）
- `status`：任务状态，值为 `PENDING`、`RUNNING`、`COMPLETED`、`FAILED`（String）
- `queryExpression`：检索表达式（String，最大长度2000）
- `remark`：备注信息，如失败原因（String，最大长度1024，可选）
- `createdAt`：创建时间（LocalDateTime）
- `startedAt`：开始执行时间（LocalDateTime，可选）
- `finishedAt`：完成时间（LocalDateTime，可选）

### 7.2 SearchResultItemDTO 回传字段（主要字段）
- `title`：文献标题（String，可选）
- `authors`：作者（String，可选）
- `source`：数据源（String，如果为空会使用任务的数据源）
- `sourceUrl`：源链接（String，可选）
- `publicationDate`：发表日期（String，可选）
- `summary`：摘要（String，可选）
- `content`：全文内容（String，可选）
- `doi`：DOI号（String，可选）
- `pmid`：PMID号（String，可选）
- `nctId`：NCT ID（String，可选）
- `metadata`：元数据JSON字符串（String，可选，后端会注入rpaTaskId和queryExpression）

注意：后端会自动设置以下字段：
- `inquiryRequestId`：根据任务关联的查询ID自动设置
- `source`：如果为空，使用任务的数据源
- `metadata`：如果为空，会注入 `{"rpaTaskId":xxx,"queryExpression":"xxx"}`；如果已有内容，会保留

## 8. 示例（curl）

获取所有任务：
```bash
curl -X GET "http://localhost:8080/api/rpa-tasks"
```

获取指定查询的任务：
```bash
curl -X GET "http://localhost:8080/api/rpa-tasks/inquiry/88"
```

获取待处理任务：
```bash
curl -X GET "http://localhost:8080/api/rpa-tasks/pending?source=CNKI"
```

创建任务：
```bash
curl -X POST "http://localhost:8080/api/rpa-tasks/inquiry/88/create" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "CNKI",
    "queryExpressions": ["阿莫西林 AND 不良反应", "Amoxicillin adverse events"]
  }'
```

标记开始：
```bash
curl -X POST "http://localhost:8080/api/rpa-tasks/123/start"
```

回传结果：
```bash
curl -X POST "http://localhost:8080/api/rpa-tasks/123/results" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "title": "文献题目",
      "authors": "作者A; 作者B",
      "source": "CNKI",
      "sourceUrl": "https://example.com",
      "publicationDate": "2023-09-01",
      "summary": "摘要..."
    }
  ]'
```

标记失败：
```bash
curl -X POST "http://localhost:8080/api/rpa-tasks/123/fail?reason=网络错误"
```

回传结果（CNKI字符串格式）：
```bash
curl -X POST "http://localhost:8080/api/rpa-tasks/123/results/text" \
  -H "Content-Type: application/json" \
  -d '[1]王冰冰. 注射用醋酸曲普瑞林序贯地诺孕素治疗卵巢子宫内膜异位症的临床效果[J].临床合理用药,2025,18(30):125-127.DOI:10.15887/j.cnki.13-1389/r.2025.30.034.'
```

注意：字符串格式接口需要传递纯文本字符串，不是JSON格式。

## 9. 前端展示要点（供联调参考）
- 查询详情页"知网"Tab 按 `{ rpaTaskId, queryExpression }` 分组展示；RPA 回传后点击"刷新"即可看到新结果
- 前端会从 `metadata` 字段解析 `rpaTaskId` 和 `queryExpression` 来分组显示结果

## 10. 常见问题

### 10.1 任务重复执行
若上一次失败，任务会出现在待处理列表（状态为 `FAILED`），可再次执行并回传。

### 10.2 去重处理
如需服务器去重，可在回传时于 `metadata` 提供文献唯一标识，后续可在服务端增加去重逻辑。

### 10.3 数据源大小写
`source` 参数不区分大小写，后端会自动转换为大写（`CNKI` 或 `WANFANG`）。

### 10.4 空检索式处理
创建任务时，空的检索式会被自动跳过。但至少需要有一个有效检索式才能创建任务。

### 10.5 任务状态说明
- `PENDING`：待处理，等待RPA终端拉取执行
- `RUNNING`：执行中，RPA终端已标记开始
- `COMPLETED`：已完成，结果已成功回传
- `FAILED`：执行失败，可重新拉取并重试