AIclinicalresearch/docs/03-业务模块/IIT Manager Agent/04-开发计划/REDCap对接技术方案与实施指南.md

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

**版本：** V1.0  
**创建日期：** 2026-01-02  
**适用阶段：** IIT Manager Agent MVP - Day 2  
**文档性质：** 核心技术基石  
**重要程度：** ⭐⭐⭐⭐⭐

---

## 📋 文档目标

本文档是IIT Manager Agent与REDCap集成的**权威技术指南**，明确：
1. ✅ REDCap对接方式的技术选型
2. ✅ Data Entry Trigger (DET) 的验证与配置
3. ✅ REST API的使用方法
4. ✅ 实时质控的完整架构
5. ✅ Day 2的开发实施步骤

---

## 🎯 核心结论（Executive Summary）

### ✅ **技术选型：DET（实时触发） + REST API（数据读写）**

**不采用：** External Module (EM)  
**原因：** EM需要PHP开发、侵入REDCap源码、维护成本高、不适合外部系统集成

**采用方案：**

| 组件 | 技术 | 用途 | 实时性 |
|------|-----|------|--------|
| **Data Entry Trigger** | REDCap原生功能 | 数据保存时实时通知 | 0秒延迟 |
| **REST API (Export)** | HTTP + JSON | 拉取数据、元数据 | 按需调用 |
| **REST API (Import)** | HTTP + JSON | 回写质控意见（Phase 2） | 按需调用 |
| **轮询机制** | pg-boss定时任务 | 补充DET遗漏数据 | 30分钟 |

---

## 🔍 技术调研结果

### 调研1：REDCap提供的对接方式

**调研来源：**
- REDCap 15.8.0源码
- External Module Framework官方文档
- REDCap二次开发深度指南

**发现的对接方式：**

| 方式 | 技术栈 | 适用场景 | 我们是否适用 |
|------|--------|---------|-------------|
| **External Module** | PHP + Hook | REDCap内部功能扩展、UI定制 | ❌ 不适用 |
| **REST API** | HTTP + JSON | 外部系统集成、数据同步 | ✅ **适用** |
| **Data Entry Trigger** | Webhook | 实时通知外部系统 | ✅ **适用** |

### 调研2：Data Entry Trigger (DET) 验证

**源码位置：**
```
/var/www/html/redcap/redcap_v15.8.0/Classes/DataEntry.php
/var/www/html/redcap/redcap_v15.8.0/ProjectSetup/index.php
/var/www/html/redcap/redcap_v15.8.0/ControlCenter/modules_settings.php
```

**关键代码：**
```php
// DataEntry.php 核心实现
global $data_entry_trigger_url, $data_entry_trigger_enabled;
if (!$data_entry_trigger_enabled || $data_entry_trigger_url == '') {
    return;
}
// 发送HTTP POST到配置的URL
$full_url = $pre_url . $data_entry_trigger_url;
```

**验证结论：** ✅ DET是REDCap原生功能，真实存在且广泛使用

---

## 🏗️ 完整架构设计

### 架构图

