# 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完成 - 混合检索架构实现！**
- **整体完成�?*�?5%（Day 1-3 + Phase 1.5完成 + Dify集成完成�?- **已完成功�?*�?  - �?数据库Schema创建（iit_schema�?个表�?  - �?Prisma Schema编写�?23行类型定义）
  - �?模块目录结构创建
  - �?企业微信应用注册和配�?  - �?企业微信Access Token获取成功
  - �?**企业微信可信域名配置成功**（devlocal.xunzhengyixue.com�?  - �?**REDCap本地Docker环境部署成功**�?5.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适配器完�?*�?71行，7个API方法�?  - �?**WebhookController完成**�?27行，<10ms响应�?  - �?**SyncManager完成**�?98行，增量+全量同步�?  - �?**Worker注册完成**（iit_quality_check, iit_redcap_poll�?  - �?**质控Worker完善**（质控逻辑 + 企业微信推�?+ 审计日志�?  - �?**🎯 端到端测试通过**（REDCap �?Node.js �?企业微信�?2秒延迟）
  - �?**🎯 MVP闭环完全打�?*�?00%消息成功率）
  - �?**🚀 Phase 1.5: AI对话集成完成**�?026-01-03 & 2026-01-04�?    - �?ChatService集成�?85行）
    - �?SessionMemory�?20行，上下文记忆）
    - �?REDCap数据查询集成（queryRedcapRecord, countRedcapRecords�?    - �?**Dify知识库集�?*（queryDifyKnowledge�?    - �?**混合检索实�?*（REDCap实时数据 + Dify文档知识库）
    - �?**智能路由**（根据意图自动选择数据源）
    - �?意图识别优化（扩充医学关键词库）
    - �?数据注入LLM（基于真实数据，不编造）
    - �?即时反馈�?正在查询"�?    - �?**Dify Dataset关联**（test0102 �?b49595b2-bf71-4e47-9988-4aa2816d3c6f�?    - �?**Bug修复**（Dify API字段路径错误修正�?    - �?测试通过�?个场景：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：完�?测试** | �?待开�?| - | 错误处理 + 日志 + 性能优化 |

### 当前进度统计

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

**Day 3已完�?*�?026-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�?- **创建时间**�?025-12-31
- **表数�?*�?�?- **验证状�?*：✅ 已创建并验证

### 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定义**（位于文件末尾）�?- 完整�?个表模型定义
- 外键关系配置
- 索引优化
- 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             �?类型定义�?23行）
├── 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）：
```bash
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配置�?容器架构�?   - �?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原生支持�?- 🎉 对接方案技术可行�?00%确认
- 🎉 完整实施指南已编写（可直接开发）

**技术亮�?*�?1. **DET实时触发**�?秒延迟，满足实时质控需�?2. **双保险机�?*：Webhook + 轮询，确保数据不丢失
3. **零侵入�?*：无需修改REDCap源码，只用原生API
4. **生产级架�?*：开发环境与生产环境配置一�?
**验收标准**�?- �?REDCap可通过浏览器访�?- �?Admin账户登录成功
- �?测试项目可正常使�?- �?DET功能在源码中确认存在
- �?REST API端点可访�?- �?技术方案文档完�?- �?代码设计可直接实�?
---

### 2026-01-01：Day 1完成 - 环境初始�?�?
**完成内容**�?1. **数据库初始化**�?   - �?创建 `iit_schema`
   - �?编写 Prisma Schema�?个表�?   - �?同步数据库（`npx prisma db push`�?   - �?生成 Prisma Client
   - �?验证CRUD操作�?1/11测试通过�?
2. **企业微信初始�?*�?   - �?注册企业微信开发者账�?   - �?创建自建应用
   - �?获取并配置凭证（CorpID、AgentID、Secret�?   - �?测试Access Token获取成功
   - �?**获取网页授权及JS-SDK授权**
   - �?**配置可信域名（iit.xunzhengyixue.com�?*

3. **项目初始�?*�?   - �?创建模块目录结构
   - �?配置路由前缀（`/api/v1/iit`�?   - �?创建基础类型定义�?23行）

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�?个表定义�?- 位于文件末尾
- 包含外键关系和索�?```

**模块代码**�?```
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行（企微测试�?```

