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

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

> **文档版本：** v3.0  
> **创建日期：** 2026-01-01  
> **维护者：** IIT Manager开发团队  
> **最后更新：** 2026-02-25 **CRA Agent V3.0 开发计划定稿**  
> **重大里程碑：**  
> - **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 开发计划](./04-开发计划/V3.0全新开发计划/V3.0全新开发计划.md)  
> - [统一数字 CRA 质控平台 PRD](./04-开发计划/V3.0全新开发计划/统一数字%20CRA%20质控平台产品需求文档(PRD).md)  
> - [UI 原型](./04-开发计划/V3.0全新开发计划/Final%20CRA质控平台V3.html)

---

## 📋 文档说明

本文档是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 开发**
- **已完成的基础设施**（可复用）：
  - HardRuleEngine (478行) + SoftRuleEngine (488行) + SkillRunner (756行)
  - RedcapAdapter (1363行) + QcReportService (980行) + ToolsService (731行)
  - 实时质控 Webhook + 质控驾驶舱 UI + 18 张数据库表
  - 企业微信推送 + REDCap 生产环境
- **待重构**：ChatService (1442行，关键词路由) → ChatOrchestrator + 4 Tool Use
- **代码规模**：后端 ~15,000+ 行 / 61 个文件 / 18 张表（iit_schema）

#### ✅ 已完成功能（基础设施）
- ✅ 数据库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 错误 + 记录数统计 + 报告限制移除）

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

> 详见：[CRA Agent V3.0 开发计划](./04-开发计划/V3.0全新开发计划/V3.0全新开发计划.md)

| 阶段 | 内容 | 预估 | 状态 |
|------|------|------|------|
| **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 开发计划](./04-开发计划/V3.0全新开发计划/V3.0全新开发计划.md)
- **历史计划文档**：[V2.9.1 综合开发计划](./04-开发计划/IIT%20Manager%20Agent%20V2.6%20综合开发计划.md)（已归档）

---

## 📊 一、当前开发进度

### 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）：
```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配置（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操作

**运行方式**：
```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获取成功

---

## 🎯 八、下一步工作（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 开发计划](./04-开发计划/V3.0全新开发计划/V3.0全新开发计划.md)

### 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 开发计划](./04-开发计划/V3.0全新开发计划/V3.0全新开发计划.md)
- 📖 [统一数字 CRA 质控平台 PRD](./04-开发计划/V3.0全新开发计划/统一数字%20CRA%20质控平台产品需求文档(PRD).md)
- 📖 [UI 原型](./04-开发计划/V3.0全新开发计划/Final%20CRA质控平台V3.html)
- 📖 [REDCap对接技术方案与实施指南](./04-开发计划/REDCap对接技术方案与实施指南.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 开发计划文档

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

### 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，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知识库集成开发记录](./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开发**（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-企业微信集成与端到端测试完成记录](./06-开发记录/Day3-企业微信集成与端到端测试完成记录.md)
- [Phase 1.5开发完成记录](./06-开发记录/Phase1.5-AI对话集成REDCap完成记录.md)

---

### 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 开发计划](./04-开发计划/V3.0全新开发计划/V3.0全新开发计划.md) ⭐⭐⭐⭐⭐
> - [统一数字 CRA 质控平台 PRD](./04-开发计划/V3.0全新开发计划/统一数字%20CRA%20质控平台产品需求文档(PRD).md) ⭐⭐⭐⭐⭐
> - [UI 原型](./04-开发计划/V3.0全新开发计划/Final%20CRA质控平台V3.html) ⭐⭐⭐⭐
> - [事件级质控开发记录](./06-开发记录/2026-02-08-事件级质控与报告优化开发记录.md)
> - [实时质控系统开发记录](./06-开发记录/2026-02-07-实时质控系统开发记录.md)