```
┌─────────────────────────────────────────────────────┐
│  1. CRC 在 REDCap 中保存记录                         │
│     - 录入患者数据                                   │
│     - 点击"Save"按钮                                 │
└──────────────────┬──────────────────────────────────┘
                   ↓ 立即触发（REDCap DET，0秒延迟）
┌─────────────────────────────────────────────────────┐
│  2. REDCap Data Entry Trigger (DET)                 │
│     POST → https://iit.xunzhengyixue.com/           │
│              api/v1/iit/webhooks/redcap             │
│     Payload:                                         │
│       - project_id: 16                               │
│       - record: 101                                  │
│       - instrument: demographics                     │
│       - redcap_event_name: baseline_arm_1            │
└──────────────────┬──────────────────────────────────┘
                   ↓ 1秒内
┌─────────────────────────────────────────────────────┐
│  3. Node.js Webhook接收器                           │
│     - 验证请求来源（可选）                           │
│     - 立即返回200 OK（<100ms，不阻塞REDCap）        │
│     - 异步调用质控流程（setImmediate）               │
└──────────────────┬──────────────────────────────────┘
                   ↓ 异步处理
┌─────────────────────────────────────────────────────┐
│  4. REDCap REST API - exportRecords                 │
│     - 使用API Token认证                             │
│     - 拉取指定record_id的完整数据                   │
│     - 包含所有字段值、元数据                         │
└──────────────────┬──────────────────────────────────┘
                   ↓
┌─────────────────────────────────────────────────────┐
│  5. 推送到质控队列                                   │
│     - jobQueue.send('iit:quality-check', record)    │
│     - 异步处理，不影响实时响应                       │
└──────────────────┬──────────────────────────────────┘
                   ↓ 由QualityCheckAgent处理（Day 6）
┌─────────────────────────────────────────────────────┐
│  6. AI质控分析                                       │
│     - 规则引擎验证                                   │
│     - AI推理检测异常                                 │
│     - 生成质控报告                                   │
└──────────────────┬──────────────────────────────────┘
                   ↓ 3-5秒内
┌─────────────────────────────────────────────────────┐
│  7. 多渠道反馈                                       │
│     A. 企业微信推送给CRC（实时通知）                 │
│     B. REDCap API importQueries（写回质疑）          │
│     C. IIT Manager前端显示（待办事项）               │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│  补充：定时轮询机制（每30分钟）                      │
│     - 防止DET遗漏数据                                │
│     - 使用dateRangeBegin增量拉取                    │
│     - 推送到相同的质控队列                           │
└─────────────────────────────────────────────────────┘
```

### 实时性对比

| 方案 | 延迟时间 | 我们的选择 |
|------|---------|-----------|
| **纯轮询（每5分钟）** | 最高5分钟 | ❌ 不满足实时性要求 |
| **纯轮询（每1分钟）** | 最高1分钟 | ⚠️ 资源浪费、延迟仍高 |
| **DET + API** | 0秒触发 + 3-5秒处理 | ✅ **最优方案** |
| **DET + 轮询补充** | 实时 + 可靠 | ✅ **最终架构** |

**结论：** CRC点击"保存" → 5秒内收到企业微信通知 ✅

---

## 📦 技术实现详解

### 1. Data Entry Trigger (DET) 配置

#### 步骤1：在Control Center启用DET

```
1. 登录REDCap：http://localhost:8080/
2. 使用管理员账户（Admin / Admin123!）
3. 进入：Control Center → "Additional Customizations"
4. 找到："Data Entry Trigger" 选项
5. 设置为："Enabled"
6. 保存配置
```

**数据库字段：** `redcap_config.data_entry_trigger_enabled = 1`

#### 步骤2：在项目中配置Webhook URL

```
1. 进入测试项目：test0102 (PID 16)
2. 左侧菜单 → Project Setup
3. 找到："Additional Customizations"
4. 展开："Data Entry Trigger URL"
5. 填入Webhook URL：
   - 开发环境：http://localhost:3001/api/v1/iit/webhooks/redcap
   - 测试环境：https://backend-dev.xunzhengyixue.com/api/v1/iit/webhooks/redcap
   - 生产环境：https://iit.xunzhengyixue.com/api/v1/iit/webhooks/redcap
6. 保存
```

**数据库字段：** `redcap_projects.data_entry_trigger_url`

#### 步骤3：验证DET配置

**使用RequestBin/ngrok验证：**

```bash
# 使用ngrok创建临时公网URL（开发测试用）
ngrok http 3001

# 将ngrok URL配置到REDCap DET
# 例如：https://1234-abc-def.ngrok.io/api/v1/iit/webhooks/redcap

# 在REDCap中保存一条记录
# 检查ngrok控制台是否收到POST请求
```