**代码统计**�?- **已完成代�?*�?77�?- **测试脚本**�?49�?- **总计**�?26�?
### 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版本**�?5.8.0
- **访问地址**：`http://localhost:8080`
- **Admin账户**：`Admin` / `Xilu,881009`
- **部署方式**：Docker Compose�?容器：Apache+PHP+REDCap、MySQL、phpMyAdmin�?- **Docker项目路径**：`AIclinicalresearch/redcap-docker-dev/`
- **部署状�?*：✅ 运行�?
**测试项目信息**�?- **项目名称**：test0102
- **Project ID (PID)**�?6
- **项目状�?*：已创建，已录入测试数据
- **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操作

**运行方式**�?```bash
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. �?卡片消息发送（待测试）

**运行方式**�?```bash
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`�?- �?完整测试（单元测�?+ 集成测试�?
**预计工作�?*�?-8小时（完整工作日�?
---

### 8.2 阶段1：环境准备（30分钟�?
**REDCap配置**�?- [ ] 在Control Center启用DET功能
- [ ] 在test0102项目生成API Token
- [ ] 配置环境变量�?  ```env
  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小时�?
**测试内容**�?1. **DET配置验证**�?   - [ ] 在REDCap中配置DET URL
   - [ ] 使用ngrok测试Webhook
   - [ ] 验证Payload格式

2. **API测试**�?   - [ ] 运行 `test-redcap-api.ts`
   - [ ] 验证exportRecords正常
   - [ ] 验证exportMetadata正常

3. **端到端测�?*�?   - [ ] 在REDCap保存一条记�?   - [ ] 验证Webhook被触�?   - [ ] 验证数据被拉�?   - [ ] 验证数据推送到队列
   - [ ] 验证审计日志记录

4. **轮询测试**�?   - [ ] 手动触发轮询
   - [ ] 验证增量拉取
   - [ ] 验证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遗漏�?- ⚠️ 记录详细日志（便于排查问题）

**技术参�?*�?- 📖 [REDCap对接技术方案与实施指南](./04-开发计�?REDCap对接技术方案与实施指南.md)
- 📖 [REDCap二次开发深度指南](../../Redcap/03-API对接与开�?33-REDCap二次开发深度指�?md)
- 📖 [REDCap Docker部署操作手册](../../Redcap/01-部署与配�?10-REDCap_Docker部署操作手册.md)

---

## 📚 九、相关文档索�?
### 9.1 技术设计文�?
- [IIT Manager Agent 完整技术开发方�?(V1.1)](./02-技术设�?IIT%20Manager%20Agent%20完整技术开发方�?20(V1.1).md) - 完整技术方�?- [IIT Manager Agent 技术架构白皮书](./00-系统设计/IIT%20Manager%20Agent%20技术架构白皮书.md) - 架构设计
- [IIT Manager Agent V4 完整产品需求文档](./00-系统设计/IIT%20Manager%20Agent%20V4%20完整产品需求文�?md) - 产品需�?- [EDC 适配�?(REDCap) 技术详细设�?(V1.0)](./02-技术设�?文档%20B：EDC%20适配�?20(REDCap)%20技术详细设�?20(V1.0).md) - REDCap适配器设�?
### 9.2 开发计划文�?
- [MVP开发任务清单](./04-开发计�?MVP开发任务清�?md) - 详细任务清单
- [企业微信注册指南](./04-开发计�?企业微信注册指南.md) - 企业微信配置
- �?[REDCap对接技术方案与实施指南](./04-开发计�?REDCap对接技术方案与实施指南.md) - REDCap集成完整方案（Day 2核心参考）

### 9.3 REDCap相关文档

- [REDCap模块文档导航](../../Redcap/00-模块概览/00-REDCap模块文档导航.md) - REDCap文档总览
- [REDCap Docker部署操作手册](../../Redcap/01-部署与配�?10-REDCap_Docker部署操作手册.md) - Docker部署指南
- [REDCap二次开发深度指南](../../Redcap/03-API对接与开�?33-REDCap二次开发深度指�?md) - 二次开发参�?- [部署问题排查手册](../../Redcap/01-部署与配�?13-部署问题排查手册.md) - 常见问题解决

### 9.4 开发记录文�?
- [V1.1更新完成报告](./06-开发记�?V1.1更新完成报告.md) - 技术方案更新记�?
---

