Files

HaHafeng 7a299e8562 feat(iit): Implement event-level QC architecture V3.1 with dynamic rule filtering, report deduplication and AI intent enhancement

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-02-08 21:22:11 +08:00

37 KiB

Raw Blame History

IIT Manager Agent模块 - 当前状态与开发指南

文档版本： v2.4
创建日期： 2026-01-01
维护者： IIT Manager开发团队
最后更新： 2026-02-08 🎉 事件级质控架构 V3.1 开发完成！
重大里程碑：

✅ 2026-02-08：事件级质控架构 V3.1 完成（record+event 独立质控 + 规则动态过滤 + 报告去重 + AI对话增强）

✅ 2026-02-08：质控驾驶舱 UI 开发完成（PromptBuilder XML 格式 + 驾驶舱页面 + 热力图 + 详情抽屉）

✅ 2026-02-08：质控系统优化计划制定（XML 临床切片格式 + 质控驾驶舱设计 + 方案 A 确认）

✅ 2026-02-07：实时质控系统开发完成（pg-boss防抖 + 质控日志 + 录入汇总 + 管理端批量操作）

✅ 2026-02-05：V2.9.1 完整开发计划发布（双脑架构 + 三层记忆 + 主动性增强 + 隐私合规）

✅ 2026-02-02：REDCap 生产环境部署完成（ECS + RDS + HTTPS）

✅ 2026-01-04：混合检索架构实现（REDCap实时数据 + Dify文档知识库）
文档目的： 反映模块真实状态，记录开发历程

📋 文档说明

本文档是IIT Manager Agent模块的真实状态快照，如实记录开发进度、关键配置和当前真实状况。

与其他文档的关系：

本文档（00-模块当前状态）：What is（真实状态，当前进度）
MVP开发任务清单：What to do（开发计划）
技术设计文档：How to do（技术方案）
开发记录文档：What done（历史记录）

🎯 模块概述

核心功能

IIT Manager Agent（研究者发起试验管理助手）是一个基于企业微信的主动式AI Agent产品，为IIT（研究者发起试验）提供智能化管理能力。

架构设计

核心理念：双脑架构（V2.9.1） - SOP 状态机 + ReAct 引擎 + 三层记忆 + 隐私合规
双脑路由：
- 左脑（SOP 引擎）：结构化任务执行，写操作必经
- 右脑（ReAct 引擎）：模糊查询，只读不写
技术栈：
- 后端：Node.js (Fastify) + PostgreSQL (Prisma) + pg-boss
- 前端：企业微信 + 微信小程序 (Taro 4.x)
- 数据源：REDCap (EDC系统)
- 通知：企业微信
- AI能力：DeepSeek/Qwen + 自研 RAG

当前状态

开发阶段：🎉 事件级质控架构 V3.1 开发完成！基本测试通过
整体完成度：
- 基础设施：95%（REDCap + 企业微信 + AI 对话 + 实时质控 + 驾驶舱 UI + 事件级质控）
- 架构设计：100%（V2.9.1 完整开发计划发布）
- 代码实现：60%（实时质控系统 + 驾驶舱 UI + 事件级质控 V3.1 已实现）

✅ 已完成功能（基础设施）

✅ 数据库Schema创建（iit_schema，9个表 = 原5个 + 新增4个质控表）
✅ Prisma Schema编写（扩展至 ~350 行类型定义）
✅ 企业微信应用注册和配置
✅ REDCap 生产环境部署完成（ECS + RDS + HTTPS）
✅ REDCap实时集成完成（DET + REST API）
✅ 企业微信推送服务完成（WechatService）
✅ 端到端测试通过（REDCap → Node.js → 企业微信）
✅ AI对话集成完成（ChatService + SessionMemory）

✅ 已完成功能（实时质控系统 - 2026-02-07）

✅ 质控数据库表（iit_qc_logs + iit_record_summary + iit_qc_project_stats + iit_field_metadata）
✅ pg-boss 防抖机制（WebhookController + singletonKey）
✅ Worker 双产出（质控日志 + 录入汇总，一次执行两个产出）
✅ HardRuleEngine 增强（按表单过滤规则）
✅ QcService 创建（质控查询服务，6 个核心方法）
✅ ChatService 优化（优先查询汇总表/质控表，新增录入/质控意图识别）
✅ 管理端批量操作（一键全量质控 + 一键全量汇总，前后端完整实现）

✅ 已完成功能（架构设计 V2.9.1）

✅ 双脑架构设计（SOP 状态机 + ReAct 引擎）
✅ 三层记忆系统设计（流水账 + 热记忆 + 历史书）
✅ 主动性增强设计（Cron Skill + 用户画像 + 反馈循环）
✅ 隐私合规设计（PII 脱敏中间件 + 审计日志）
✅ 自动化工具设计（AutoMapper REDCap Schema 对齐）
✅ 模块化开发文档（6 份专项文档）

✅ 已完成功能（质控驾驶舱 UI - 2026-02-08）

