# **文档 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 专家 | **状�?*：详细设计完