Files

HaHafeng 9b8490b4d0 docs(iit): Update module status with frontend architecture changes

Changes:
- Add frontend architecture adjustment milestone (admin/business side split)
- Document product positioning: ops team configures, end users use QC platform
- Add new completed feature section for routing/navigation changes
- Update current status to reflect Web AI Chat and admin IIT project management

Made-with: Cursor

2026-02-26 22:12:49 +08:00

40 KiB

Raw Blame History

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

文档版本： v3.0
创建日期： 2026-01-01
维护者： IIT Manager开发团队
最后更新： 2026-02-26 前端架构调整 + Web Chat 上线
重大里程碑：

2026-02-26：前端架构调整完成！ 运营管理端恢复 IIT 项目管理 + 业务端精简为日常使用 + Web AI 对话页面上线

2026-02-26：CRA Agent V3.0 P0+P1 全部完成！ 自驱动质控流水线 + ChatOrchestrator + LLM Function Calling + E2E 54/54 通过

2026-02-25：CRA Agent V3.0 开发计划定稿（替代 CRA 定位 + 报告驱动架构 + 4 语义化工具 + 统一驾驶舱）

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

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

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

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

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

CRA Agent V3.0 开发计划

统一数字 CRA 质控平台 PRD

UI 原型

📋 文档说明

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

与其他文档的关系：

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

🎯 模块概述

核心定位（V3.0 更新）

CRA Agent 是一个替代 CRA 岗位的自主 AI Agent，而非辅助 CRA 的工具。目标是用 AI 替代临床监查员 70-80% 的工作量，让 IIT 项目在无专职 CRA 的情况下也能达到合规的质控水平。主要用户为 PI（主要研究者）/ 研究团队。

架构设计（V3.0）

核心理念：报告驱动 + LLM Tool Use + 统一驾驶舱
两层架构：
- 自驱动层：定时质控 → 生成报告 → 派发 eQuery → 推送告警（Agent 自主"上班"）
- 对话层：ChatOrchestrator + LLM 原生 Function Calling + 4 个语义化工具
4 语义化工具：look_up_data / check_quality / read_report / search_knowledge
已废弃（V2.9.1）：双脑架构、三层记忆系统、手写 ReAct 引擎、关键词意图路由
技术栈：
- 后端：Node.js (Fastify) + PostgreSQL (Prisma) + pg-boss
- 前端：管理端（React + Ant Design） + 企业微信推送
- 数据源：REDCap (EDC系统)
- 通知：企业微信
- AI能力：DeepSeek/Qwen + 自研 RAG（pgvector）+ LLM Tool Use

当前状态

开发阶段：V3.0 P0 + P1 已完成，E2E 测试 54/54 通过
P0 已完成（自驱动质控流水线）：
- 变量清单导入 + 可视化
- 规则配置增强（4 类规则 + AI 辅助建议）
- 定时质控 + 报告生成 + eQuery 闭环 + 重大事件归档
- 统一质控驾驶舱（健康分 + 趋势图 + 风险热力图）+ AI Stream Timeline
P1 已完成（对话层 Tool Use 改造）：
- LLM Adapter 原生 Function Calling（DeepSeek / GPT-5 / Claude-4.5）
- 4 语义化工具：read_report / look_up_data / check_quality / search_knowledge
- ChatOrchestrator 轻量 ReAct（max 3 轮 Function Calling loop）
- ChatService (1,442行) 已废弃，替换为 ChatOrchestrator (~160行)
前端架构调整已完成（2026-02-26）：
- 运营管理端：恢复 IIT 项目管理（项目列表 + 配置 + 驾驶舱），供运营团队使用
- 业务端 CRA 质控：精简为 5 个日常页面（驾驶舱 / 报告 / AI 工作流水 / AI 对话 / eQuery），供 PI/CRC 使用
- 新增 Web AI 对话页面（/iit/chat）+ 后端 POST /api/v1/iit/chat 端点
产品定位明确：运营团队配置项目（白手套服务） → 终端用户使用质控平台
待开发：P1-2 对话体验优化 / P2 可选功能
代码规模：后端 ~14,000+ 行（净减 ~1,100 行）/ 20 张表（iit_schema）

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

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

✅ 已完成功能（P0 自驱动质控流水线 - 2026-02-26）

✅ 变量清单导入（REDCap Data Dictionary → iit_field_metadata）
✅ 规则配置增强（4 类规则 + AI 辅助建议 + 变量关联）
✅ 定时质控调度（pg-boss cron + DailyQcOrchestrator）
✅ eQuery 闭环（open → responded → ai_reviewing → resolved/reopened）
✅ 重大事件归档（SAE + 方案偏离自动归档 iit_critical_events）
✅ 统一驾驶舱（健康分 + 趋势图 + 风险热力图 + 核心指标卡片）
✅ AI Stream Timeline（Agent 工作时间线可视化）
✅ P0 E2E 测试 46/46 通过

✅ 已完成功能（P1 对话层 Tool Use 改造 - 2026-02-26）