#### DET的POST Payload格式

**REDCap发送的请求：**

```http
POST /api/v1/iit/webhooks/redcap HTTP/1.1
Host: iit.xunzhengyixue.com
Content-Type: application/x-www-form-urlencoded
User-Agent: REDCap/15.8.0

project_id=16
&record=101
&instrument=demographics
&redcap_event_name=baseline_arm_1
&demographics_complete=2
&redcap_url=http://localhost:8080/
```

**字段说明：**

| 字段 | 类型 | 说明 | 示例 |
|------|-----|------|------|
| `project_id` | string | REDCap项目ID | "16" |
| `record` | string | 记录ID | "101" |
| `instrument` | string | 表单名称 | "demographics" |
| `redcap_event_name` | string | 事件名称（纵向研究） | "baseline_arm_1" |
| `[instrument]_complete` | string | 表单完成状态（0/1/2） | "2" |
| `redcap_url` | string | REDCap实例URL | "http://localhost:8080/" |

---

### 2. REDCap REST API 使用

#### API端点

```
http://localhost:8080/api/
```

#### API认证：Token

**生成步骤：**
```
1. 登录REDCap
2. 进入项目：test0102 (PID 16)
3. 左侧菜单 → "API"
4. 点击 "Generate API Token"
5. 复制Token（32位字符串）
6. 保存到环境变量：
   REDCAP_API_TOKEN_TEST=YOUR_TOKEN_HERE
```

**Token存储：**
- ✅ 环境变量（推荐）
- ✅ 数据库加密字段（IitProject.redcapApiToken）
- ❌ 不要提交到Git

#### API方法1：导出记录 (exportRecords)

**用途：** 拉取数据（支持增量同步）

**请求示例（curl）：**

```bash
curl -X POST http://localhost:8080/api/ \
  -F "token=YOUR_API_TOKEN" \
  -F "content=record" \
  -F "format=json" \
  -F "type=flat" \
  -F "records[0]=101" \
  -F "records[1]=102" \
  -F "dateRangeBegin=2026-01-01 00:00:00"
```

**参数说明：**

| 参数 | 必填 | 说明 | 示例 |
|------|-----|------|------|
| `token` | ✅ | API Token | "ABC123..." |
| `content` | ✅ | 固定值 | "record" |
| `format` | ✅ | 返回格式 | "json" |
| `type` | ✅ | 数据结构 | "flat" |
| `records` | ❌ | 指定记录ID | ["101", "102"] |
| `fields` | ❌ | 指定字段 | ["age", "gender"] |
| `dateRangeBegin` | ❌ | 时间过滤（增量同步关键） | "2026-01-01 00:00:00" |
| `dateRangeEnd` | ❌ | 结束时间 | "2026-01-31 23:59:59" |

**响应示例：**

```json
[
  {
    "record_id": "101",
    "redcap_event_name": "baseline_arm_1",
    "first_name": "张",
    "last_name": "三",
    "age": "30",
    "gender": "1",
    "demographics_complete": "2"
  }
]
```

#### API方法2：导出元数据 (exportMetadata)

**用途：** 获取字段定义、表单结构

**请求示例：**

```bash
curl -X POST http://localhost:8080/api/ \
  -F "token=YOUR_API_TOKEN" \
  -F "content=metadata" \
  -F "format=json"
```

**响应示例：**

```json
[
  {
    "field_name": "age",
    "form_name": "demographics",
    "section_header": "",
    "field_type": "text",
    "field_label": "Age",
    "select_choices_or_calculations": "",
    "field_note": "",
    "text_validation_type_or_show_slider_number": "integer",
    "text_validation_min": "0",
    "text_validation_max": "120",
    "identifier": "",
    "branching_logic": "",
    "required_field": "y",
    "custom_alignment": "",
    "question_number": "",
    "matrix_group_name": "",
    "matrix_ranking": "",
    "field_annotation": ""
  }
]
```

