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

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

文档版本： v1.0
创建日期： 2026-01-01
维护者： IIT Manager开发团队
最后更新： 2026-01-01 ✅ Day 1完成 - 基础环境初始化成功！
重大里程碑： 企业微信集成基础完成 + 网页授权及JS-SDK授权获取
文档目的： 反映模块真实状态，记录开发历程

---

📋 文档说明

本文档是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

当前状态

• 开发阶段：✅ Day 1完成（环境初始化）
• 已完成功能：
  • ✅ 数据库Schema创建（iit_schema，5个表）
  • ✅ Prisma Schema编写（223行类型定义）
  • ✅ 模块目录结构创建
  • ✅ 企业微信应用注册和配置
  • ✅ 企业微信Access Token获取成功
  • ✅ 企业微信可信域名配置成功（iit.xunzhengyixue.com）
  • ✅ 前端域名验证文件部署（v1.2）
• 未开发功能：
  • ⏳ REDCap API Adapter（拉取能力）
  • ⏳ 数据质量Agent
  • ⏳ 任务驱动引擎
  • ⏳ 患者随访Agent
  • ⏳ 微信小程序前端
• 部署状态：✅ 数据库表已创建，后端模块骨架已搭建
• 已知问题：无

---

📊 一、当前开发进度

MVP开发阶段（2周，10个工作日）

阶段	状态	完成时间	核心交付物
Day 1：环境初始化	✅ 已完成	2026-01-01	数据库Schema + 企业微信配置 + 模块骨架
Day 2：REDCap拉取	⏳ 待开始	-	REDCap API Adapter + SyncManager
Day 3：质控Agent	⏳ 待开始	-	ComplianceService + DetectionService
Day 4：企微推送	⏳ 待开始	-	WechatService + CardGenerator
Day 5：影子状态	⏳ 待开始	-	ActionService + 状态机
Day 6-7：小程序	⏳ 待开始	-	Taro前端 + 审批界面
Day 8：回写+集成	⏳ 待开始	-	REDCap回写 + 端到端测试
Day 9-10：完善+测试	⏳ 待开始	-	错误处理 + 日志 + 性能优化

当前进度统计

整体完成度：12.5%（1/8天）

已完成任务：

• ✅ 数据库初始化（11/11测试通过）
• ✅ 企业微信初始化（Access Token获取成功）
• ✅ 项目初始化（目录结构 + 类型定义）
• ✅ 企业微信网页授权及JS-SDK授权获取
• ✅ 可信域名配置（iit.xunzhengyixue.com）

待完成任务：

• ⏳ REDCap API Adapter开发
• ⏳ 数据质量Agent开发
• ⏳ 企业微信消息推送
• ⏳ 影子状态管理
• ⏳ 微信小程序前端
• ⏳ 完整业务流程集成

---

🗄️ 二、数据库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=ww01cb7b72ea2db83c
WECHAT_AGENT_ID=1000002
WECHAT_AGENT_SECRET=F3XqlAqKdcOKHi9pLGv5a2dSUowWbevdcDRrBk2pXLM

---

🚀 四、关键里程碑

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/
├── 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：ww01cb7b72ea2db83c
• AgentID：1000002
• Secret：F3XqlAqKdcOKHi9pLGv5a2dSUowWbevdcDRrBk2pXLM

授权配置：

• 网页授权域名：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配置

连接信息（待配置）：

• API URL：待提供
• API Token：待提供
• Project ID：待提供

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

---

🎯 八、下一步工作（Day 2）

8.1 核心任务

REDCap API Adapter开发（4小时）：

• 创建 RedcapAdapter.ts
• 实现 exportRecords() 方法
• 实现 importRecords() 方法
• 实现 exportMetadata() 方法
• 配置超时和重试机制
• 编写单元测试

SyncManager开发（4小时）：

• 创建 SyncManager.ts
• 实现 initializeSync() 方法
• 实现 schedulePolling() 方法
• 实现 handlePoll() 方法
• 集成 pg-boss 定时任务

8.2 技术准备

REDCap环境准备：

• 获取测试项目API Token
• 确认API端点可访问性
• 准备测试数据

开发工具：

• 配置REDCap API调试工具
• 准备Postman测试集合

---

📚 九、相关文档索引

9.1 技术设计文档

• IIT Manager Agent 完整技术开发方案 (V1.1) - 完整技术方案
• IIT Manager Agent 技术架构白皮书 - 架构设计
• IIT Manager Agent V4 完整产品需求文档 - 产品需求

9.2 开发计划文档

• MVP开发任务清单 - 详细任务清单
• 企业微信注册指南 - 企业微信配置

9.3 开发记录文档

• V1.1更新完成报告 - 技术方案更新记录

---

🔄 十、更新日志

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-01-01 14:30
当前进度：Day 1完成（12.5%）| 下一步：Day 2 REDCap集成