✅ PromptBuilder 类（XML 临床切片格式构建器，减少 LLM 幻觉）
✅ ChatService 优化（集成 PromptBuilder，使用 XML 格式化数据）
✅ 质控驾驶舱页面（IitQcCockpitPage.tsx，全屏展示模式）
✅ 统计卡片组件（QcStatCards.tsx，4 个核心指标）
✅ 风险热力图组件（RiskHeatmap.tsx，受试者×表单矩阵视图）
✅ 详情抽屉组件（QcDetailDrawer.tsx，含 LLM Trace 视图）
✅ 驾驶舱后端 API（iitQcCockpitService + Controller + Routes）
✅ 前端类型定义（qcCockpit.ts，完整的 TypeScript 类型）

✅ 已完成功能（事件级质控 V3.1 - 2026-02-08）

✅ 事件级质控架构（每个 record+event 独立质控，不再合并数据）
✅ 规则动态过滤（applicableEvents/applicableForms 配置规则适用范围）
✅ RedcapAdapter 增强（getAllRecordsByEvent + getFormEventMapping + getEvents）
✅ SkillRunner 重构（按 record+event 执行 + filterApplicableRules）
✅ 质控报告去重（按 recordId+ruleId 去重，避免多事件重复问题）
✅ 报告自动刷新（导出 XML 前自动获取最新数据）
✅ AI 意图识别增强（支持"严重违规有几项"等自然语言查询）
✅ Bug 修复（formatPatientData 500 错误 + 记录数统计 + 报告限制移除）

⏳ 待实施功能（按 Phase 规划）

Phase	内容	优先级	状态
Phase 1	基础工具层（ToolsService + HardRuleEngine + AutoMapper）	P0	✅ 部分完成（HardRuleEngine 已实现）
Phase 1.5	隐私安全（AnonymizerService + PII 脱敏）	P0 合规必需	待开始
Phase 2	实时质控系统（QC Worker + QcService + 批量操作）	P0	✅ 已完成
Phase 2.5	质控 UI 与 LLM 格式优化（驾驶舱 + XML 临床切片）	P0	📋 计划已制定
Phase 3	ReAct 引擎 + 流水账（ReActEngine + 反馈循环）	P0	待开始
Phase 4	调度系统（SchedulerService + Cron Skill + ProfilerService）	P1	待开始
Phase 5	智能路由（IntentService + 多意图处理）	P1	待开始
Phase 6	视觉能力（VisionService）	延后	待开始

📋 新增开发计划（2026-02-08）

质控系统 UI 与 LLM 格式优化计划
- 阶段 1：LLM 格式优化（PromptBuilder + XML 临床切片）~5.5h
- 阶段 2：管理端 UI 增强（质控驾驶舱 + 统计卡片 + 热力图）~9.5h
- 阶段 3：变量标签系统（按语义标签切片数据）~5h
部署状态：✅ REDCap 生产环境运行中（https://redcap.xunzhengyixue.com/）
已知问题：无
开发计划文档：V2.9.1 综合开发计划

📊 一、当前开发进度

MVP开发阶段（2周，10个工作日）

阶段	状态	完成时间	核心交付物
Day 1：环境初始化	✅ 已完成	2026-01-01	数据库Schema + 企业微信配置 + 模块骨架
REDCap环境准备	✅ 已完成	2026-01-02	REDCap Docker部署 + 对接方案确定
Day 2：REDCap拉取	✅ 已完成	2026-01-02	RedcapAdapter(271行) + WebhookController(327行) + SyncManager(398行)
Day 3：企微推送	✅ 已完成	2026-01-03	WechatService(314行) + WechatCallbackController(501行) + 质控Worker
Phase 1.5：AI对话	✅ 已完成	2026-01-03 & 2026-01-04	ChatService(485行) + SessionMemory(120行) + Dify集成
IIT 管理端配置	✅ 已完成	2026-02-07	运营管理端 IIT 项目管理（REDCap配置 + 质控规则 + 用户映射 + 知识库）
实时质控系统	✅ 已完成	2026-02-07	4个新表 + pg-boss防抖 + Worker双产出 + QcService + 管理端批量操作
Day 6-7：小程序	⏳ 待开始	-	Taro前端 + 审批界面
Day 8：回写+集成	⏳ 待开始	-	REDCap回写 + 端到端测试
Day 9-10：完善+测试	⏳ 待开始	-	错误处理 + 日志 + 性能优化

当前进度统计

整体完成度：50%（Day 1 + Day 2 + Day 3完成）

已完成任务：