#### API方法3：导入记录 (importRecords) - Phase 2

**用途：** 回写数据（如质控意见、AI建议）

**请求示例：**

```bash
curl -X POST http://localhost:8080/api/ \
  -F "token=YOUR_API_TOKEN" \
  -F "content=record" \
  -F "format=json" \
  -F "type=flat" \
  -F "overwriteBehavior=normal" \
  -F 'data=[{"record_id":"101","ai_review":"数据异常"}]'
```

---

### 3. Node.js实现代码

#### 3.1 RedcapAdapter（API适配器）

**文件：** `backend/src/modules/iit-manager/adapters/RedcapAdapter.ts`

```typescript
import axios from 'axios';
import FormData from 'form-data';
import { logger } from '@/common/logging';

export interface RedcapExportOptions {
  records?: string[];
  fields?: string[];
  dateRangeBegin?: Date;
  dateRangeEnd?: Date;
}

export class RedcapAdapter {
  private baseUrl: string;
  private apiToken: string;
  private timeout: number;

  constructor(baseUrl: string, apiToken: string, timeout = 30000) {
    this.baseUrl = baseUrl.replace(/\/$/, ''); // 移除末尾斜杠
    this.apiToken = apiToken;
    this.timeout = timeout;
  }

  /**
   * 导出记录（支持增量同步）
   */
  async exportRecords(options: RedcapExportOptions = {}): Promise<any[]> {
    const formData = new FormData();
    formData.append('token', this.apiToken);
    formData.append('content', 'record');
    formData.append('format', 'json');
    formData.append('type', 'flat');

    // 指定记录ID
    if (options.records && options.records.length > 0) {
      options.records.forEach((recordId, index) => {
        formData.append(`records[${index}]`, recordId);
      });
    }

    // 指定字段
    if (options.fields && options.fields.length > 0) {
      options.fields.forEach((field, index) => {
        formData.append(`fields[${index}]`, field);
      });
    }

    // 时间过滤（增量同步关键）
    if (options.dateRangeBegin) {
      const dateStr = this.formatRedcapDate(options.dateRangeBegin);
      formData.append('dateRangeBegin', dateStr);
    }

    if (options.dateRangeEnd) {
      const dateStr = this.formatRedcapDate(options.dateRangeEnd);
      formData.append('dateRangeEnd', dateStr);
    }

    try {
      const response = await axios.post(
        `${this.baseUrl}/api/`,
        formData,
        {
          headers: formData.getHeaders(),
          timeout: this.timeout
        }
      );

      if (!Array.isArray(response.data)) {
        throw new Error('Invalid response format');
      }

      logger.info(`REDCap API: Exported ${response.data.length} records`);
      return response.data;

    } catch (error) {
      logger.error('REDCap API exportRecords failed:', error);
      throw new Error(`REDCap API error: ${error.message}`);
    }
  }

  /**
   * 导出元数据（字段定义）
   */
  async exportMetadata(): Promise<any[]> {
    const formData = new FormData();
    formData.append('token', this.apiToken);
    formData.append('content', 'metadata');
    formData.append('format', 'json');

    try {
      const response = await axios.post(
        `${this.baseUrl}/api/`,
        formData,
        {
          headers: formData.getHeaders(),
          timeout: this.timeout
        }
      );

      logger.info(`REDCap API: Exported ${response.data.length} metadata fields`);
      return response.data;

    } catch (error) {
      logger.error('REDCap API exportMetadata failed:', error);
      throw new Error(`REDCap API error: ${error.message}`);
    }
  }

  /**
   * 导入记录（回写数据）- Phase 2
   */
  async importRecords(records: any[]): Promise<void> {
    const formData = new FormData();
    formData.append('token', this.apiToken);
    formData.append('content', 'record');
    formData.append('format', 'json');
    formData.append('type', 'flat');
    formData.append('overwriteBehavior', 'normal');
    formData.append('data', JSON.stringify(records));

    try {
      await axios.post(
        `${this.baseUrl}/api/`,
        formData,
        {
          headers: formData.getHeaders(),
          timeout: this.timeout
        }
      );

      logger.info(`REDCap API: Imported ${records.length} records`);

    } catch (error) {
      logger.error('REDCap API importRecords failed:', error);
      throw new Error(`REDCap API error: ${error.message}`);
    }
  }

  /**
   * 格式化日期为REDCap格式：YYYY-MM-DD HH:MM:SS
   */
  private formatRedcapDate(date: Date): string {
    return date
      .toISOString()
      .replace('T', ' ')
      .substring(0, 19);
  }
}
```

