AIclinicalresearch/docs/03-业务模块/IIT Manager Agent/00-模块当前状态与开发指南.md

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

文档版本： v3.1
创建日期： 2026-01-01
维护者： IIT Manager开发团队
最后更新： 2026-03-01 质控引擎 V3.1 架构升级计划定稿（五级数据结构 + 多维报告）
重大里程碑：

• 2026-03-01：质控引擎 V3.1 架构设计完成！ 五级数据结构（CDISC ODM）+ D1-D7 多维报告 + 三批次落地计划
• 2026-03-01：架构团队评审完成！ 采纳 InstanceID/规则分类/状态冒泡/LLM 三不原则，暂缓 SDV/自动映射/GCP 全量报表
• 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：QC 系统深度修复（null tolerance + baseline merge + record-level pass rate）
• ✅ 2026-02-08：事件级质控架构 V3.1 完成（record+event 独立质控 + 规则动态过滤 + 报告去重）
• ✅ 2026-02-07：实时质控系统开发完成（pg-boss防抖 + 质控日志 + 录入汇总 + 管理端批量操作）
• ✅ 2026-02-02：REDCap 生产环境部署完成（ECS + RDS + HTTPS）
• ✅ 2026-01-04：混合检索架构实现（REDCap实时数据 + Dify文档知识库）
  文档目的： 反映模块真实状态，记录开发历程
  V3.1 核心文档（质控引擎架构升级）：
• 质控引擎 V3.1 开发计划（唯一开发文档）
• CRA Agent 质控体系全景技术路径（策略评审稿）
• 五层数据架构方案评审反馈
• CRA 四大工具工作原理说明

---

📋 文档说明

本文档是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 已完成 → 正在规划 V3.1 质控引擎架构升级
• V3.0 已完成：
  • P0 自驱动质控流水线 + P1 对话层 Tool Use 改造 + E2E 54/54 通过
  • QC 系统深度修复（null tolerance + baseline merge + record-level pass rate + LLM 报告修正）
  • 前端架构调整（运营管理端 + 业务端 + Web AI 对话）
  • 项目成员管理（跨租户添加成员 + 项目知识库）
  • CRA 四大工具工作原理文档输出
• V3.1 规划中（质控引擎架构升级）：
  • 核心升级：三级数据结构 → CDISC ODM 五级结构（Record → Event → Form → Instance → Field）
  • 报告维度：从单一通过率 → D1-D7 七维质控报告（入排/完整性/准确性/Query/安全性/方案偏离/药物管理）
  • 触发模式：手动 + 定时 Cron + REDCap DET 实时触发
  • 关键机制：状态冒泡 + eQuery 自动闭环 + Record-Level Context + Event-Aware 完整性
  • 落地策略：三批次落地（A 数据地基 → B 聚合冒泡 → C 新维度引擎）
  • 开发计划文档：质控引擎 V3.1 开发计划
• 产品定位明确：运营团队配置项目（白手套服务） → 终端用户使用质控平台
• 代码规模：后端 ~14,000+ 行 / 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

✅ 已完成功能（QC 系统深度修复 + 架构评审 - 2026-02-25 ~ 03-01）

• ✅ QC 规则修复（seed-iit-qc-rules.ts：null/空字符串容忍 + applicableEvents 配置）
• ✅ HardRuleEngine 增强（字段可用性预检查 + skipped 状态）
• ✅ SkillRunner 基线数据合并（随访事件自动合并基线数据）
• ✅ QcReportService 修正（Record-Level 通过率计算 + LLM XML 报告准确性）
• ✅ 批量质控修复（iitBatchController：legacy log 清理 + upsert RecordSummary）
• ✅ CRA 四大工具原理文档（面向临床专家的工具工作原理说明文档）
• ✅ 质控引擎 V3.1 架构设计（五级数据结构 + D1-D7 维度 + 三批次落地计划）
• ✅ 架构团队评审完成（4 份白皮书评审 + 评审反馈文档 + 4 条关键落地建议采纳）
• ✅ V3.0 → V3.1 计划迁移（V3.1 为唯一开发文档，V3.0 存档供参考）

✅ 已完成功能（实时质控系统 - 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 开发计划（已完成）

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

阶段	内容	状态
P0-1	ChatOrchestrator + ToolsService 重构	✅ 已完成
P0-2	read_report + search_knowledge 实现	✅ 已完成
P0-3	定时质控 + 报告生成 + eQuery 闭环	✅ 已完成
P0-4	统一质控驾驶舱	✅ 已完成
P1	对话层 Tool Use + E2E 测试 54/54	✅ 已完成

✅ QC 系统深度修复（2026-02-25）

修复项	说明
Null Tolerance	质控规则增加 null/空字符串容忍，未填数据不再误判为 FAIL
Baseline Data Merge	SkillRunner 合并基线事件数据，解决随访期规则缺字段问题
Record-Level Pass Rate	QcReportService 改为按受试者最严重状态计算通过率
Legacy Log Cleanup	批量质控前清理 eventId 为 null 的历史脏数据
LLM 报告修正	XML 报告准确反映真实质控结果（从 0% → 92.9%）

⏳ V3.1 质控引擎架构升级（规划中）

详见：质控引擎 V3.1 开发计划（唯一开发文档）