✅ 数据库初始化（11/11测试通过）
✅ REDCap实时集成（DET + REST API）
✅ 企业微信推送服务（WechatService）
✅ 企业微信回调处理（WechatCallbackController）
✅ 企业微信URL验证（调试工具通过）
✅ 企业微信初始化（Access Token获取成功）
✅ 项目初始化（目录结构 + 类型定义）
✅ 企业微信网页授权及JS-SDK授权获取
✅ 可信域名配置（iit.xunzhengyixue.com）
✅ REDCap本地Docker环境部署（15.8.0）
✅ REDCap对接技术调研（源码分析 + 官方文档研究）
✅ REDCap对接方案确定（DET + REST API架构）
✅ REDCap测试项目创建（test0102, PID 16，已有数据）
✅ REDCap对接技术方案文档编写（1070行完整实施指南）
✅ RedcapAdapter开发完成（271行，7个API方法，测试通过）
✅ WebhookController开发完成（327行，<10ms响应，支持form-urlencoded）
✅ SyncManager开发完成（398行，增量+全量+手动同步）
✅ Worker注册完成（iit_quality_check + iit_redcap_poll）
✅ 路由配置完成（5个API端点）
✅ 集成测试通过（12/12测试用例全部通过）
✅ 真实场景验证（新增+编辑记录，DET实时触发，数据一致性验证）

Day 3已完成（2026-01-03）：

✅ 企业微信推送服务（WechatService, 314行）
✅ 企业微信回调处理（WechatCallbackController, 501行）
✅ 质控Worker完善（质控逻辑 + 通知推送 + 审计日志）
✅ Worker注册修复（initIitManager() 调用）
✅ 数据库字段修复（action_type）
✅ 端到端测试通过（<2秒延迟，100%成功率）
✅ 🎯 MVP闭环完全打通（REDCap → Node.js → 企业微信）

下一步任务：

⏳ Phase 1.5：AI质控能力（Dify RAG + 规则引擎）
⏳ Phase 2：多项目支持（notification_config 字段）
⏳ Phase 2：定时轮询实现（兜底机制）

待完成任务：

⏳ 数据质量Agent开发（AI质控）
⏳ 企业微信对话功能（用户消息处理）
⏳ 影子状态管理
⏳ 微信小程序前端
⏳ REDCap双向回写

🗄️ 二、数据库Schema

2.1 Schema信息

Schema名称：iit_schema
数据库：ai_clinical_research（RDS PostgreSQL 15）
创建时间：2025-12-31
表数量：5个
验证状态：✅ 已创建并验证

2.2 表结构

表名	用途	主要字段	索引
IitProject	项目配置	id, redcapApiUrl, redcapApiToken, difyAgentUrl	redcapProjectId
IitPendingAction	影子状态（待审核动作）	id, projectId, actionType, status	projectId, status
IitTaskRun	任务运行记录	id, projectId, taskType, status	projectId, status
IitUserMapping	跨系统用户映射	id, projectId, redcapUsername, wechatUserId	redcapUsername, wechatUserId
IitAuditLog	审计日志	id, projectId, actionType, operator	projectId, createdAt

2.3 Prisma Schema位置

AIclinicalresearch/backend/prisma/schema.prisma

IIT Manager Schema定义（位于文件末尾）：

完整的5个表模型定义
外键关系配置
索引优化
JSON字段支持

🔧 三、技术架构

3.1 后端技术栈

核心框架：

Node.js：v22.x
Web框架：Fastify
ORM：Prisma 6.17.0（多Schema支持）
任务队列：pg-boss（Postgres-Only架构）
AI能力：Dify RAG（RESTful API）

模块结构：

backend/src/modules/iit-manager/
├── index.ts                  ✅ 主入口（模块注册）
├── types/
│   └── index.ts             ✅ 类型定义（223行）
├── routes/
│   └── index.ts             ✅ 路由骨架
├── controllers/             ⏳ 待开发
├── services/                ⏳ 待开发
├── agents/                  ⏳ 待开发
└── adapters/                ⏳ 待开发

3.2 前端技术栈

微信小程序：

框架：Taro 4.x（React语法）
UI组件：Taro UI / WeUI
状态管理：React Hooks
开发状态：⏳ 未开始

3.3 企业微信集成

应用信息：

应用名称：IIT Manager Agent
CorpID：ww01cb7b72ea2db83c
AgentID：1000002
Secret：F3XqlAqKdcOKHi9pLGv5a2dSUowWbevdcDRrBk2pXLM

授权配置：

✅ 网页授权及JS-SDK授权：已获取
✅ 可信域名：iit.xunzhengyixue.com
✅ 域名验证文件：已部署（前端v1.2）

消息推送能力：

✅ Access Token获取：测试通过
⏳ 文本消息推送：待开发
⏳ 卡片消息推送：待开发
⏳ 消息模板：待设计

环境变量配置（Node.js后端SAE）：

WECHAT_CORP_ID=ww6ab493470ab4f377
WECHAT_AGENT_ID=1000002
WECHAT_CORP_SECRET=AZIVxMtoLb0rEszXS81e4dBRl-I9kgTjygIS0cFfENU
WECHAT_TOKEN=oXlRBm1YnvMy2SbDLbvAdDd5Gq3oBGq
WECHAT_ENCODING_AES_KEY=v88eT3O9bMW897h4btr7v7qvQImlMf31edTQCmuhOhO

🚀 四、关键里程碑