#### 3.2 WebhookController（Webhook接收器）

**文件：** `backend/src/modules/iit-manager/controllers/webhookController.ts`

```typescript
import { FastifyRequest, FastifyReply } from 'fastify';
import { prisma } from '@/config/database';
import { logger } from '@/common/logging';
import { jobQueue } from '@/common/jobs';
import { RedcapAdapter } from '../adapters/RedcapAdapter';

export class WebhookController {
  /**
   * 接收REDCap Data Entry Trigger Webhook
   * 
   * 性能要求：响应时间 < 100ms（不阻塞REDCap）
   */
  async handleRedcapWebhook(
    request: FastifyRequest,
    reply: FastifyReply
  ): Promise<void> {
    const startTime = Date.now();

    // 解析Webhook Payload
    const payload = request.body as Record<string, any>;
    const {
      project_id,
      record,
      instrument,
      redcap_event_name,
      redcap_url
    } = payload;

    // 基本验证
    if (!project_id || !record) {
      reply.code(400).send({
        error: 'Missing required fields: project_id, record'
      });
      return;
    }

    logger.info('REDCap DET webhook received:', {
      project_id,
      record,
      instrument,
      event: redcap_event_name
    });

    // 立即返回200（不阻塞REDCap）
    const responseTime = Date.now() - startTime;
    reply.code(200).send({
      status: 'received',
      timestamp: new Date().toISOString(),
      response_time_ms: responseTime
    });

    // 异步处理（不阻塞HTTP响应）
    setImmediate(async () => {
      try {
        await this.processWebhook({
          project_id,
          record,
          instrument,
          redcap_event_name,
          redcap_url
        });
      } catch (error) {
        logger.error('Webhook processing failed:', error);
        // 不抛出错误，因为已经返回200了
      }
    });
  }

  /**
   * 异步处理Webhook
   */
  private async processWebhook(payload: {
    project_id: string;
    record: string;
    instrument: string;
    redcap_event_name?: string;
    redcap_url?: string;
  }): Promise<void> {
    const { project_id, record, instrument } = payload;

    // 1. 查找项目配置
    const project = await prisma.iitProject.findFirst({
      where: { redcapProjectId: project_id }
    });

    if (!project) {
      logger.warn(`Unknown REDCap project_id: ${project_id}`);
      return;
    }

    // 2. 幂等性检查（防止重复处理）
    const isDuplicate = await this.checkDuplicate(
      project.id,
      record,
      instrument
    );

    if (isDuplicate) {
      logger.info(`Duplicate webhook ignored: ${record}`);
      return;
    }

    // 3. 调用REDCap API拉取完整数据
    const adapter = new RedcapAdapter(
      project.redcapBaseUrl,
      project.redcapApiToken
    );

    const records = await adapter.exportRecords({
      records: [record]  // 只拉取这一条记录
    });

    if (records.length === 0) {
      logger.warn(`No data found for record: ${record}`);
      return;
    }

    // 4. 推送到质控队列
    await jobQueue.send('iit:quality-check', {
      projectId: project.id,
      record: records[0],
      trigger: 'webhook',
      instrument,
      timestamp: new Date().toISOString()
    });

    logger.info(`Webhook processed successfully: project=${project_id}, record=${record}`);

    // 5. 记录审计日志
    await prisma.iitAuditLog.create({
      data: {
        projectId: project.id,
        action: 'WEBHOOK_RECEIVED',
        targetType: 'RECORD',
        targetId: record,
        details: {
          instrument,
          trigger: 'redcap_det'
        }
      }
    });
  }

  /**
   * 幂等性检查（防止5分钟内重复处理相同记录）
   */
  private async checkDuplicate(
    projectId: string,
    recordId: string,
    instrument: string
  ): Promise<boolean> {
    const fiveMinutesAgo = new Date(Date.now() - 5 * 60 * 1000);

    const recentLog = await prisma.iitAuditLog.findFirst({
      where: {
        projectId,
        action: 'WEBHOOK_RECEIVED',
        targetId: recordId,
        createdAt: { gte: fiveMinutesAgo },
        details: {
          path: ['instrument'],
          equals: instrument
        }
      }
    });

    return recentLog !== null;
  }
}
```

