Files

HaHafeng dfc472810b feat(iit-manager): Integrate Dify knowledge base for hybrid retrieval

Completed features:
- Created Dify dataset (Dify_test0102) with 2 processed documents
- Linked test0102 project with Dify dataset ID
- Extended intent detection to recognize query_protocol intent
- Implemented queryDifyKnowledge method (semantic search Top 5)
- Integrated hybrid retrieval (REDCap data + Dify documents)
- Fixed AI hallucination bugs (intent detection + API field path)
- Developed debugging scripts
- Completed end-to-end testing (5 scenarios passed)
- Generated comprehensive documentation (600+ lines)
- Updated development plans and module status

Technical highlights:
- Single project single knowledge base architecture
- Smart routing based on user intent
- Prevent AI hallucination by injecting real data/documents
- Session memory for multi-turn conversations
- Reused LLMFactory for DeepSeek-V3 integration

Bug fixes:
- Fixed intent detection missing keywords
- Fixed Dify API response field path error

Testing: All scenarios verified in WeChat production environment

Status: Fully tested and deployed

2026-01-04 15:44:11 +08:00

34 KiB

Raw Blame History

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

文档版本： v1.6
创建日期： 2026-01-01
维护者： IIT Manager开发团队
最后更新： 2026-01-04 🎉 Dify知识库集成完成 - 混合检索实现！
重大里程碑： ✅ 混合检索架构实现（REDCap实时数据 + Dify文档知识库）！
文档目的： 反映模块真实状态，记录开发历程

📋 文档说明

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

与其他文档的关系：

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

🎯 模块概述

核心功能

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

架构设计

核心理念：Native Orchestration（原生编排）+ Dify RAG + Shadow State（影子状态）
技术栈：
- 后端：Node.js (Fastify) + PostgreSQL (Prisma) + pg-boss
- 前端：微信小程序 (Taro 4.x)
- 数据源：REDCap (EDC系统)
- 通知：企业微信
- AI能力：Dify RAG + DeepSeek/Qwen

当前状态

开发阶段：🎉 Phase 1.5完成 - 混合检索架构实现！
整体完成度：65%（Day 1-3 + Phase 1.5完成 + Dify集成完成）
已完成功能：
- ✅ 数据库Schema创建（iit_schema，5个表）
- ✅ Prisma Schema编写（223行类型定义）
- ✅ 模块目录结构创建
- ✅ 企业微信应用注册和配置
- ✅ 企业微信Access Token获取成功
- ✅ 企业微信可信域名配置成功（devlocal.xunzhengyixue.com）
- ✅ REDCap本地Docker环境部署成功（15.8.0）
- ✅ REDCap对接技术方案确定（DET + REST API）
- ✅ REDCap测试项目创建（test0102, PID 16, 11条记录）
- ✅ REDCap实时集成完成（DET + REST API + WebhookController + SyncManager）
- ✅ 企业微信推送服务完成（WechatService, 314行）
- ✅ 企业微信回调处理完成（WechatCallbackController, 501行）
- ✅ natapp内网穿透配置成功（https://devlocal.xunzhengyixue.com + 公司备案域名）
- ✅ RedcapAdapter API适配器完成（271行，7个API方法）
- ✅ WebhookController完成（327行，<10ms响应）
- ✅ SyncManager完成（398行，增量+全量同步）
- ✅ Worker注册完成（iit_quality_check, iit_redcap_poll）
- ✅ 质控Worker完善（质控逻辑 + 企业微信推送 + 审计日志）
- ✅ 🎯 端到端测试通过（REDCap → Node.js → 企业微信，<2秒延迟）
- ✅ 🎯 MVP闭环完全打通（100%消息成功率）
- ✅ 🚀 Phase 1.5: AI对话集成完成（2026-01-03 & 2026-01-04）
  - ✅ ChatService集成（485行）
  - ✅ SessionMemory（120行，上下文记忆）
  - ✅ REDCap数据查询集成（queryRedcapRecord, countRedcapRecords）
  - ✅ Dify知识库集成（queryDifyKnowledge）
  - ✅ 混合检索实现（REDCap实时数据 + Dify文档知识库）
  - ✅ 智能路由（根据意图自动选择数据源）
  - ✅ 意图识别优化（扩充医学关键词库）
  - ✅ 数据注入LLM（基于真实数据，不编造）
  - ✅ 即时反馈（"正在查询"）
  - ✅ Dify Dataset关联（test0102 → b49595b2-bf71-4e47-9988-4aa2816d3c6f）
  - ✅ Bug修复（Dify API字段路径错误修正）
  - ✅ 测试通过（5个场景：REDCap查询、Dify文档查询、混合查询）
未开发功能：
- ⏳ Function Calling（LLM自主决策）- Phase 2
- ⏳ 多项目支持（项目切换）- Phase 2
- ⏳ 文档API上传（自动化上传到Dify）- Phase 2
- ⏳ 数据质量Agent（AI质控逻辑）- Phase 2
- ⏳ 任务驱动引擎 - Phase 2
- ⏳ 患者随访Agent - Phase 2
- ⏳ 微信小程序前端 - Phase 3
- ⏳ REDCap双向回写 - Phase 2
部署状态：✅ AI对话正常运行，支持REDCap实时数据 + Dify文档查询
已知问题：无
临时措施：
- ⚠️ 使用关键词匹配识别意图（Phase 2升级为Function Calling）
- ⚠️ SessionMemory基于内存（Phase 2改为Redis）
- ⚠️ 默认查询第一个active项目（Phase 2支持项目选择）
- ⚠️ Dify文档通过Web界面手动上传（Phase 2开发API自动上传）
- ⚠️ 单项目单知识库（Phase 2支持多知识库）
- ⚠️ UserID从环境变量获取（WECHAT_TEST_USER_ID）- Phase 2改进
- ⚠️ 定时轮询暂时禁用（REDCap DET已足够）- Phase 2添加

📊 一、当前开发进度

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集成
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-01-03 22:30
当前进度：Day 1-3 + Phase 1.5完成（60%）| 下一步：Phase 2 Function Calling + Dify知识库
重要文档：

Phase 1.5开发完成记录 ⭐⭐⭐⭐⭐

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

34 KiB Raw Blame History Unescape Escape

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

📋 文档说明

🎯 模块概述

核心功能

架构设计

当前状态

📊 一、当前开发进度

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

34 KiB

Raw Blame History