2026-01-02：REDCap环境就绪 - 对接方案确定 ✅

完成内容：

REDCap本地环境部署：
- ✅ Docker Compose配置（3容器架构）
- ✅ REDCap 15.8.0部署成功
- ✅ 解决部署问题（ERR_CONTENT_DECODING_FAILED、CRLF污染等）
- ✅ Admin账户登录成功
- ✅ 测试项目创建（test0102, PID 16）
- ✅ 测试数据录入成功
REDCap技术调研：
- ✅ 源码分析（redcap15.8.0/）
- ✅ External Module文档研究（redcap_external_module_framework_docs_main/）
- ✅ 验证DET功能真实存在（Classes/DataEntry.php）
- ✅ 确认REST API可用性
对接方案确定：
- ✅ 技术选型：DET + REST API（不使用External Module）
- ✅ 架构设计：实时触发（DET） + 轮询补充（每30分钟）
- ✅ 实时性保证：0秒延迟触发 + 5秒内完成质控
- ✅ 可靠性保证：Webhook幂等性 + 轮询补充机制
技术方案文档编写：
- ✅ 创建《REDCap对接技术方案与实施指南》（1070行）
- ✅ 完整代码设计（RedcapAdapter、WebhookController、SyncManager）
- ✅ 详细实施步骤（Day 2清单）
- ✅ 测试验证方案
REDCap文档体系建立：
- ✅ 创建REDCap模块文档结构
- ✅ 编写《REDCap Docker部署操作手册》
- ✅ 编写《部署问题排查手册》
- ✅ 整理参考资料和最佳实践

关键成果：

🎉 REDCap本地环境运行稳定
🎉 DET功能验证成功（REDCap原生支持）
🎉 对接方案技术可行性100%确认
🎉 完整实施指南已编写（可直接开发）

技术亮点：

DET实时触发：0秒延迟，满足实时质控需求
双保险机制：Webhook + 轮询，确保数据不丢失
零侵入性：无需修改REDCap源码，只用原生API
生产级架构：开发环境与生产环境配置一致

验收标准：

✅ REDCap可通过浏览器访问
✅ Admin账户登录成功
✅ 测试项目可正常使用
✅ DET功能在源码中确认存在
✅ REST API端点可访问
✅ 技术方案文档完整
✅ 代码设计可直接实现

2026-01-01：Day 1完成 - 环境初始化 ✅

完成内容：

数据库初始化：
- ✅ 创建 iit_schema
- ✅ 编写 Prisma Schema（5个表）
- ✅ 同步数据库（npx prisma db push）
- ✅ 生成 Prisma Client
- ✅ 验证CRUD操作（11/11测试通过）
企业微信初始化：
- ✅ 注册企业微信开发者账号
- ✅ 创建自建应用
- ✅ 获取并配置凭证（CorpID、AgentID、Secret）
- ✅ 测试Access Token获取成功
- ✅ 获取网页授权及JS-SDK授权
- ✅ 配置可信域名（iit.xunzhengyixue.com）
项目初始化：
- ✅ 创建模块目录结构
- ✅ 配置路由前缀（/api/v1/iit）
- ✅ 创建基础类型定义（223行）
前端部署：
- ✅ 前端v1.2部署成功
- ✅ 企业微信域名验证文件部署
- ✅ 解决Windows换行符问题（CRLF→LF）

关键成果：

🎉 IIT Manager Agent模块正式启动
🎉 企业微信集成基础完成
🎉 网页授权及JS-SDK授权已获取
🎉 可信域名配置成功

验收标准：

✅ 5个表全部创建成功
✅ Prisma Client可正常导入
✅ 测试脚本能执行CRUD
✅ 企微账号注册成功
✅ 能成功获取Access Token
✅ 目录结构完整
✅ 类型定义完整

📁 五、代码文件清单

5.1 后端代码

Prisma Schema：

backend/prisma/schema.prisma
- IIT Manager Schema（5个表定义）
- 位于文件末尾
- 包含外键关系和索引

模块代码：

backend/src/modules/iit-manager/
├── index.ts                     ✅ 82行（模块注册）
├── types/index.ts               ✅ 223行（类型定义）
├── routes/index.ts              ✅ 23行（路由骨架）
├── test-iit-database.ts         ✅ 111行（数据库测试）
└── test-wechat-push.ts          ✅ 138行（企微测试）

代码统计：

已完成代码：577行
测试脚本：249行
总计：826行

5.2 前端代码

域名验证文件：

frontend-v2/public/WW_verify_YnhsQBwI0ARnNoG0.txt
- 企业微信域名验证文件
- 已部署到SAE（前端v1.2）

微信小程序：

⏳ 未开始

🔑 六、关键配置信息

6.1 企业微信配置

应用凭证：

CorpID：ww6ab493470ab4f377
AgentID：1000002
Secret：AZIVxMtoLb0rEszXS81e4dBRl-I9kgTjygIS0cFfENU
应用名称：IIT Manager Agent

回调配置（已验证）：