#### 3.3 SyncManager（轮询补充）

**文件：** `backend/src/modules/iit-manager/services/SyncManager.ts`

```typescript
import { prisma } from '@/config/database';
import { logger } from '@/common/logging';
import { jobQueue } from '@/common/jobs';
import { RedcapAdapter } from '../adapters/RedcapAdapter';

export class SyncManager {
  /**
   * 初始化同步（注册定时任务）
   */
  async initializeSync(projectId: string, interval: string = '*/30 * * * *'): Promise<void> {
    // 注册定时任务（每30分钟）
    await jobQueue.schedule(
      'iit:redcap:poll',
      interval,
      { projectId }
    );

    logger.info(`Polling sync initialized for project ${projectId}, interval: ${interval}`);
  }

  /**
   * 处理轮询（拉取增量数据）
   */
  async handlePoll(projectId: string): Promise<void> {
    logger.info(`Starting poll sync for project ${projectId}`);

    try {
      // 1. 获取项目配置
      const project = await prisma.iitProject.findUnique({
        where: { id: projectId }
      });

      if (!project) {
        throw new Error(`Project not found: ${projectId}`);
      }

      // 2. 获取上次同步时间
      const lastSyncAt = project.lastSyncAt || new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);

      logger.info(`Last sync: ${lastSyncAt.toISOString()}`);

      // 3. 拉取增量数据
      const adapter = new RedcapAdapter(
        project.redcapBaseUrl,
        project.redcapApiToken
      );

      const records = await adapter.exportRecords({
        dateRangeBegin: lastSyncAt
      });

      logger.info(`Pulled ${records.length} records from REDCap`);

      // 4. 推送到质控队列
      for (const record of records) {
        await jobQueue.send('iit:quality-check', {
          projectId,
          record,
          trigger: 'polling',
          timestamp: new Date().toISOString()
        });
      }

      // 5. 更新同步时间
      await prisma.iitProject.update({
        where: { id: projectId },
        data: { lastSyncAt: new Date() }
      });

      logger.info(`Poll sync completed for project ${projectId}`);

    } catch (error) {
      logger.error(`Poll sync failed for project ${projectId}:`, error);
      throw error;
    }
  }

  /**
   * 停止同步（取消定时任务）
   */
  async stopSync(projectId: string): Promise<void> {
    // pg-boss不支持直接取消schedule，需要在Worker中检查项目状态
    logger.info(`Sync stopped for project ${projectId}`);
  }
}
```

#### 3.4 路由配置

**文件：** `backend/src/modules/iit-manager/routes/index.ts`

