Files

HaHafeng 4c5bb3d174 feat(iit): Initialize IIT Manager Agent MVP - Day 1 complete

- 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)

2025-12-31 18:35:05 +08:00

4.8 KiB

Raw Blame History

文档 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) 的回写链路

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

建议生成：Agent 结果存入我们的 pending_actions 表。
人类审核：CRC 在 Workbench 点击“确认”。
适配器调用：Node.js 提取该条目的 edc_api_token，组装标准的 REDCap importRecords JSON 报文。
回写执行：
// REDCap 接受的数据格式示例
[
{"record_id": "P001", "redcap_repeat_instance": 1, "field_name": "ai_qc_status", "value": "2"}
]
审计闭环：回写成功后，更新 pending_actions.status = 'EXECUTED'。

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

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

自定义菜单链接 (links)：
在 REDCap 左侧导航栏直接嵌入 “壹证循 AI 控制中心” 的 H5 链接，让用户不出 EDC 就能使用我们的功能。
定时任务管理 (crons)：
在 REDCap 侧利用 Cron 触发定期的数据健康检查，减轻我们主系统的轮询压力。
字段级颜色高亮：
通过 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 专家 | 状态：详细设计完成

4.8 KiB Raw Blame History Unescape Escape