Token：oXlRBm1YnvMy2SbDLbvAdDd5Gq3oBGq
EncodingAESKey：v88eT3O9bMW897h4btr7v7qvQImlMf31edTQCmuhOhO
回调URL：https://iit.nat100.top/api/v1/iit/wechat/callback（调试工具验证通过 ✅）

授权配置：

网页授权域名：iit.xunzhengyixue.com
JS-SDK安全域名：iit.xunzhengyixue.com
验证文件：WW_verify_YnhsQBwI0ARnNoG0.txt
验证文件内容：YnhsQBwI0ARnNoG0

API端点：

获取Access Token：https://qyapi.weixin.qq.com/cgi-bin/gettoken
发送消息：https://qyapi.weixin.qq.com/cgi-bin/message/send

6.2 REDCap配置

本地开发环境：

REDCap版本：15.8.0
访问地址：http://localhost:8080
Admin账户：Admin / Xilu,881009
部署方式：Docker Compose（3容器：Apache+PHP+REDCap、MySQL、phpMyAdmin）
Docker项目路径：AIclinicalresearch/redcap-docker-dev/
部署状态：✅ 运行中

测试项目信息：

项目名称：test0102
Project ID (PID)：16
项目状态：已创建，已录入测试数据
API Token：待生成（Day 2第一步）

REDCap对接方案：

技术方案：Data Entry Trigger (DET) + REST API
实时触发：DET Webhook → Node.js接收器 → 异步处理
数据拉取：REST API exportRecords（支持增量同步）
数据回写：REST API importRecords（Phase 2）
轮询补充：pg-boss定时任务（每30分钟，防止DET遗漏）
方案文档：docs/03-业务模块/IIT Manager Agent/04-开发计划/REDCap对接技术方案与实施指南.md

DET配置（待执行）：

Control Center启用：待启用
Webhook URL：http://localhost:3001/api/v1/iit/webhooks/redcap（开发环境）
生产URL：https://iit.xunzhengyixue.com/api/v1/iit/webhooks/redcap

6.3 数据库配置

数据库连接：

postgresql://airesearch:Xibahe%40fengzhibo117@pgm-2zex1m2y3r23hdn5.pg.rds.aliyuncs.com:5432/ai_clinical_research

Schema：iit_schema

📝 七、测试脚本

7.1 数据库测试

文件位置：backend/src/modules/iit-manager/test-iit-database.ts

测试内容：

✅ IitProject CRUD操作
✅ IitPendingAction CRUD操作
✅ IitTaskRun CRUD操作
✅ IitUserMapping CRUD操作
✅ IitAuditLog CRUD操作

运行方式：

cd backend
npx ts-node src/modules/iit-manager/test-iit-database.ts

测试结果：✅ 11/11测试通过

7.2 企业微信测试

文件位置：backend/src/modules/iit-manager/test-wechat-push.ts

测试内容：

✅ Access Token获取
⏳ 文本消息发送（待测试）
⏳ 卡片消息发送（待测试）

运行方式：

cd backend
npx ts-node src/modules/iit-manager/test-wechat-push.ts

测试结果：✅ Access Token获取成功

🎯 八、下一步工作（Day 2）

8.1 Day 2总体目标

核心目标：实现REDCap数据的实时拉取能力

交付物：

✅ REDCap API Adapter（RedcapAdapter.ts）
✅ Webhook接收器（WebhookController.ts）
✅ 数据同步管理（SyncManager.ts）
✅ 完整测试（单元测试 + 集成测试）

预计工作量：6-8小时（完整工作日）

8.2 阶段1：环境准备（30分钟）

REDCap配置：

在Control Center启用DET功能
在test0102项目生成API Token

配置环境变量：

REDCAP_BASE_URL=http://localhost:8080
REDCAP_API_TOKEN_TEST=YOUR_TOKEN_HERE

使用curl测试API是否可用

测试工具准备：

安装ngrok（用于DET测试）
准备Postman Collection（API调试）
准备测试数据（在REDCap中录入几条记录）

8.3 阶段2：RedcapAdapter开发（1.5小时）

文件位置：backend/src/modules/iit-manager/adapters/RedcapAdapter.ts

任务清单：

创建RedcapAdapter类
实现 exportRecords() 方法（支持增量同步）
实现 exportMetadata() 方法（获取字段定义）
实现 importRecords() 方法（Phase 2使用）
实现 formatRedcapDate() 工具方法
配置axios超时和重试
编写单元测试：RedcapAdapter.test.ts

验收标准：

✅ 可以拉取test0102的所有记录
✅ 可以拉取指定record_id的记录
✅ 可以使用dateRangeBegin增量拉取
✅ 可以获取元数据（字段定义）
✅ 单元测试全部通过

8.4 阶段3：WebhookController开发（2小时）

文件位置：backend/src/modules/iit-manager/controllers/webhookController.ts

任务清单：