```typescript
import { FastifyInstance } from 'fastify';
import { WebhookController } from '../controllers/webhookController';
import { SyncManager } from '../services/SyncManager';

export async function iitManagerRoutes(fastify: FastifyInstance) {
  const webhookController = new WebhookController();
  const syncManager = new SyncManager();

  // Webhook端点（接收REDCap DET）
  fastify.post('/webhooks/redcap', async (request, reply) => {
    return webhookController.handleRedcapWebhook(request, reply);
  });

  // 手动触发同步（测试用）
  fastify.post('/projects/:id/sync', async (request, reply) => {
    const { id } = request.params as { id: string };
    await syncManager.handlePoll(id);
    return { status: 'synced' };
  });
}
```

#### 3.5 Worker注册

**文件：** `backend/src/modules/iit-manager/index.ts`

```typescript
import { jobQueue } from '@/common/jobs';
import { SyncManager } from './services/SyncManager';
import { logger } from '@/common/logging';

export async function initializeIITManager() {
  const syncManager = new SyncManager();

  // 注册轮询Worker
  await jobQueue.work('iit:redcap:poll', async (job) => {
    const { projectId } = job.data;
    await syncManager.handlePoll(projectId);
  });

  logger.info('IIT Manager initialized: Poll worker registered');
}
```

---

## 🧪 测试验证

### 测试1：验证DET配置

**步骤：**
1. 配置ngrok：`ngrok http 3001`
2. 将ngrok URL配置到REDCap DET
3. 在REDCap中保存一条记录
4. 检查ngrok控制台是否收到POST请求

**预期结果：**
- ✅ ngrok收到POST请求
- ✅ Payload包含project_id、record等字段

### 测试2：验证API Token

**测试脚本：** `test-redcap-api.ts`

```typescript
import { RedcapAdapter } from './adapters/RedcapAdapter';

async function testRedcapAPI() {
  const adapter = new RedcapAdapter(
    'http://localhost:8080',
    process.env.REDCAP_API_TOKEN_TEST!
  );

  // 测试导出记录
  const records = await adapter.exportRecords();
  console.log('Records:', records);

  // 测试导出元数据
  const metadata = await adapter.exportMetadata();
  console.log('Metadata fields:', metadata.length);

  console.log('✅ REDCap API test passed!');
}

testRedcapAPI();
```

### 测试3：端到端集成测试

**测试脚本：** `test-redcap-integration.ts`

```typescript
async function testIntegration() {
  // 1. 创建测试项目
  const project = await prisma.iitProject.create({
    data: {
      name: 'test0102',
      redcapBaseUrl: 'http://localhost:8080',
      redcapApiToken: process.env.REDCAP_API_TOKEN_TEST!,
      redcapProjectId: '16',
      status: 'ACTIVE'
    }
  });

  // 2. 初始化同步
  const syncManager = new SyncManager();
  await syncManager.initializeSync(project.id);

  // 3. 手动触发一次轮询
  await syncManager.handlePoll(project.id);

  // 4. 模拟Webhook
  const webhookController = new WebhookController();
  await webhookController.handleRedcapWebhook(
    {
      body: {
        project_id: '16',
        record: '101',
        instrument: 'demographics'
      }
    } as any,
    {} as any
  );

  console.log('✅ Integration test passed!');
}
```

---

## 📋 Day 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是否可用

### 阶段2：开发RedcapAdapter（1.5小时）

- [ ] 创建文件：`adapters/RedcapAdapter.ts`
- [ ] 实现 `exportRecords()` 方法
- [ ] 实现 `exportMetadata()` 方法
- [ ] 实现 `formatRedcapDate()` 工具方法
- [ ] 编写单元测试：`RedcapAdapter.test.ts`

### 阶段3：开发WebhookController（2小时）

- [ ] 创建文件：`controllers/webhookController.ts`
- [ ] 实现 `handleRedcapWebhook()` 方法
- [ ] 实现 `processWebhook()` 私有方法
- [ ] 实现 `checkDuplicate()` 幂等性检查
- [ ] 配置路由：`POST /api/v1/iit/webhooks/redcap`