✅ LLM Adapter Function Calling（types.ts + DeepSeekAdapter + CloseAIAdapter）
✅ 4 语义化工具（read_report / look_up_data / check_quality / search_knowledge）
✅ ChatOrchestrator（轻量 ReAct，max 3 轮 Function Calling loop，~160 行）
✅ ChatService 废弃（1,442 行 → ChatService.deprecated.ts）
✅ WechatCallbackController 接线（入口切换为 ChatOrchestrator）
✅ P1 E2E 测试 8/8 通过（8 个真实对话场景 + DeepSeek API）

✅ 已完成功能（前端架构调整 - 2026-02-26）

✅ 运营管理端 IIT 项目管理恢复（App.tsx 路由接线 + AdminLayout 侧边栏菜单）
✅ 业务端精简为日常使用（去掉项目设置/变量清单入口，只保留 5 个页面）
✅ Web AI 对话页面（AiChatPage.tsx + POST /api/v1/iit/chat 后端端点）
✅ 产品分层明确：
- 运营管理端（/admin/iit-projects）→ 运营团队：创建项目、配置 REDCap、设规则
- 业务端（/iit/）→ PI/CRC：驾驶舱、报告、AI 工作流水、AI 对话、eQuery

✅ 已完成功能（实时质控系统 - 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 错误 + 记录数统计 + 报告限制移除）

⏳ V3.0 开发计划（2026-02-25 定稿）

详见：CRA Agent V3.0 开发计划

阶段	内容	预估	状态
P0-1	ChatOrchestrator + ToolsService 重构（4 语义化工具 + LLM Tool Use）	2 天	待开始
P0-2	report 工具补全（read_report + search_knowledge 实现）	1.5 天	待开始
P0-3	定时质控 + 报告生成 + eQuery 闭环（pg-boss cron + 全量/增量报告 + eQuery 状态机）	3.5 天	待开始
P0-4	统一质控驾驶舱（概览 + AI Stream + eQuery 管理 + 报告归档 + 重大事件库）	2.5 天	待开始
P1-1	企业微信主动推送（日报/告警/eQuery 通知）	2 天	待开始
P1-2	管理端配置增强（规则模板 + 多项目切换）	2 天	待开始
P2	长期可选（PII 脱敏 / SDV 视觉核对 / AutoMapper / 数据响应质量评级）	-	待开始

P0 合计：约 9.5 天 / P0+P1 合计：约 13.5 天（1 人）

部署状态：✅ REDCap 生产环境运行中（https://redcap.xunzhengyixue.com/）
已知问题：ChatService (1442行) 为"上帝类"，关键词路由需重构为 LLM Tool Use
开发计划文档：CRA Agent V3.0 开发计划
历史计划文档：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 → 企业微信）

下一步任务（V3.0）：

⏳ P0-1：ChatOrchestrator + ToolsService 重构（LLM Tool Use + 4 语义化工具）
⏳ P0-2：read_report + search_knowledge 工具实现
⏳ P0-3：定时质控 + 报告生成 + eQuery 闭环
⏳ P0-4：统一质控驾驶舱（AI Stream + eQuery 管理）

已废弃的旧计划任务：

~~Phase 3：ReAct 引擎~~ → 改用 LLM 原生 Tool Use
~~Phase 5：IntentService~~ → LLM 自行选择工具
~~微信小程序前端~~ → 管理端 Web 前端 + 企微推送

🗄️ 二、数据库Schema

2.1 Schema信息

Schema名称：iit_schema
数据库：ai_clinical_research（RDS PostgreSQL 15）
创建时间：2025-12-31
表数量：18 个（原始 5 个 + 质控 4 个 + 规则/技能 4 个 + 知识库/会话/字段元数据 5 个）
验证状态：✅ 已创建并验证

2.2 核心表结构

表名	用途	类别
IitProject	项目配置（REDCap 连接 + 规则 + 知识库）	基础
IitPendingAction	影子状态（待审核动作）	基础
IitTaskRun	任务运行记录	基础
IitUserMapping	跨系统用户映射	基础
IitAuditLog	审计日志	基础
iit_qc_logs	质控日志（单条质控问题记录）	质控
iit_record_summary	患者录入汇总	质控
iit_qc_project_stats	项目级质控统计	质控
iit_field_metadata	REDCap 字段元数据缓存	质控
iit_qc_rules	质控规则定义	规则
iit_qc_skills	质控技能定义	规则
iit_qc_rule_skill	规则-技能关联	规则
iit_qc_skill_triggers	技能触发器	规则
iit_chat_sessions	对话会话	会话
iit_chat_messages	对话消息	会话
iit_knowledge_bases	知识库	知识
iit_knowledge_documents	知识库文档	知识
iit_qc_reports（V3.0 新增）	质控报告归档	报告

2.3 Prisma Schema位置

AIclinicalresearch/backend/prisma/schema.prisma

IIT Manager Schema定义（~350 行类型定义）：

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

🔧 三、技术架构

3.1 后端技术栈

核心框架：

Node.js：v22.x
Web框架：Fastify
ORM：Prisma 6.17.0（多Schema支持）
任务队列：pg-boss（Postgres-Only架构）
AI能力：LLM Tool Use (DeepSeek/Qwen) + 自研 RAG (pgvector)