批次	内容	预估	状态
Batch A	数据地基（五级状态表 DDL + QcExecutor + InstanceID 标准化 + D1/D3 迁移）	~5 天	待开始
Batch B	聚合冒泡（状态冒泡 + 多维报告 + Cron 灵活配置 + 驾驶舱升级）	~5 天	待开始（依赖 A）
Batch C	新维度引擎（D2 完整性 + D5 安全性 + D6 方案偏离 + 沙盒测试）	~5 天	待开始（依赖 B + 临床专家确认）
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环境就绪 - 对接方案确定 ✅

完成内容：

1. REDCap本地环境部署：

   • ✅ Docker Compose配置（3容器架构）
   • ✅ REDCap 15.8.0部署成功
   • ✅ 解决部署问题（ERR_CONTENT_DECODING_FAILED、CRLF污染等）
   • ✅ Admin账户登录成功
   • ✅ 测试项目创建（test0102, PID 16）
   • ✅ 测试数据录入成功

2. REDCap技术调研：

   • ✅ 源码分析（redcap15.8.0/）
   • ✅ External Module文档研究（redcap_external_module_framework_docs_main/）
   • ✅ 验证DET功能真实存在（Classes/DataEntry.php）
   • ✅ 确认REST API可用性

3. 对接方案确定：

   • ✅ 技术选型：DET + REST API（不使用External Module）
   • ✅ 架构设计：实时触发（DET） + 轮询补充（每30分钟）
   • ✅ 实时性保证：0秒延迟触发 + 5秒内完成质控
   • ✅ 可靠性保证：Webhook幂等性 + 轮询补充机制

4. 技术方案文档编写：

   • ✅ 创建《REDCap对接技术方案与实施指南》（1070行）
   • ✅ 完整代码设计（RedcapAdapter、WebhookController、SyncManager）
   • ✅ 详细实施步骤（Day 2清单）
   • ✅ 测试验证方案

5. REDCap文档体系建立：

   • ✅ 创建REDCap模块文档结构
   • ✅ 编写《REDCap Docker部署操作手册》
   • ✅ 编写《部署问题排查手册》
   • ✅ 整理参考资料和最佳实践

关键成果：

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

技术亮点：

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

验收标准：

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

---

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

完成内容：

1. 数据库初始化：

   • ✅ 创建 iit_schema
   • ✅ 编写 Prisma Schema（5个表）
   • ✅ 同步数据库（npx prisma db push）
   • ✅ 生成 Prisma Client
   • ✅ 验证CRUD操作（11/11测试通过）

2. 企业微信初始化：

   • ✅ 注册企业微信开发者账号
   • ✅ 创建自建应用
   • ✅ 获取并配置凭证（CorpID、AgentID、Secret）
   • ✅ 测试Access Token获取成功
   • ✅ 获取网页授权及JS-SDK授权
   • ✅ 配置可信域名（iit.xunzhengyixue.com）

3. 项目初始化：

   • ✅ 创建模块目录结构
   • ✅ 配置路由前缀（/api/v1/iit）
   • ✅ 创建基础类型定义（223行）

4. 前端部署：

   • ✅ 前端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

测试内容：

1. ✅ IitProject CRUD操作
2. ✅ IitPendingAction CRUD操作
3. ✅ IitTaskRun CRUD操作
4. ✅ IitUserMapping CRUD操作
5. ✅ 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

测试内容：

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

运行方式：

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 产品三原则

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

8.3 关键注意事项

架构决策：

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

技术参考：

• 📖 CRA Agent V3.0 开发计划
• 📖 统一数字 CRA 质控平台 PRD
• 📖 UI 原型
• 📖 REDCap对接技术方案与实施指南

---

📚 九、相关文档索引

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回答完全基于真实数据/文档（防止幻觉）
• 🎉 智能路由机制（根据问题自动选择数据源）
• 🎉 完整排查流程记录（从问题发现到根因修复）

技术亮点：

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

测试验证：

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

问题排查记录：

1. 问题：AI编造答案，不查询Dify

   • 根因1：意图识别关键词不全（缺"入选"、"诊断标准"等）
   • 解决：扩充关键词正则表达式
   • 根因2：Dify API字段路径错误（record.document_name → record.segment.document.name）
   • 解决：修正字段访问路径

2. 调试工具：

   • debug-dify-injection.ts：追踪Dify结果是否正确注入LLM
   • inspect-dify-response.ts：查看Dify API实际返回结构

技术债务：

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

参考文档：

• Dify知识库集成开发记录
• IIT Manager Agent 技术路径与架构设计

下一步：

• 🔄 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秒（超出预期）

技术亮点：

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

参考文档：

• Day3-企业微信集成与端到端测试完成记录
• Phase 1.5开发完成记录

---

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文档体系完整（部署、对接、排查全覆盖）

技术亮点：

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

技术决策：

• ❌ 不使用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授权已获取
• 🎉 为微信小程序开发铺平道路

技术要点：

1. Prisma Multi-Schema支持：成功配置iit_schema
2. 企业微信API测试：Access Token获取验证通过
3. 域名验证：解决Windows换行符问题（CRLF→LF）
4. 前端部署：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 原型 ⭐⭐⭐⭐
• 事件级质控开发记录
• 实时质控系统开发记录