创建WebhookController类
实现 handleRedcapWebhook() 方法（响应时间<100ms）
实现 processWebhook() 异步处理方法
实现 checkDuplicate() 幂等性检查
配置路由：POST /api/v1/iit/webhooks/redcap
记录审计日志
推送到质控队列（iit:quality-check）

验收标准：

✅ Webhook可以接收POST请求
✅ 立即返回200 OK（<100ms）
✅ 异步处理不阻塞响应
✅ 5分钟内相同记录不重复处理
✅ 成功调用RedcapAdapter拉取数据
✅ 数据推送到pg-boss队列

8.5 阶段4：SyncManager开发（1.5小时）

文件位置：backend/src/modules/iit-manager/services/SyncManager.ts

任务清单：

创建SyncManager类
实现 initializeSync() 方法（注册定时任务）
实现 handlePoll() 方法（轮询逻辑）
实现 stopSync() 方法（停止同步）
注册pg-boss Worker：iit:redcap:poll
增量拉取逻辑（使用lastSyncAt）
更新项目lastSyncAt字段

验收标准：

✅ 可以手动触发一次轮询
✅ 定时任务可以自动执行（每30分钟）
✅ 增量拉取正确（只拉取新数据）
✅ lastSyncAt正确更新
✅ 数据推送到质控队列

8.6 阶段5：集成测试（1小时）

测试内容：

DET配置验证：
- 在REDCap中配置DET URL
- 使用ngrok测试Webhook
- 验证Payload格式
API测试：
- 运行 test-redcap-api.ts
- 验证exportRecords正常
- 验证exportMetadata正常
端到端测试：
- 在REDCap保存一条记录
- 验证Webhook被触发
- 验证数据被拉取
- 验证数据推送到队列
- 验证审计日志记录
轮询测试：
- 手动触发轮询
- 验证增量拉取
- 验证lastSyncAt更新

验收标准：

✅ DET实时触发正常
✅ API拉取数据正常
✅ 轮询补充机制正常
✅ 端到端流程畅通
✅ 所有测试通过

8.7 阶段6：文档更新（30分钟）

更新内容：

更新MVP开发任务清单（Day 2标记为完成）
记录API Token和配置信息
更新模块当前状态文档
更新架构图
提交Git（遵循Git提交规范）

8.8 关键注意事项

性能要求：

⚠️ Webhook响应时间必须<100ms
⚠️ 使用setImmediate()异步处理，不阻塞响应

安全要求：

⚠️ API Token存储在环境变量
⚠️ 不要在日志中打印完整Token
⚠️ 不要提交Token到Git

可靠性要求：

⚠️ 实现幂等性检查（防止重复处理）
⚠️ 实现轮询补充（防止DET遗漏）
⚠️ 记录详细日志（便于排查问题）

技术参考：

📚 九、相关文档索引

9.1 技术设计文档

IIT Manager Agent 完整技术开发方案 (V1.1) - 完整技术方案
IIT Manager Agent 技术架构白皮书 - 架构设计
IIT Manager Agent V4 完整产品需求文档 - 产品需求
EDC 适配器 (REDCap) 技术详细设计 (V1.0) - REDCap适配器设计

9.2 开发计划文档

MVP开发任务清单 - 详细任务清单
企业微信注册指南 - 企业微信配置
⭐ REDCap对接技术方案与实施指南 - REDCap集成完整方案（Day 2核心参考）

9.3 REDCap相关文档

REDCap模块文档导航 - REDCap文档总览
REDCap Docker部署操作手册 - Docker部署指南
REDCap二次开发深度指南 - 二次开发参考
部署问题排查手册 - 常见问题解决

9.4 开发记录文档

V1.1更新完成报告 - 技术方案更新记录

🔄 十、更新日志

2026-01-04：Dify知识库集成完成 - 混合检索实现 ✅

完成内容：

✅ Dify知识库创建（Dify_test0102，2个文档已处理）
✅ 项目关联配置（test0102 → Dataset ID: b49595b2-bf71-4e47-9988-4aa2816d3c6f）
✅ 意图识别扩展（新增query_protocol意图，扩充医学关键词）
✅ Dify查询集成（queryDifyKnowledge方法，Top 5语义检索）
✅ 混合检索实现（同时支持REDCap数据 + Dify文档）
✅ 智能路由（根据意图自动选择数据源）
✅ Bug修复（Dify API字段路径错误：record.segment.document.name）
✅ 调试工具开发（debug-dify-injection.ts、inspect-dify-response.ts）
✅ 端到端测试（5个场景全部通过）
✅ 开发记录文档（600+行完整记录）

关键成果：

🎉 混合检索架构实现（结构化数据 + 非结构化文档）
🎉 AI回答完全基于真实数据/文档（防止幻觉）
🎉 智能路由机制（根据问题自动选择数据源）
🎉 完整排查流程记录（从问题发现到根因修复）

技术亮点：

单项目单知识库架构（MVP快速落地方案）
语义检索（Dify semantic_search, Top 5）
数据注入LLM（格式化文档片段注入System Prompt）
完整调试链路（从意图识别 → Dify调用 → LLM注入）
关键Bug快速定位（通过调试脚本发现字段路径错误）