模块结构（61 个文件，~15,000+ 行）：

backend/src/modules/iit-manager/
├── index.ts                  ✅ 主入口
├── types/index.ts            ✅ 类型定义
├── routes/                   ✅ 路由（5+ 个路由文件）
├── controllers/              ✅ 控制器（Webhook/QcCockpit/Admin）
├── services/
│   ├── ChatService.ts        ✅ 1442行（V3.0 将重构为 ChatOrchestrator）
│   ├── ToolsService.ts       ✅ 731行（V3.0 重构为 4 语义化工具）
│   ├── HardRuleEngine.ts     ✅ 478行（JSON-logic 硬规则）
│   ├── SoftRuleEngine.ts     ✅ 488行（LLM 软规则）
│   ├── SkillRunner.ts        ✅ 756行（质控技能编排）
│   ├── QcReportService.ts    ✅ 980行（报告生成）
│   ├── QcService.ts          ✅ 质控查询服务
│   ├── RedcapCacheService.ts ✅ REDCap 缓存
│   ├── KnowledgeBaseService.ts ✅ 知识库服务
│   └── ...
├── adapters/
│   └── RedcapAdapter.ts      ✅ 1363行（REDCap API 适配器）
└── workers/                  ✅ pg-boss Worker（质控/同步）

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/
├── services/ChatService.ts           1442行（对话服务，V3.0 待重构）
├── adapters/RedcapAdapter.ts         1363行（REDCap API 适配器）
├── services/QcReportService.ts        980行（质控报告生成）
├── services/SkillRunner.ts            756行（技能编排器）
├── services/ToolsService.ts           731行（工具服务，V3.0 待重构）
├── services/SoftRuleEngine.ts         488行（LLM 软规则）
├── services/HardRuleEngine.ts         478行（JSON-logic 硬规则）
├── controllers/WebhookController.ts   500+行（REDCap/企微回调）
└── ... (61 files total)

代码统计：

后端代码：~15,000+ 行 / 61 个文件
数据库表：18 张（iit_schema）
Prisma Schema：~350 行类型定义

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获取成功

🎯 八、下一步工作（V3.0 开发）

8.1 V3.0 首要目标

核心目标：将 ChatService 关键词路由重构为 LLM 原生 Tool Use 架构

即将开始：P0-1 ChatOrchestrator + ToolsService 重构（2 天）

核心交付物：

ChatOrchestrator（替代 ChatService，~300 行，LLM Tool Use 循环）
ToolsService 重构（6 个细粒度工具 → 4 个语义化工具）
System Prompt（嵌入工具选择策略）
端到端测试（对话 → LLM 选工具 → 执行 → 返回结果）

详细计划：CRA Agent V3.0 开发计划

8.2 V3.0 产品三原则

AI 替代：Agent 自驱执行质控全流程，用户仅做确认
AI 白盒化：AI Stream 时间线透明展示推理与操作过程
统一视角：去角色化，单一平台所有用户可下钻查看

8.3 关键注意事项

架构决策：

✅ 报告优先，工具兜底（read_report 为主入口，80% 问答通过报告回答）
✅ LLM 原生 Tool Use，不手写 ReAct 循环
✅ 4 个粗粒度语义化工具（look_up_data / check_quality / read_report / search_knowledge）
✅ pg-boss cron 定时触发（替代自建 SchedulerService）

技术参考：

📚 九、相关文档索引

9.1 技术设计文档

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

9.2 开发计划文档

⭐⭐⭐ CRA Agent V3.0 开发计划 - 当前核心开发计划
⭐⭐ 统一数字 CRA 质控平台 PRD - 产品需求文档
⭐ UI 原型 - HTML 原型（浏览器打开预览）
MVP开发任务清单 - 初期任务清单（已归档）
V2.9.1 综合开发计划 - 旧版计划（已归档）
企业微信注册指南 - 企业微信配置
REDCap对接技术方案与实施指南 - REDCap集成完整方案

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-25
当前进度：V3.0 开发计划已定稿 | 下一步：P0-1 ChatOrchestrator + ToolsService 重构
核心文档：

CRA Agent V3.0 开发计划 ⭐⭐⭐⭐⭐

统一数字 CRA 质控平台 PRD ⭐⭐⭐⭐⭐

UI 原型 ⭐⭐⭐⭐

事件级质控开发记录

实时质控系统开发记录

40 KiB Raw Blame History Unescape Escape

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

📋 文档说明

🎯 模块概述

核心定位（V3.0 更新）

架构设计（V3.0）

当前状态

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

✅ 已完成功能（P0 自驱动质控流水线 - 2026-02-26）

✅ 已完成功能（P1 对话层 Tool Use 改造 - 2026-02-26）

✅ 已完成功能（前端架构调整 - 2026-02-26）

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

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

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

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

⏳ V3.0 开发计划（2026-02-25 定稿）

📊 一、当前开发进度

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 企业微信测试

🎯 八、下一步工作（V3.0 开发）

8.1 V3.0 首要目标

8.2 V3.0 产品三原则

8.3 关键注意事项

📚 九、相关文档索引

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：项目启动

40 KiB

Raw Blame History