## 🔄 十、更新日�?
### 2026-01-04：Dify知识库集成完�?- 混合检索实�?�?
**完成内容**�?- �?**Dify知识库创�?*（Dify_test0102�?个文档已处理�?- �?**项目关联配置**（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�?- �?**端到端测�?*�?个场景全部通过�?- �?**开发记录文�?*�?00+行完整记录）

**关键成果**�?- 🎉 **混合检索架构实�?*（结构化数据 + 非结构化文档�?- 🎉 **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知识库集成开发记录](./06-开发记�?2026-01-04-Dify知识库集成开发记�?md)
- [IIT Manager Agent 技术路径与架构设计](./02-技术设�?IIT%20Manager%20Agent%20技术路径与架构设计.md)

**下一�?*�?- 🔄 **Phase 2**：多项目支持、文档API上传、Function Calling

---

### 2026-01-03：Day 3完成 - 企业微信集成 + Phase 1.5 AI对话 �?
**完成内容**�?- �?**WechatService开�?*�?14行，消息推送服务）
- �?**WechatCallbackController开�?*�?01行，回调处理 + 对话集成�?- �?**质控Worker完善**�?36行，质控逻辑 + 企微推�?+ 审计日志�?- �?**Worker注册修复**（initIitManager调用�?- �?**数据库字段修�?*（action_type�?- �?**端到端测试通过**（REDCap �?Node.js �?企微�?2秒）
- �?**Phase 1.5: ChatService开�?*�?90行，AI对话服务�?- �?**SessionMemory开�?*�?70行，上下文记忆）
- �?**REDCap数据查询集成**（queryRedcapRecord, countRedcapRecords�?- �?**意图识别实现**（关键词匹配�?- �?**LLM集成**（DeepSeek-V3, LLMFactory复用�?- �?**防止幻觉**（数据注入LLM，基于真实数据回答）

**关键成果**�?- 🎉 **MVP闭环完全打�?*（REDCap �?Node.js �?企微 �?AI对话�?- 🎉 **AI基于REDCap真实数据对话**（解决LLM幻觉问题�?- 🎉 **上下文记忆实�?*（最�?轮对话）
- 🎉 **端到端延�?2�?*（超出预期）

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

**参考文�?*�?- [Day3-企业微信集成与端到端测试完成记录](./06-开发记�?Day3-企业微信集成与端到端测试完成记录.md)
- [Phase 1.5开发完成记录](./06-开发记�?Phase1.5-AI对话集成REDCap完成记录.md)

---

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

**关键成果**�?- 🎉 **REDCap本地环境稳定运行**（可随时用于开发测试）
- 🎉 **DET功能验证成功**（REDCap原生支持，无需PHP开发）
- 🎉 **对接方案100%技术可�?*（实时�?可靠性双保证�?- 🎉 **完整实施指南已编�?*（可直接进入Day 2开发）
- 🎉 **REDCap文档体系完整**（部署、对接、排查全覆盖�?
**技术亮�?*�?1. **DET实时触发**�?秒延迟，CRC保存数据�?秒内完成质控
2. **双保险机�?*：Webhook（主�?+ 定时轮询（补充），数据不丢失
3. **零侵入�?*：只使用REDCap原生API和DET，无需修改源码
4. **生产级架�?*：Docker配置可直接用于ECS/医院环境部署
5. **完整文档**：从部署到开发，全流程文档化

**技术决�?*�?- �?**不使用External Module**（需要PHP开发、侵入性强、维护成本高�?- �?**使用DET + REST API**（REDCap原生功能、零代码配置、实时触发）
- �?**实时触发 + 轮询补充**（实时�?9% + 可靠�?00%�?
**部署记录**�?- **REDCap版本**�?5.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�?个表�?- �?Prisma Schema编写�?23行类型定义）
- �?数据库CRUD验证�?1/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部署成功，内网地址�?72.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模块的最新真实状态，每个里程碑完成后必须更新�? 
> **最后更�?*�?026-01-03 22:30  
> **当前进度**：Day 1-3 + Phase 1.5完成�?0%）| 下一步：Phase 2 Function Calling + Dify知识�? 
> **重要文档**�?> - [Phase 1.5开发完成记录](./06-开发记�?Phase1.5-AI对话集成REDCap完成记录.md) ⭐⭐⭐⭐�?> - [REDCap对接技术方案与实施指南](./04-开发计�?REDCap对接技术方案与实施指南.md) ⭐⭐⭐⭐�?