测试验证：

测试场景	用户问题	数据源	结果	响应时间
文档查询	"这个研究的排除标准是什么？"	Dify	✅ 准确	~5s
CRF查询	"CRF表格中有哪些观察指标？"	Dify	✅ 准确	~5s
患者查询	"ID 7的患者情况"	REDCap	✅ 准确	~5s
统计查询	"目前入组了多少人？"	REDCap	✅ 准确 (11人)	~4s
混合查询	"这个研究的主要研究目的是什么？"	Dify	✅ 准确	~5s

问题排查记录：

问题：AI编造答案，不查询Dify
- 根因1：意图识别关键词不全（缺"入选"、"诊断标准"等）
- 解决：扩充关键词正则表达式
- 根因2：Dify API字段路径错误（record.document_name → record.segment.document.name）
- 解决：修正字段访问路径
调试工具：
- debug-dify-injection.ts：追踪Dify结果是否正确注入LLM
- inspect-dify-response.ts：查看Dify API实际返回结构

技术债务：

⚠️ Dify文档通过Web界面手动上传（Phase 2开发API自动上传）
⚠️ 单项目单知识库（Phase 2支持多知识库）
⚠️ 检索参数固定（top_k=5，Phase 2支持动态调优）

参考文档：

下一步：

🔄 Phase 2：多项目支持、文档API上传、Function Calling

2026-01-03：Day 3完成 - 企业微信集成 + Phase 1.5 AI对话 ✅

完成内容：

✅ WechatService开发（314行，消息推送服务）
✅ WechatCallbackController开发（501行，回调处理 + 对话集成）
✅ 质控Worker完善（336行，质控逻辑 + 企微推送 + 审计日志）
✅ Worker注册修复（initIitManager调用）
✅ 数据库字段修复（action_type）
✅ 端到端测试通过（REDCap → Node.js → 企微，<2秒）
✅ Phase 1.5: ChatService开发（390行，AI对话服务）
✅ SessionMemory开发（170行，上下文记忆）
✅ REDCap数据查询集成（queryRedcapRecord, countRedcapRecords）
✅ 意图识别实现（关键词匹配）
✅ LLM集成（DeepSeek-V3, LLMFactory复用）
✅ 防止幻觉（数据注入LLM，基于真实数据回答）

关键成果：

🎉 MVP闭环完全打通（REDCap → Node.js → 企微 → AI对话）
🎉 AI基于REDCap真实数据对话（解决LLM幻觉问题）
🎉 上下文记忆实现（最近3轮对话）
🎉 端到端延迟<2秒（超出预期）

技术亮点：

异步Worker架构（符合Postgres-Only最佳范式）
企业微信消息加解密（完整实现签名验证和加解密）
异步回复模式（setImmediate 确保5秒内响应）
复用LLMFactory（零配置使用DeepSeek-V3）
SessionMemory内存存储（无需Redis，快速实现）

参考文档：

2026-01-02：REDCap环境就绪 + 对接方案确定 ✅

完成内容：

✅ REDCap本地Docker环境部署成功（15.8.0，3容器架构）
✅ REDCap部署问题排查（ERR_CONTENT_DECODING_FAILED、CRLF污染等）
✅ REDCap管理员登录成功（Admin账户验证通过）
✅ 测试项目创建（test0102, PID 16，已录入测试数据）
✅ REDCap源码分析（验证DET功能真实存在）
✅ External Module文档研究（确认不适用于外部系统集成）
✅ 对接方案技术选型：DET（实时触发） + REST API（数据读写）
✅ 架构设计完成：实时触发 + 轮询补充（双保险机制）
✅ 《REDCap对接技术方案与实施指南》编写（1070行完整文档）
✅ RedcapAdapter代码设计（exportRecords、exportMetadata、importRecords）
✅ WebhookController代码设计（<100ms响应、异步处理、幂等性检查）
✅ SyncManager代码设计（定时轮询、增量同步）
✅ REDCap文档体系建立（部署手册、问题排查、API对接等）

关键成果：

🎉 REDCap本地环境稳定运行（可随时用于开发测试）
🎉 DET功能验证成功（REDCap原生支持，无需PHP开发）
🎉 对接方案100%技术可行（实时性+可靠性双保证）
🎉 完整实施指南已编写（可直接进入Day 2开发）
🎉 REDCap文档体系完整（部署、对接、排查全覆盖）

技术亮点：

DET实时触发：0秒延迟，CRC保存数据后5秒内完成质控
双保险机制：Webhook（主） + 定时轮询（补充），数据不丢失
零侵入性：只使用REDCap原生API和DET，无需修改源码
生产级架构：Docker配置可直接用于ECS/医院环境部署
完整文档：从部署到开发，全流程文档化

技术决策：

❌ 不使用External Module（需要PHP开发、侵入性强、维护成本高）
✅ 使用DET + REST API（REDCap原生功能、零代码配置、实时触发）
✅ 实时触发 + 轮询补充（实时性99% + 可靠性100%）

