# **文档 B：EDC 适配器 (REDCap) 技术详细设计 (V1.0)**

## **1\. 需求映射：PRD V3 对 REDCap 能力的诉求**

基于 IIT Manager Agent V3 的功能定义，适配器必须支持以下 REDCap 核心能力。

### **1.1 感知能力 (Read & Monitor)**

* **实时监听 (Real-time Hook)**：对应“数据质控 Agent”。当 CRC 录入数据时，REDCap 必须能主动“推”出事件。  
* **数据全量/增量导出 (Data Export)**：对应“项目管理 Agent”。需要定期抓取所有记录，进行入组率、完整率的统计分析。  
* **元数据定义获取 (Metadata Export)**：对应“方案数字化”。需要获取项目的表单结构、变量名、字段类型（下拉框/文本框），用于 AI 自动生成映射。

### **1.2 执行能力 (Write & Query)**

* **记录注入与更新 (Record Import)**：对应“数据智能采集 Agent”。AI 识别出的结构化数据需写入指定字段。  
* **质疑管理 (Query/Data Resolution)**：对应“质控 Agent”。AI 发现问题后，需通过接口在 REDCap 中创建“质疑 (Query)”。  
* **用户认证映射 (Auth API)**：确保 Agent 操作时具备合法的 User Token 审计。

## **2\. 技术实现：External Module (EM) 与 REST API 混合架构**

为了实现深度融合且保持高性能，我们采用 **“EM 侧挂插件 \+ Node.js 适配器”** 的混合方案。

### **2.1 External Module (EM) 核心职责：主动钩子**

由于我们拥有 REDCap 源码，我们将开发一个名为 ai\_research\_assistant 的 EM。

* **数据保存钩子 (redcap\_save\_record)**：  
  * **逻辑**：每当记录保存，EM 捕获当前 project\_id 和 record\_id。  
  * **动作**：通过 HTTP POST 发送 Webhook 给 Node.js 后端。  
  * **价值**：实现“质控 Agent”的亚秒级响应。  
* **页面注入钩子 (redcap\_every\_page\_top)**：  
  * **逻辑**：在数据录入页面注入自定义 JS (ai\_assistant.js)。  
  * **动作**：在录入框旁显示 AI 辅助按钮或高亮证据提醒。  
  * **价值**：实现录入阶段的“数字助手”入口。

### **2.2 Node.js EDC Adapter 核心职责：被动访问**

在后端封装 RedcapAdapter 类，处理所有主动抓取任务。

* **API 调用封装**：  
  * exportRecords: 抓取临床数据。  
  * importRecords: 回写影子状态确认后的数据。  
  * exportMetadata: 获取表单变量清单。  
  * importQueries: (基于 EM 的自定义页面) 实现 AI 自动创建质疑。

## **3\. 关键接口清单与实现细节**

### **3.1 核心对接接口表**

| 对接功能 | REDCap 原生 API / EM Hook | 对应的 Agent 动作 |
| :---- | :---- | :---- |
| **实时入组通知** | redcap\_save\_record (Hook) | 触发质控检查、更新日报 |
| **全量数据同步** | exportRecords (API) | 生成周报趋势图、脱落分析 |
| **AI 自动录入** | importRecords (API) | 采集 Agent 写入数据（影子确认后） |
| **数据异常预警** | importQueries (自定义) | 质控 Agent 创建质疑条目 |
| **方案解析映射** | exportMetadata (API) | 获取变量清单进行 AI 语义映射 |

### **3.2 影子状态 (Shadow State) 的回写链路**

这是白皮书的核心要求，其技术实现路径如下：

1. **建议生成**：Agent 结果存入我们的 pending\_actions 表。  
2. **人类审核**：CRC 在 Workbench 点击“确认”。  
3. **适配器调用**：Node.js 提取该条目的 edc\_api\_token，组装标准的 REDCap importRecords JSON 报文。  
4. **回写执行**：  
   // REDCap 接受的数据格式示例  
   \[  
     {"record\_id": "P001", "redcap\_repeat\_instance": 1, "field\_name": "ai\_qc\_status", "value": "2"}  
   \]

5. **审计闭环**：回写成功后，更新 pending\_actions.status \= 'EXECUTED'。

## **4\. 独特技术亮点：External Module 对外合作机制**

利用 REDCap 的 EM 机制，我们可以实现比普通 API 更深入的整合：

1. 自定义菜单链接 (links)：  
   在 REDCap 左侧导航栏直接嵌入 “壹证循 AI 控制中心” 的 H5 链接，让用户不出 EDC 就能使用我们的功能。  
2. 定时任务管理 (crons)：  
   在 REDCap 侧利用 Cron 触发定期的数据健康检查，减轻我们主系统的轮询压力。  
3. 字段级颜色高亮：  
   通过 EM 修改录入页面的 DOM，将 Agent 发现有问题的字段标记为黄色或红色。

## **5\. 安全与认证设计 (Security)**

* **双重 Token 校验**：  
  * **系统级**：EM 访问 Node.js 时，Headers 携带 X-Signature（HMAC-SHA256 加密）。  
  * **用户级**：Node.js 访问 REDCap 时，使用加密存储的 Personal API Token。  
* API 限流 (Rate Limiting)：  
  针对大中心项目，适配器自动对 API 请求进行分片和限流，防止 REDCap 服务器因高频 AI 质控而崩溃。

**维护者**：架构组 & REDCap 专家 | **状态**：详细设计完成