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)
This commit is contained in:
@@ -0,0 +1,85 @@
|
||||
# **IIT Manager Agent 多端交互流程与权限设计 (V1.0)**
|
||||
|
||||
## **1\. 核心角色定义与终端矩阵**
|
||||
|
||||
系统通过“基础角色 \+ 扩展权限”模式，支持单中心与多中心项目的灵活配置。
|
||||
|
||||
| 角色代码 | 角色名称 | 核心职责 | 主要终端 | 核心权限 |
|
||||
| :---- | :---- | :---- | :---- | :---- |
|
||||
| **SYS\_ADMIN** | 系统管理员 | 平台初始化、多租户管理、Dify 知识库维护 | PC 端 (Admin Portal) | 全局配置、资源分配 |
|
||||
| **PROJECT\_PI** | 项目负责人 (PI) | 项目进度监控、重大偏离决策、智能报表查看 | 微信端 (企微通知+小程序) | 影子状态最终审批、导出报表 |
|
||||
| **CRC\_OPERATOR** | 协调员 (CRC) | 数据录入、AI 建议复核、患者随访执行 | REDCap (录入) \+ PC Workbench | 质疑处理、数据采集、患者互动 |
|
||||
| **SUBJECT\_PATIENT** | 患者 (受试者) | 接收提醒、咨询答疑、AE/随访上报 | 个人微信 (H5/小程序) | 任务反馈、问答咨询 |
|
||||
| **SUB\_I / CO\_PI** | 子中心负责人 | 分中心数据查看、本中心流程审批 | 微信端 | 仅限本中心的数据权限 |
|
||||
|
||||
## **2\. 跨终端核心交互流程 (User Journeys)**
|
||||
|
||||
### **2.1 智能质控与影子决策流 (核心闭环)**
|
||||
|
||||
该流程体现了“REDCap 录入 \-\> AI 发现 \-\> Workbench 复核 \-\> 回写 REDCap”的逻辑。
|
||||
|
||||
1. **数据产生**：CRC 在 **REDCap 原生界面**提交受试者 V1 访视数据。
|
||||
2. **监听与推理**：Node.js 接收 Webhook，驱动 **QC Agent** 调用 Dify RAG 检索 Protocol，发现逻辑矛盾。
|
||||
3. **影子生成**：系统在 **Postgres (iit\_schema)** 中生成一条状态为 PROPOSED 的影子记录。
|
||||
4. **即时提醒**：
|
||||
* **PC 端**：CRC 的 Workbench 任务卡片实时更新。
|
||||
* **微信端**：若为严重违背，自动给 PI/CRC 推送企微通知。
|
||||
5. **复核决策**：CRC 登录 **PC Workbench**，查看证据链对比。
|
||||
6. **正式执行**：CRC 点击“确认并更新”，系统调用 REDCap API 将修正值或质疑状态写回 **REDCap**，影子记录状态转为 EXECUTED。
|
||||
|
||||
### **2.2 任务驱动与患者互动流**
|
||||
|
||||
该流程体现了“任务引擎 \-\> 企微触达 \-\> AI 知识库回复”的逻辑。
|
||||
|
||||
1. **任务触发**：任务引擎检测到患者 P001 明日需回访，状态变为 DUE\_SOON。
|
||||
2. **消息推送**：系统通过**企业微信 API**，以 CRC 身份向患者微信发送提醒。
|
||||
3. **患者追问**：患者在微信回复：“我今天需要停药吗？”。
|
||||
4. **AI 处理**：**Counseling Agent** 基于 Dify 知识库生成回答草稿。
|
||||
5. **人工介入**：
|
||||
* 若为简单科普，Agent 直接回复。
|
||||
* 若涉及用药指导，提醒 CRC 在企微侧边栏确认该草稿后再发送。
|
||||
|
||||
### **2.3 PI 宏观管理流**
|
||||
|
||||
1. **周期汇报**：**Reporting Agent** 每周生成统计报表。
|
||||
2. **品牌化展示**：PI 收到企微通知，点击跳转至**小程序**。
|
||||
3. **多租户适配**：小程序根据项目 ID 自动加载 \[北医三院\] 等品牌元素和 Logo。
|
||||
4. **移动决策**：PI 在小程序内对 CRC 提交的疑难问题进行远程批示。
|
||||
|
||||
## **3\. 终端功能边界划分 (Function Boundary)**
|
||||
|
||||
| 功能模块 | PC 管理员门户 | PC Agent Workbench | 微信小程序/H5 | 企业微信通知 |
|
||||
| :---- | :---- | :---- | :---- | :---- |
|
||||
| **项目初始化** | 100% (上传方案) | 0% | 0% | 0% |
|
||||
| **字段映射配置** | 100% | 0% | 0% | 0% |
|
||||
| **数据质控审核** | 0% | 100% (深度比对) | 20% (紧急确认) | 0% (仅入口) |
|
||||
| **智能采集(OCR)** | 0% | 100% | 0% | 0% |
|
||||
| **进度/风险报表** | 20% | 50% | 100% (精美可视化) | 10% (卡片摘要) |
|
||||
| **患者沟通记录** | 0% | 100% (归档) | 0% | 100% (实时交互) |
|
||||
|
||||
## **4\. 权限与安全模型 (Access Control)**
|
||||
|
||||
### **4.1 RBAC 权限设计**
|
||||
|
||||
系统采用“功能权限 \+ 数据范围”双重校验：
|
||||
|
||||
* **功能权限 (Permission)**：决定能否点击“确认回写”、“导出报表”。
|
||||
* **数据范围 (Scope)**：
|
||||
* GLOBAL：可看所有中心数据（项目 PI）。
|
||||
* SITE\_ONLY：仅限本中心（子中心 PI/CRC）。
|
||||
* PATIENT\_ONLY：仅限本人（受试者）。
|
||||
|
||||
### **4.2 异构系统身份映射 (Auth Bridge)**
|
||||
|
||||
* **REDCap Token 托管**：每个 CRC/PI 的账户下加密存储其 REDCap API Token。
|
||||
* **企微 OpenID 绑定**：在 iit\_schema.user\_mapping 中建立 SystemUserID \<-\> WeComID 的映射，确保消息精准推送。
|
||||
|
||||
## **5\. 扩展性设计 (Future Roles)**
|
||||
|
||||
对于 **Co-PI** 或 **Sub-I** 等角色，系统支持在 iit\_projects.roles 表中动态添加权限标签：
|
||||
|
||||
* can\_approve\_shadow\_state: 赋予审批权。
|
||||
* can\_view\_audit\_trail: 赋予审计查看权。
|
||||
* can\_manage\_patients: 赋予患者管理权。
|
||||
|
||||
**版本说明**：V1.0 基础版 | **状态**：待评审
|
||||
@@ -0,0 +1,64 @@
|
||||
# **IIT Manager Agent 多端角色与微信端开发指南**
|
||||
|
||||
## **1\. 微信端选型分析：为什么必须是企业微信？**
|
||||
|
||||
在临床研究的长周期中，消息触达的可靠性是第一位的。
|
||||
|
||||
| 特性 | 微信订阅号 | 微信服务号 | 企业微信 (WeCom) |
|
||||
| :---- | :---- | :---- | :---- |
|
||||
| **消息主动性** | 极弱（折叠在文件夹） | 中（模板消息有次数限制） | **强**（可直接发给外部联系人/群） |
|
||||
| **48小时限制** | 有 | 有（用户不互动则无法发信） | **无**（只要是外部联系人，随时触达） |
|
||||
| **身份属性** | 媒体/信息流 | 机构/品牌展示 | **专业/职业属性**（实名认证医生） |
|
||||
| **PI 适用性** | 不推荐 | 一般（仅用于简单日报） | **推荐**（用于决策确认与紧急通知） |
|
||||
| **患者适用性** | 不推荐 | 不推荐（无法长效随访） | **推荐**（CRC通过企微加患者微信） |
|
||||
|
||||
## **2\. 规模化部署下的品牌与归属感方案**
|
||||
|
||||
针对“100 个项目、47 家医院”的规模化场景，传统的“一院一授权”不可行。建议采用 **“中央应用 \+ 动态品牌”** 的架构。
|
||||
|
||||
### **2.1 品牌展示策略 (Branding Strategy)**
|
||||
|
||||
1. **企业简称优化**：申请企业微信认证时，将简称设置为“壹证循临床研究”或“临床研究服务中心”（需配合相关商标或软件著作权证明）。
|
||||
2. **多应用隔离**：针对不同项目创建不同的“自建应用”。
|
||||
* 应用 A：名为“北医三院骨质疏松项目”
|
||||
* 应用 B：名为“北大肿瘤肺癌研究组”
|
||||
3. **消息发送者自定义**：通过企业微信 API，在给 PI 推送消息时，可以将卡片的摘要（Title）动态修改为具体项目组名称。
|
||||
|
||||
### **2.2 小程序 vs 企业微信：深度对比**
|
||||
|
||||
| 维度 | 微信小程序 | 企业微信应用 |
|
||||
| :---- | :---- | :---- |
|
||||
| **品牌突出度** | **极高**（完全独立命名、Logo） | **中**（受限于企业主体的后缀） |
|
||||
| **通知时效性** | **低**（需用户主动订阅，有次数限制） | **极高**（消息直达聊天列表） |
|
||||
| **交互深度** | **强**（复杂的表单、可视化图表） | **中**（多为简单的卡片和 H5 链接） |
|
||||
| **患者依从性** | 依赖用户主动打开习惯 | 依赖 CRC 的私域互动（更强） |
|
||||
|
||||
## **3\. 推荐架构：“通知-落地”双轨模式**
|
||||
|
||||
为了平衡“通知及时性”与“医院品牌感”，推荐以下混合方案：
|
||||
|
||||
1. **统一通知中枢 (WeCom)**：
|
||||
* 使用壹证循统一的企业微信主体。
|
||||
* 负责所有项目的：访视提醒、质控警报、日报推送。
|
||||
* 用户感官：收到一条来自“临床研究助理”的消息。
|
||||
2. **多租户品牌落地 (Mini-Program / H5)**：
|
||||
* PI 或 CRC 点击企微消息，跳转到对应项目的**微信小程序**。
|
||||
* 小程序界面顶部显著展示：\[北京大学肿瘤医院\] 及其 Logo。
|
||||
* 业务逻辑：小程序通过 project\_id 自动渲染对应的品牌元素。
|
||||
|
||||
## **4\. 微信端开发准备清单 (针对 100+ 项目规模)**
|
||||
|
||||
1. **资质准备**：
|
||||
* \[ \] **企业微信代开发模式**：如果希望未来更灵活，可以申请成为“企业微信服务商”。
|
||||
* \[ \] **多域名备案**：准备 1-2 个通用的学术性域名（如 research-support.com）。
|
||||
2. **数据隔离技术**：
|
||||
* \[ \] **WeCom-ID 映射表**：在 iit\_schema 中记录 user\_id 在不同项目应用中的 OpenID。
|
||||
* \[ \] **消息模板引擎**：支持根据不同项目动态生成卡片文案。
|
||||
|
||||
## **5\. 结论**
|
||||
|
||||
* **关于更名**：腾讯不允许无资质的泛指词更名。建议以“公司名+服务中心”作为主体，以“项目组”作为应用名。
|
||||
* **关于小程序**：小程序不适合作为“第一提醒入口”，但非常适合作为“第一展示窗口”。
|
||||
* **最终建议**：**用企业微信推消息，用小程序看报表和填表。** 这样既解决了 47 家医院的对接难点，又通过小程序给足了 PI 面子。
|
||||
|
||||
**版本**：V3.1 (规模化修正版) | **最后更新**：2025-12-30
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,47 @@
|
||||
# **REDCap 原生录入与 AI Workbench 操作边界划分**
|
||||
|
||||
针对您的关键问题：“CRC 到底在哪里录入数据？”，我们采取\*\*“双轨并行，场景区分”\*\*的原则。
|
||||
|
||||
## **1\. 核心策略：尊重“数据真理源”**
|
||||
|
||||
* **原则**：为了确保 GxP 合规性和维护用户的既有习惯，**REDCap 始终是主要的数据录入入口**。
|
||||
* **逻辑**：我们不应该重新发明一个录入界面，而是要在录入时通过 AI 进行“实时监护”。
|
||||
|
||||
## **2\. 详细场景划分**
|
||||
|
||||
| 场景 | 操作位置 | AI 的角色 | 理由 |
|
||||
| :---- | :---- | :---- | :---- |
|
||||
| **常规数据录入** | **REDCap 界面** | **实时监护** | 保持 CRC 习惯，降低迁移成本。AI 通过 Webhook 实时质控。 |
|
||||
| **大批量数据导入** | **AI Workbench** | **智能搬运** | 外部 Excel 或多张化验单。AI 清洗后，CRC 确认一次，一键注入。 |
|
||||
| **图像/PDF 提取录入** | **AI Workbench** | **OCR 提取** | REDCap 原生不支持复杂的 OCR 解析。在 Workbench 完成提取比对最顺手。 |
|
||||
| **质疑(Query)处理** | **AI Workbench** | **冲突展示** | 在 Workbench 可以同屏看“证据原文”和“建议值”，体验远好于 REDCap。 |
|
||||
| **项目初始化配置** | **AI Workbench** | **架构定义** | 复杂的 RAG 知识库上传、映射表配置，属于 AI 平台的特有逻辑。 |
|
||||
|
||||
## **3\. 典型流程对比**
|
||||
|
||||
### **流程 A：常规录入 (CRC 在 REDCap 操作)**
|
||||
|
||||
1. CRC 登录 REDCap，打开患者表单。
|
||||
2. 输入血红蛋白值：8.0（单位录错）。
|
||||
3. 点击保存 \-\> REDCap 写入 MySQL \-\> 触发 Webhook。
|
||||
4. 我们的后端感知后，QC Agent 发现逻辑错误。
|
||||
5. **反馈**：
|
||||
* **低延时提醒**：通过 EM 插件在 REDCap 页面上方显示：“AI 提示：该值偏离历史均值，请确认单位”。
|
||||
* **异步质疑**：在我们的 Workbench 生成一条 Pending Action。
|
||||
|
||||
### **流程 B：AI 增强录入 (CRC 在 Workbench 操作)**
|
||||
|
||||
1. CRC 收到一张化验单照片。
|
||||
2. CRC 登录我们的 Workbench，上传照片。
|
||||
3. AI 提取出 10 个指标。
|
||||
4. **预览比对**：界面左侧是照片，右侧是提取的表格，高亮显示不确定的值。
|
||||
5. **一键注入**：CRC 确认无误，点击“同步”。系统自动调用 REDCap API 将这 10 个值一次性填满 REDCap 表单。
|
||||
|
||||
## **4\. 结论与思路总结**
|
||||
|
||||
* **REDCap 登录**：用于\*\*“手动、少量、常规”\*\*的临床记录。
|
||||
* **AI Workbench 登录**：用于\*\*“大批量、文档提取、质控确认、方案解析”\*\*的高级任务。
|
||||
|
||||
这种设计的优势在于：**不强制改变用户习惯，但用 AI 让任务变得更轻松。** 我们不需要做一个完整的 EDC，我们要做的是 EDC 的“智能加速器”。
|
||||
|
||||
**您认可这个“双轨制”吗？** 特别是关于“大批量和文档提取才去 Workbench”的设定。
|
||||
@@ -0,0 +1,92 @@
|
||||
# **文档 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 专家 | **状态**：详细设计完成
|
||||
Reference in New Issue
Block a user