### 阶段4：开发SyncManager（1.5小时）

- [ ] 创建文件：`services/SyncManager.ts`
- [ ] 实现 `initializeSync()` 方法
- [ ] 实现 `handlePoll()` 方法
- [ ] 实现 `stopSync()` 方法
- [ ] 注册Worker：`iit:redcap:poll`

### 阶段5：集成测试（1小时）

- [ ] 配置ngrok/RequestBin测试DET
- [ ] 运行 `test-redcap-api.ts`
- [ ] 运行 `test-redcap-integration.ts`
- [ ] 验证端到端流程
- [ ] 记录测试结果

### 阶段6：文档更新（30分钟）

- [ ] 更新MVP开发任务清单（Day 2完成）
- [ ] 记录API Token和配置信息
- [ ] 更新架构图
- [ ] 提交Git

---

## ⚠️ 关键注意事项

### 1. DET配置要点

**常见错误：**
- ❌ 忘记在Control Center启用DET全局开关
- ❌ Webhook URL填写错误（多了斜杠、少了路径）
- ❌ 本地开发环境无法接收外网Webhook

**解决方案：**
- ✅ 使用ngrok创建临时公网URL测试
- ✅ 开发环境可先用RequestBin验证Payload格式
- ✅ 生产环境确保URL可访问（防火墙、HTTPS）

### 2. API Token安全

**安全实践：**
- ✅ 存储在环境变量或数据库加密字段
- ✅ 定期轮换Token
- ✅ 最小权限原则（只开启需要的权限）
- ❌ 不要提交到Git
- ❌ 不要在日志中打印完整Token

### 3. 性能优化

**Webhook响应时间：**
- ✅ 必须 < 100ms（立即返回200）
- ✅ 使用 `setImmediate()` 异步处理
- ❌ 不要在Webhook中执行耗时操作

**API调用频率：**
- ✅ 增量拉取（使用dateRangeBegin）
- ✅ 指定字段（减少数据量）
- ✅ 合理设置timeout（30秒）

### 4. 错误处理

**DET Webhook失败：**
- REDCap会重试3次（间隔1分钟）
- 如果仍失败，REDCap会记录到日志
- 我们的轮询机制可以补充遗漏的数据

**API调用失败：**
- 实现重试机制（3次，指数退避）
- 记录失败日志
- 告警通知管理员

---

## 📊 成功验收标准

### Day 2完成标准

- [ ] ✅ REDCap API Token已生成并验证
- [ ] ✅ RedcapAdapter可以拉取测试数据
- [ ] ✅ DET已配置并成功接收Webhook
- [ ] ✅ Webhook可以触发API拉取
- [ ] ✅ 轮询机制可以定时运行
- [ ] ✅ 数据推送到质控队列
- [ ] ✅ 单元测试全部通过
- [ ] ✅ 端到端集成测试通过

### 性能指标

- [ ] Webhook响应时间 < 100ms
- [ ] API调用成功率 > 99%
- [ ] 端到端延迟 < 5秒（DET触发 → 企微通知）

---

## 🔗 相关文档

- **MVP开发任务清单：** `MVP开发任务清单.md`
- **完整技术方案：** `IIT Manager Agent 完整技术开发方案 (V1.1).md`
- **REDCap二次开发指南：** `../../Redcap/03-API对接与开发/33-REDCap二次开发深度指南.md`
- **REDCap部署手册：** `../../Redcap/01-部署与配置/10-REDCap_Docker部署操作手册.md`

---

## 📝 更新日志

| 日期 | 版本 | 更新内容 | 更新人 |
|------|------|---------|--------|
| 2026-01-02 | V1.0 | 初始版本，完成技术调研和方案设计 | AI Assistant |

---

**这是IIT Manager Agent的技术基石文档，请妥善保管！** ⭐⭐⭐⭐⭐