部署记录：

REDCap版本：15.8.0
访问地址：http://localhost:8080
Docker容器：redcap-apache、redcap-mysql、redcap-phpmyadmin
测试项目：test0102 (PID 16)
部署时长：约6小时（含问题排查）

下一步：

🔄 Day 2：REDCap API集成开发（RedcapAdapter + WebhookController + SyncManager）
⏳ 在Control Center启用DET
⏳ 生成API Token
⏳ 实施《REDCap对接技术方案与实施指南》中的Day 2计划

2026-01-01：Day 1完成 - 环境初始化 ✅

完成内容：

✅ 数据库Schema创建（iit_schema，5个表）
✅ Prisma Schema编写（223行类型定义）
✅ 数据库CRUD验证（11/11测试通过）
✅ 企业微信应用注册和配置
✅ 企业微信Access Token获取成功
✅ 企业微信网页授权及JS-SDK授权获取
✅ 可信域名配置成功（iit.xunzhengyixue.com）
✅ 前端域名验证文件部署（v1.2）
✅ 模块目录结构创建
✅ 路由骨架搭建

关键成果：

🎉 IIT Manager Agent模块正式启动
🎉 企业微信集成基础完成
🎉 网页授权及JS-SDK授权已获取
🎉 为微信小程序开发铺平道路

技术要点：

Prisma Multi-Schema支持：成功配置iit_schema
企业微信API测试：Access Token获取验证通过
域名验证：解决Windows换行符问题（CRLF→LF）
前端部署：SAE部署成功，内网地址：172.17.173.80

下一步：

Day 2：REDCap API Adapter + SyncManager开发

2025-12-31：项目启动

项目背景：

基于REDCap的IIT（研究者发起试验）管理需求
使用企业微信作为移动端入口
采用Shadow State（影子状态）确保医疗合规性
利用Dify RAG提供智能知识服务

技术选型确认：

后端：Node.js + Fastify + Prisma + pg-boss
前端：微信小程序（Taro 4.x）
数据源：REDCap API
通知：企业微信
AI：Dify RAG

提示：本文档反映IIT Manager Agent模块的最新真实状态，每个里程碑完成后必须更新！
最后更新：2026-02-08 22:00
当前进度：事件级质控 V3.1 完成（60%）| 下一步：Phase 3 ReAct 引擎 + 流水账
重要文档：

事件级质控开发记录 ⭐⭐⭐⭐⭐

实时质控系统开发记录 ⭐⭐⭐⭐⭐

REDCap对接技术方案与实施指南 ⭐⭐⭐⭐⭐

37 KiB Raw Blame History Unescape Escape

IIT Manager Agent模块 - 当前状态与开发指南

📋 文档说明

🎯 模块概述

核心功能

架构设计

当前状态

✅ 已完成功能（基础设施）

✅ 已完成功能（实时质控系统 - 2026-02-07）

✅ 已完成功能（架构设计 V2.9.1）

✅ 已完成功能（质控驾驶舱 UI - 2026-02-08）

✅ 已完成功能（事件级质控 V3.1 - 2026-02-08）

⏳ 待实施功能（按 Phase 规划）

📋 新增开发计划（2026-02-08）

📊 一、当前开发进度

MVP开发阶段（2周，10个工作日）

当前进度统计

🗄️ 二、数据库Schema

2.1 Schema信息

2.2 表结构

2.3 Prisma Schema位置

🔧 三、技术架构

3.1 后端技术栈

3.2 前端技术栈

3.3 企业微信集成

🚀 四、关键里程碑

2026-01-02：REDCap环境就绪 - 对接方案确定 ✅

2026-01-01：Day 1完成 - 环境初始化 ✅

📁 五、代码文件清单

5.1 后端代码

5.2 前端代码

🔑 六、关键配置信息

6.1 企业微信配置

6.2 REDCap配置

6.3 数据库配置

📝 七、测试脚本

7.1 数据库测试

7.2 企业微信测试

🎯 八、下一步工作（Day 2）

8.1 Day 2总体目标

8.2 阶段1：环境准备（30分钟）

8.3 阶段2：RedcapAdapter开发（1.5小时）

8.4 阶段3：WebhookController开发（2小时）

8.5 阶段4：SyncManager开发（1.5小时）

8.6 阶段5：集成测试（1小时）

8.7 阶段6：文档更新（30分钟）

8.8 关键注意事项

📚 九、相关文档索引

9.1 技术设计文档

9.2 开发计划文档

9.3 REDCap相关文档

9.4 开发记录文档

🔄 十、更新日志

2026-01-04：Dify知识库集成完成 - 混合检索实现 ✅

2026-01-03：Day 3完成 - 企业微信集成 + Phase 1.5 AI对话 ✅

2026-01-02：REDCap环境就绪 + 对接方案确定 ✅

2026-01-01：Day 1完成 - 环境初始化 ✅

2025-12-31：项目启动

37 KiB

Raw Blame History