HaHafeng
4c5bb3d174
- Add iit_schema with 5 tables - Create module structure and types (223 lines) - WeChat integration verified (Access Token success) - Update system docs to v2.4 - Add REDCap source folders to .gitignore - Day 1/14 complete (11/11 tasks)
92 lines
4.8 KiB
Markdown
92 lines
4.8 KiB
Markdown
# **文档 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 专家 | **状态**：详细设计完成 |