AIclinicalresearch/docs/03-业务模块/Redcap/00-模块概览/02-REDCap对接总体方案.md

# REDCap与AIclinicalresearch平台对接总体方案

> **文档版本：** v1.0  
> **创建日期：** 2025-12-30  
> **最后更新：** 2025-12-30  
> **文档状态：** 规划中  
> **作者：** 技术架构师

---

## 📋 文档说明

本文档定义REDCap（15.8.0）与壹证循AI科研平台的**完整对接方案**，包括：
1. 对接架构设计
2. External Module开发方案
3. API集成方案
4. 数据流设计
5. 开发计划与实施步骤

**前置条件：**
- ✅ 已获得REDCap官方授权
- ✅ 拥有REDCap 15.8.0源代码
- ✅ 拥有External Module Framework文档

**相关文档：**
- [REDCap 二次开发深度指南](./REDCap%20二次开发深度指南.md)
- [系统架构分层设计](../../00-系统总体设计/01-系统架构分层设计.md)

---

## 🎯 对接目标与价值

### 核心目标

**将REDCap的强大EDC能力与AI科研平台的AI增值功能深度融合**

```
REDCap (数据采集)  +  AIclinicalresearch (AI能力)
    ↓                           ↓
临床数据录入              AI智能处理、分析、洞察
    ↓                           ↓
        完整的AI驱动临床研究闭环
```

### 业务价值

| 功能模块 | REDCap基础能力 | AI平台增值能力 | 协同价值 |
|---------|--------------|--------------|---------|
| **数据采集** | ✅ 表单设计、数据录入、验证 | 🎁 AI辅助录入、智能质控 | 提升录入效率50% |
| **数据清洗** | ⚠️ 手动查询、导出Excel | 🎁 DC模块自动清洗、NER提取 | 减少数据处理时间80% |
| **统计分析** | ⚠️ 需导出到R/SPSS | 🎁 SSA模块一键分析、可视化 | 降低统计门槛，分析速度提升10倍 |
| **文献支持** | ❌ 无 | 🎁 ASL模块智能文献筛选 | 系统评价效率提升5倍 |
| **AI问答** | ❌ 无 | 🎁 AIA模块10+智能体辅助 | 全流程AI辅助 |
| **知识库** | ❌ 无 | 🎁 PKB模块RAG问答 | 项目知识沉淀 |

---

## 🏗️ 对接架构设计

### 整体架构

```
┌─────────────────────────────────────────────────────────────────┐
│                   用户层（研究人员/医生）                           │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                      前端展示层                                   │
│  ┌────────────────┐              ┌─────────────────────────┐   │
│  │  REDCap Web UI │              │ AIclinicalresearch      │   │
│  │  (原生界面)     │◄────────────►│ Frontend (React)        │   │
│  └────────────────┘              └─────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                     集成层（核心）                                 │
│  ┌────────────────────────────────────────────────────────┐    │
│  │  REDCap External Module: "AI Research Assistant"       │    │
│  │  ─────────────────────────────────────────────────────  │    │
│  │  ├── 数据同步服务 (Data Sync Service)                   │    │
│  │  ├── AI功能菜单 (AI Menu Links)                        │    │
│  │  ├── Hooks处理器 (Hook Handlers)                       │    │
│  │  └── API代理层 (API Proxy)                             │    │
│  └────────────────────────────────────────────────────────┘    │
│                              ↕                                  │
│  ┌────────────────────────────────────────────────────────┐    │
│  │  AIclinicalresearch Backend RESTful API                │    │
│  │  /api/v1/redcap/*                                       │    │
│  └────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                  业务处理层（AI能力）                              │
│  ┌──────┐  ┌──────┐  ┌──────┐  ┌──────┐  ┌──────┐            │
│  │ DC   │  │ SSA  │  │ ASL  │  │ AIA  │  │ PKB  │  ...       │
│  │数据  │  │统计  │  │文献  │  │问答  │  │知识库│            │
│  │清洗  │  │分析  │  │筛选  │  │      │  │      │            │
│  └──────┘  └──────┘  └──────┘  └──────┘  └──────┘            │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                    数据存储层                                     │
│  ┌──────────────────┐         ┌──────────────────┐            │
│  │  REDCap MySQL    │         │  AI Platform     │            │
│  │  (临床数据)       │◄───────►│  PostgreSQL      │            │
│  │  - 患者数据       │  同步   │  (分析结果)       │            │
│  │  - 表单元数据     │         │  - 清洗后数据     │            │
│  └──────────────────┘         └──────────────────┘            │
└─────────────────────────────────────────────────────────────────┘
```

### 核心对接模式

我们采用**双向对接**策略：

#### 模式A：REDCap → AI平台（数据推送）

```
用户在REDCap录入数据
         ↓
   redcap_save_record Hook触发
         ↓
External Module推送数据到AI平台API
         ↓
AI平台处理（清洗/分析/AI处理）
         ↓
    结果返回REDCap存储
```

#### 模式B：AI平台 → REDCap（数据拉取）

```
用户在AI平台发起分析
         ↓
AI平台调用REDCap API获取数据
         ↓
AI平台执行分析（DC/SSA/AIA等）
         ↓
结果展示在AI平台前端
         ↓
（可选）结果回写REDCap
```

---

## 🔧 技术方案详解

### 方案1：REDCap External Module开发

#### 模块命名与结构

```
模块名称: ai_research_assistant
版本: v1.0.0
完整目录: <redcap-root>/modules/ai_research_assistant_v1.0.0/

目录结构:
ai_research_assistant_v1.0.0/
├── config.json                    # 模块配置
├── AiResearchAssistantModule.php  # 主逻辑类
├── README.md                      # 说明文档
├── LICENSE                        # MIT许可
├── pages/                         # 自定义页面
│   ├── dashboard.php             # AI功能仪表盘
│   ├── data_sync.php             # 数据同步管理
│   ├── analysis_center.php       # 分析中心
│   └── settings.php              # 模块设置
├── js/                           # JavaScript文件
│   ├── dashboard.js
│   └── data_sync.js
├── css/                          # 样式文件
│   └── style.css
└── services/                     # 服务类
    ├── ApiClient.php             # AI平台API客户端
    ├── DataMapper.php            # 数据映射转换
    └── SyncService.php           # 同步服务
```

#### config.json核心配置

```json
{
  "name": "AI Research Assistant",
  "description": "壹证循AI科研平台集成模块 - 提供数据智能清洗、统计分析、文献支持等AI增值功能",
  "authors": [
    {
      "name": "壹证循科技",
      "email": "support@yizx.ai",
      "institution": "壹证循科技"
    }
  ],
  "framework-version": 16,
  "permissions": [],
  "links": {
    "project": [
      {
        "name": "🤖 AI功能中心",
        "icon": "fas fa-brain",
        "url": "pages/dashboard.php",
        "show-header-and-footer": true
      },
      {
        "name": "🔄 数据同步",
        "icon": "fas fa-sync-alt",
        "url": "pages/data_sync.php",
        "show-header-and-footer": true
      },
      {
        "name": "📊 AI分析中心",
        "icon": "fas fa-chart-line",
        "url": "pages/analysis_center.php",
        "show-header-and-footer": true
      }
    ],
    "control-center": [
      {
        "name": "AI平台配置",
        "icon": "fas fa-cog",
        "url": "pages/settings.php"
      }
    ]
  },
  "system-settings": [
    {
      "key": "ai_platform_url",
      "name": "AI平台地址",
      "type": "text",
      "required": true,
      "default": "https://ai.yizx.com"
    },
    {
      "key": "ai_platform_api_key",
      "name": "API密钥",
      "type": "password",
      "required": true
    },
    {
      "key": "enable_auto_sync",
      "name": "启用自动同步",
      "type": "checkbox",
      "default": true
    }
  ],
  "project-settings": [
    {
      "key": "sync_mode",
      "name": "同步模式",
      "type": "dropdown",
      "choices": [
        {"value": "manual", "name": "手动同步"},
        {"value": "realtime", "name": "实时同步"},
        {"value": "scheduled", "name": "定时同步"}
      ],
      "default": "realtime"
    },
    {
      "key": "enable_dc_module",
      "name": "启用数据清洗模块",
      "type": "checkbox",
      "default": true
    },
    {
      "key": "enable_ssa_module",
      "name": "启用统计分析模块",
      "type": "checkbox",
      "default": true
    },
    {
      "key": "enable_asl_module",
      "name": "启用智能文献模块",
      "type": "checkbox",
      "default": false
    }
  ],
  "crons": [
    {
      "cron_name": "data_sync_cron",
      "cron_description": "定时同步数据到AI平台",
      "method": "syncDataToAIPlatform",
      "cron_frequency": "3600",
      "cron_max_run_time": "600"
    }
  ]
}
```

#### 主逻辑类（AiResearchAssistantModule.php）

```php
<?php
namespace YiZhengXun\AiResearchAssistant;

use ExternalModules\AbstractExternalModule;
use REDCap;

class AiResearchAssistantModule extends AbstractExternalModule {
    
    // API客户端实例
    private $apiClient;
    
    /**
     * 构造函数 - 初始化API客户端
     */
    public function __construct() {
        parent::__construct();
        require_once __DIR__ . '/services/ApiClient.php';
        $this->apiClient = new ApiClient(
            $this->getSystemSetting('ai_platform_url'),
            $this->getSystemSetting('ai_platform_api_key')
        );
    }
    
    /**
     * Hook: 数据保存时触发
     * 核心功能：实时推送数据到AI平台
     */
    public function redcap_save_record(
        $project_id, 
        $record, 
        $instrument, 
        $event_id, 
        $group_id, 
        $survey_hash, 
        $response_id, 
        $repeat_instance
    ) {
        // 检查是否启用实时同步
        $syncMode = $this->getProjectSetting('sync_mode');
        if ($syncMode !== 'realtime') {
            return;
        }
        
        // 防止无限循环
        static $is_syncing = false;
        if ($is_syncing) return;
        $is_syncing = true;
        
        try {
            // 获取记录数据
            $data = REDCap::getData($project_id, 'array', $record);
            
            // 转换数据格式
            require_once __DIR__ . '/services/DataMapper.php';
            $mapper = new DataMapper();
            $mappedData = $mapper->redcapToAIPlatform($data, $project_id, $record);
            
            // 推送到AI平台
            $result = $this->apiClient->post('/api/v1/redcap/records', $mappedData);
            
            // 记录日志
            $this->log("数据同步成功", [
                'project_id' => $project_id,
                'record' => $record,
                'instrument' => $instrument,
                'ai_platform_response' => $result
            ]);
            
            // 如果启用了AI数据清洗，触发清洗任务
            if ($this->getProjectSetting('enable_dc_module')) {
                $this->triggerDataCleaning($project_id, $record);
            }
            
        } catch (\Exception $e) {
            // 错误处理
            $this->log("数据同步失败", [
                'project_id' => $project_id,
                'record' => $record,
                'error' => $e->getMessage()
            ]);
        }
        
        $is_syncing = false;
    }
    
    /**
     * Hook: 每个页面顶部
     * 功能：注入AI辅助录入的JavaScript
     */
    public function redcap_every_page_top($project_id) {
        // 仅在数据录入页面生效
        if (strpos(PAGE, 'DataEntry/index.php') !== false) {
            $this->injectAIAssistant();
        }
    }
    
    /**
     * Hook: 数据导出前
     * 功能：可以添加AI分析结果字段到导出
     */
    public function redcap_custom_verify_username($username) {
        // 验证逻辑
    }
    
    /**
     * Cron任务: 定时同步数据
     */
    public function syncDataToAIPlatform($cron_info) {
        $projects = $this->getEnabledProjects();
        
        foreach ($projects as $project_id) {
            try {
                // 获取项目所有数据
                $data = REDCap::getData($project_id, 'array');
                
                // 批量推送
                $result = $this->apiClient->post('/api/v1/redcap/batch-sync', [
                    'project_id' => $project_id,
                    'data' => $data,
                    'timestamp' => time()
                ]);
                
                $this->log("定时同步完成", [
                    'project_id' => $project_id,
                    'records_count' => count($data)
                ]);
                
            } catch (\Exception $e) {
                $this->log("定时同步失败", [
                    'project_id' => $project_id,
                    'error' => $e->getMessage()
                ]);
            }
        }
        
        return "同步完成";
    }
    
    /**
     * 触发AI数据清洗
     */
    private function triggerDataCleaning($project_id, $record) {
        $result = $this->apiClient->post('/api/v1/redcap/dc/clean', [
            'project_id' => $project_id,
            'record' => $record,
            'auto_mode' => true
        ]);
        
        return $result;
    }
    
    /**
     * 注入AI辅助录入JavaScript
     */
    private function injectAIAssistant() {
        ?>
        <script src="<?= $this->getUrl('js/ai_assistant.js') ?>"></script>
        <script>
            const aiConfig = {
                apiUrl: '<?= $this->getSystemSetting('ai_platform_url') ?>',
                projectId: <?= PROJECT_ID ?>,
                enableAutoComplete: true,
                enableSmartValidation: true
            };
            AiAssistant.init(aiConfig);
        </script>
        <?php
    }
    
    /**
     * 获取启用模块的项目列表
     */
    private function getEnabledProjects() {
        $sql = "SELECT project_id FROM redcap_external_modules 
                WHERE external_module_id = ? 
                AND directory_prefix = ?";
        $result = $this->query($sql, [
            $this->getModuleId(),
            $this->PREFIX
        ]);
        
        $projects = [];
        while ($row = $result->fetch_assoc()) {
            $projects[] = $row['project_id'];
        }
        
        return $projects;
    }
}
```

---

### 方案2：AI平台Backend API开发

#### 新增REDCap专用模块

```typescript
// backend/src/modules/redcap/ 目录结构
backend/src/modules/redcap/
├── controllers/
│   ├── RedcapController.ts        // 主控制器
│   ├── SyncController.ts          // 数据同步控制器
│   └── WebhookController.ts       // Webhook控制器
├── services/
│   ├── RedcapApiClient.ts         // REDCap API客户端
│   ├── DataTransformService.ts    // 数据转换服务
│   ├── SyncService.ts             // 同步服务
│   └── ProjectMappingService.ts   // 项目映射服务
├── models/
│   └── redcap.prisma              // Prisma Schema
├── routes/
│   └── redcap.routes.ts           // 路由定义
└── types/
    └── redcap.types.ts            // TypeScript类型定义
```

#### Prisma Schema设计

```prisma
// backend/prisma/schema.prisma

// REDCap Schema
datasource redcap_schema {
  provider = "postgresql"
  url      = env("DATABASE_URL")
  schemas  = ["redcap_schema"]
}

// REDCap项目映射表
model RedcapProject {
  id                String   @id @default(cuid())
  redcapProjectId   Int      @unique         // REDCap项目ID
  redcapUrl         String                   // REDCap服务器地址
  redcapApiToken    String   @db.VarChar(64) // API Token (加密存储)
  
  // 映射关系
  dcProjectId       String?  // 关联的DC项目ID
  ssaProjectId      String?  // 关联的SSA项目ID
  aslProjectId      String?  // 关联的ASL项目ID
  
  // 同步配置
  syncEnabled       Boolean  @default(true)
  syncMode          String   @default("realtime") // realtime, scheduled, manual
  lastSyncAt        DateTime?
  
  // 元数据
  projectName       String
  projectDescription String? @db.Text
  
  createdAt         DateTime @default(now())
  updatedAt         DateTime @updatedAt
  
  // 关联关系
  syncRecords       RedcapSyncRecord[]
  fieldMappings     RedcapFieldMapping[]
  
  @@map("redcap_projects")
  @@schema("redcap_schema")
}

// REDCap同步记录表
model RedcapSyncRecord {
  id              String   @id @default(cuid())
  projectId       String
  project         RedcapProject @relation(fields: [projectId], references: [id], onDelete: Cascade)
  
  recordId        String   // REDCap记录ID
  eventId         String?  // REDCap事件ID
  instrument      String?  // 表单名称
  
  // 同步状态
  status          String   // pending, syncing, success, failed
  direction       String   // redcap_to_ai, ai_to_redcap
  
  // 数据快照
  redcapData      Json     // REDCap原始数据
  aiPlatformData  Json?    // AI平台处理后数据
  
  // 错误信息
  errorMessage    String?  @db.Text
  retryCount      Int      @default(0)
  
  syncedAt        DateTime @default(now())
  
  @@map("redcap_sync_records")
  @@schema("redcap_schema")
  @@index([projectId, recordId])
  @@index([status])
}

// REDCap字段映射表
model RedcapFieldMapping {
  id              String   @id @default(cuid())
  projectId       String
  project         RedcapProject @relation(fields: [projectId], references: [id], onDelete: Cascade)
  
  // REDCap字段信息
  redcapFieldName String
  redcapFieldLabel String?
  redcapFieldType String   // text, radio, checkbox, dropdown, etc.
  
  // AI平台字段映射
  aiPlatformField String?  // 映射到AI平台的字段名
  transformRule   Json?    // 转换规则（JSON）
  
  // 映射配置
  isRequired      Boolean  @default(false)
  isIdentifier    Boolean  @default(false)  // 是否为主键字段
  
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
  
  @@map("redcap_field_mappings")
  @@schema("redcap_schema")
  @@unique([projectId, redcapFieldName])
}
```

#### REDCap API路由定义

```typescript
// backend/src/modules/redcap/routes/redcap.routes.ts

import { FastifyInstance } from 'fastify';
import { RedcapController } from '../controllers/RedcapController';
import { SyncController } from '../controllers/SyncController';
import { WebhookController } from '../controllers/WebhookController';

export async function redcapRoutes(fastify: FastifyInstance) {
  const redcapController = new RedcapController();
  const syncController = new SyncController();
  const webhookController = new WebhookController();
  
  // ========== 项目管理 ==========
  
  // 创建REDCap项目映射
  fastify.post('/api/v1/redcap/projects', 
    redcapController.createProject
  );
  
  // 获取项目列表
  fastify.get('/api/v1/redcap/projects', 
    redcapController.listProjects
  );
  
  // 获取项目详情
  fastify.get('/api/v1/redcap/projects/:id', 
    redcapController.getProject
  );
  
  // 更新项目配置
  fastify.put('/api/v1/redcap/projects/:id', 
    redcapController.updateProject
  );
  
  // 删除项目映射
  fastify.delete('/api/v1/redcap/projects/:id', 
    redcapController.deleteProject
  );
  
  // ========== 数据同步 ==========
  
  // 手动触发同步（REDCap → AI平台）
  fastify.post('/api/v1/redcap/sync/import/:projectId', 
    syncController.importFromRedcap
  );
  
  // 推送数据到REDCap（AI平台 → REDCap）
  fastify.post('/api/v1/redcap/sync/export/:projectId', 
    syncController.exportToRedcap
  );
  
  // 查询同步状态
  fastify.get('/api/v1/redcap/sync/status/:projectId', 
    syncController.getSyncStatus
  );
  
  // 查询同步历史
  fastify.get('/api/v1/redcap/sync/history/:projectId', 
    syncController.getSyncHistory
  );
  
  // ========== Webhook接收 ==========
  
  // REDCap External Module推送数据（实时同步）
  fastify.post('/api/v1/redcap/webhook/records', 
    webhookController.receiveRecordUpdate
  );
  
  // 批量同步（定时任务）
  fastify.post('/api/v1/redcap/webhook/batch-sync', 
    webhookController.receiveBatchSync
  );
  
  // ========== 字段映射管理 ==========
  
  // 获取REDCap项目元数据（字段列表）
  fastify.get('/api/v1/redcap/projects/:id/metadata', 
    redcapController.getProjectMetadata
  );
  
  // 创建/更新字段映射
  fastify.post('/api/v1/redcap/projects/:id/field-mappings', 
    redcapController.upsertFieldMappings
  );
  
  // 获取字段映射
  fastify.get('/api/v1/redcap/projects/:id/field-mappings', 
    redcapController.getFieldMappings
  );
  
  // ========== AI功能集成 ==========
  
  // 触发数据清洗（DC模块）
  fastify.post('/api/v1/redcap/dc/clean', 
    redcapController.triggerDataCleaning
  );
  
  // 触发统计分析（SSA模块）
  fastify.post('/api/v1/redcap/ssa/analyze', 
    redcapController.triggerStatisticalAnalysis
  );
  
  // 获取AI分析结果
  fastify.get('/api/v1/redcap/analysis/:recordId', 
    redcapController.getAnalysisResults
  );
}
```

#### 核心Controller实现

```typescript
// backend/src/modules/redcap/controllers/SyncController.ts

import { FastifyRequest, FastifyReply } from 'fastify';
import { prisma } from '@/config/database';
import { logger } from '@/common/logging';
import { RedcapApiClient } from '../services/RedcapApiClient';
import { DataTransformService } from '../services/DataTransformService';

export class SyncController {
  
  /**
   * 从REDCap导入数据到AI平台
   */
  async importFromRedcap(
    req: FastifyRequest<{ Params: { projectId: string } }>,
    res: FastifyReply
  ) {
    const { projectId } = req.params;
    
    try {
      // 1. 获取项目配置
      const project = await prisma.redcapProject.findUnique({
        where: { id: projectId },
        include: { fieldMappings: true }
      });
      
      if (!project) {
        return res.status(404).send({ 
          success: false, 
          error: '项目不存在' 
        });
      }
      
      // 2. 调用REDCap API获取数据
      const redcapClient = new RedcapApiClient(
        project.redcapUrl,
        project.redcapApiToken
      );
      
      const redcapData = await redcapClient.exportRecords({
        format: 'json',
        type: 'flat'
      });
      
      logger.info('从REDCap获取数据成功', { 
        projectId, 
        recordCount: redcapData.length 
      });
      
      // 3. 数据转换
      const transformer = new DataTransformService();
      const transformedData = await transformer.redcapToAIPlatform(
        redcapData,
        project.fieldMappings
      );
      
      // 4. 存储到AI平台数据库
      // 根据项目配置，推送到DC/SSA/ASL等模块
      if (project.dcProjectId) {
        await this.importToDCModule(project.dcProjectId, transformedData);
      }
      
      if (project.ssaProjectId) {
        await this.importToSSAModule(project.ssaProjectId, transformedData);
      }
      
      // 5. 记录同步历史
      await prisma.redcapSyncRecord.create({
        data: {
          projectId,
          recordId: 'batch_import',
          status: 'success',
          direction: 'redcap_to_ai',
          redcapData: redcapData as any,
          aiPlatformData: transformedData as any
        }
      });
      
      // 6. 更新同步时间
      await prisma.redcapProject.update({
        where: { id: projectId },
        data: { lastSyncAt: new Date() }
      });
      
      return res.send({
        success: true,
        message: '数据导入成功',
        data: {
          recordCount: redcapData.length,
          transformedCount: transformedData.length
        }
      });
      
    } catch (error) {
      logger.error('REDCap数据导入失败', { 
        projectId, 
        error: error.message 
      });
      
      return res.status(500).send({
        success: false,
        error: '数据导入失败',
        details: error.message
      });
    }
  }
  
  /**
   * 导入到DC模块
   */
  private async importToDCModule(dcProjectId: string, data: any[]) {
    // 调用DC模块的导入API
    // TODO: 实现DC模块集成逻辑
  }
  
  /**
   * 导入到SSA模块
   */
  private async importToSSAModule(ssaProjectId: string, data: any[]) {
    // 调用SSA模块的导入API
    // TODO: 实现SSA模块集成逻辑
  }
}
```

---

## 📊 数据流设计

### 数据流1：REDCap → AI平台（实时同步）

```
┌─────────────────────────────────────────────────────────┐
│  Step 1: 用户在REDCap录入数据                             │
│  ─────────────────────────────────────────────────────  │
│  研究人员在REDCap表单中录入患者数据                        │
│  例如：患者ID、年龄、性别、诊断、检验结果等                 │
└─────────────────────────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────────────┐
│  Step 2: REDCap触发redcap_save_record Hook              │
│  ─────────────────────────────────────────────────────  │
│  External Module捕获保存事件                              │
│  获取：project_id, record, instrument, event_id         │
└─────────────────────────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────────────┐
│  Step 3: 数据获取与映射                                   │
│  ─────────────────────────────────────────────────────  │
│  1. 调用REDCap::getData()获取完整记录                     │
│  2. DataMapper转换REDCap EAV格式→AI平台标准格式           │
│  3. 应用字段映射规则（redcap_field_mappings表）           │
└─────────────────────────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────────────┐
│  Step 4: HTTP POST推送到AI平台API                        │
│  ─────────────────────────────────────────────────────  │
│  URL: https://ai.yizx.com/api/v1/redcap/webhook/records │
│  Payload: {                                             │
│    project_id: 123,                                     │
│    record_id: "PAT001",                                 │
│    data: {...},                                         │
│    timestamp: 1735542000                                │
│  }                                                      │
└─────────────────────────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────────────┐
│  Step 5: AI平台接收并处理                                 │
│  ─────────────────────────────────────────────────────  │
│  1. WebhookController验证请求签名                         │
│  2. 存储原始数据到redcap_sync_records表                   │
│  3. 异步触发AI处理任务（DC/SSA模块）                       │
└─────────────────────────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────────────┐
│  Step 6: AI处理与结果返回                                 │
│  ─────────────────────────────────────────────────────  │
│  1. DC模块：数据清洗、NER提取、缺失值处理                  │
│  2. SSA模块：自动统计分析、生成可视化图表                  │
│  3. 结果存储到AI平台数据库                                │
│  4. （可选）回写结果到REDCap（通过API）                    │
└─────────────────────────────────────────────────────────┘
```

### 数据流2：AI平台 → REDCap（分析结果回写）

```
AI平台完成分析
     ↓
生成分析结果（JSON）
     ↓
调用REDCap API: importRecords
     ↓
REDCap存储结果到特定字段
     ↓
研究人员在REDCap中查看AI分析结果
```

---

## 🚀 开发计划与实施步骤

### Phase 1: 基础对接（Week 1-2）✅ 优先级P0

**目标**：建立REDCap与AI平台的基本连接

#### Week 1: External Module骨架

**任务清单**：
- [ ] 创建External Module目录结构
- [ ] 编写config.json配置文件
- [ ] 实现AiResearchAssistantModule.php基础类
- [ ] 实现redcap_save_record Hook（基础版）
- [ ] 开发ApiClient.php（HTTP客户端）
- [ ] 测试：REDCap保存数据→打印日志

**交付物**：
- `ai_research_assistant_v1.0.0/` 完整目录
- 可在REDCap中启用的External Module
- 基础日志记录功能

#### Week 2: AI平台API端点

**任务清单**：
- [ ] 创建redcap_schema数据库Schema
- [ ] 实现Prisma模型（RedcapProject等3个表）
- [ ] 开发WebhookController接收数据
- [ ] 实现数据转换服务DataTransformService
- [ ] 开发项目管理API（CRUD）
- [ ] 测试：REDCap推送→AI平台接收→存储

**交付物**：
- `/api/v1/redcap/*` API端点
- PostgreSQL redcap_schema创建
- Postman测试集合

---

### Phase 2: 数据同步与映射（Week 3-4）⭐ 优先级P1

**目标**：实现双向数据同步和字段智能映射

#### Week 3: 字段映射系统

**任务清单**：
- [ ] 开发字段映射管理UI（前端React）
- [ ] 实现REDCap元数据获取API
- [ ] 开发字段映射配置界面
- [ ] 实现映射规则引擎（DataMapper）
- [ ] 支持复杂转换（如：单位转换、编码映射）
- [ ] 测试：映射配置→数据转换验证

**交付物**：
- 字段映射UI页面
- 映射规则引擎
- 配置文档

#### Week 4: 双向同步

**任务清单**：
- [ ] 实现批量数据导入（REDCap → AI）
- [ ] 实现分析结果回写（AI → REDCap）
- [ ] 开发Cron定时同步任务
- [ ] 实现同步状态监控界面
- [ ] 错误处理与重试机制
- [ ] 测试：完整同步流程

**交付物**：
- 双向同步功能
- 同步监控Dashboard
- 错误处理机制

---

### Phase 3: AI功能集成（Week 5-6）🎁 优先级P1

**目标**：集成DC、SSA、AIA等AI模块

#### Week 5: DC模块集成

**任务清单**：
- [ ] REDCap数据→DC模块自动清洗
- [ ] 清洗结果→REDCap回写
- [ ] 在REDCap中展示清洗报告
- [ ] 支持手动触发清洗
- [ ] 测试：录入→清洗→查看结果

**交付物**：
- DC集成API
- REDCap清洗报告页面

#### Week 6: SSA模块集成

**任务清单**：
- [ ] REDCap数据→SSA模块自动分析
- [ ] 支持三大分析路径（队列/预测/RCT）
- [ ] 在REDCap中嵌入统计报告
- [ ] 可视化图表展示
- [ ] 测试：数据录入→自动分析→报告生成

**交付物**：
- SSA集成API
- 统计报告嵌入页面

---

### Phase 4: 高级功能（Week 7-8）🌟 优先级P2

**目标**：AI辅助录入、智能质控等增值功能

#### Week 7: AI辅助录入

**任务清单**：
- [ ] 开发智能自动完成（基于历史数据）
- [ ] 异常值预警（实时AI判断）
- [ ] 字段关联推荐（AI预测）
- [ ] 录入效率提升统计
- [ ] 测试：录入体验优化验证

**交付物**：
- AI辅助录入JS插件
- 智能质控规则引擎

#### Week 8: 综合测试与优化

**任务清单**：
- [ ] 性能测试（100万条记录同步）
- [ ] 安全测试（API认证、数据加密）
- [ ] 用户验收测试（UAT）
- [ ] 文档编写（用户手册+开发文档）
- [ ] 部署到生产环境

**交付物**：
- 性能测试报告
- 完整文档
- 生产环境部署

---

## 🔒 安全性设计

### API认证机制

```typescript
// 使用HMAC-SHA256签名验证

// REDCap External Module发送请求时
const timestamp = Date.now();
const signature = crypto
  .createHmac('sha256', apiSecret)
  .update(`${timestamp}${JSON.stringify(payload)}`)
  .digest('hex');

// Headers:
{
  'X-API-Key': apiKey,
  'X-Timestamp': timestamp,
  'X-Signature': signature
}

// AI平台验证
function verifySignature(req) {
  const { timestamp, signature } = req.headers;
  const expectedSignature = crypto
    .createHmac('sha256', apiSecret)
    .update(`${timestamp}${JSON.stringify(req.body)}`)
    .digest('hex');
  
  return signature === expectedSignature;
}
```

### 数据加密

- REDCap API Token：使用AES-256加密存储
- 传输加密：强制HTTPS
- 敏感字段：支持字段级加密（PHI数据）

### 权限控制

```typescript
// REDCap用户权限同步到AI平台
interface UserPermission {
  userId: string;
  redcapRights: {
    data_entry: boolean;
    data_export: boolean;
    data_analysis: boolean;
  };
  aiPlatformRights: {
    dc_access: boolean;
    ssa_access: boolean;
    asl_access: boolean;
  };
}
```

---

## 📚 技术栈总结

| 层级 | REDCap侧 | AI平台侧 |
|------|---------|---------|
| **编程语言** | PHP 7.4+ | TypeScript/Node.js 22 |
| **框架** | REDCap EM Framework v16 | Fastify v4 |
| **数据库** | MySQL 5.7+ | PostgreSQL 15 |
| **数据模型** | EAV模型 | 关系型+JSONB |
| **前端** | jQuery + Bootstrap 5 | React 19 + Ant Design 6 |
| **API** | REDCap RESTful API | Fastify RESTful API |
| **认证** | API Token | HMAC-SHA256签名 |
| **日志** | REDCap日志表 | Winston + SLS |
| **任务队列** | REDCap Cron | pg-boss (Postgres-Only) |

---

## 📝 下一步行动

### 立即行动（本周）

1. **确认需求**：
   - [ ] 确认优先级（DC优先？还是SSA优先？）
   - [ ] 确认部署形态（云端SaaS？还是私有化部署？）
   - [ ] 确认REDCap服务器信息（URL、版本、访问权限）

2. **环境准备**：
   - [ ] 搭建REDCap测试环境（使用Docker）
   - [ ] 创建测试项目和测试数据
   - [ ] 配置AI平台测试API

3. **启动开发**：
   - [ ] 创建External Module目录
   - [ ] 初始化Git仓库
   - [ ] 编写config.json

### 技术预研

1. **REDCap API深入测试**
2. **External Module Hook机制验证**
3. **大数据量同步性能测试**
4. **移动端（REDCap Mobile App）集成可行性**

---

## 🎯 成功标准

**MVP版本（Phase 1-2完成）**：
- ✅ REDCap数据能推送到AI平台
- ✅ AI平台能接收并存储数据
- ✅ 字段映射配置功能可用
- ✅ 基础同步监控可用

**标准版本（Phase 3完成）**：
- ✅ DC模块集成完成（自动清洗）
- ✅ SSA模块集成完成（自动分析）
- ✅ 分析结果可在REDCap中查看
- ✅ 用户体验流畅

**企业版本（Phase 4完成）**：
- ✅ AI辅助录入提升效率50%+
- ✅ 智能质控减少错误率80%+
- ✅ 支持100万+记录同步
- ✅ 安全合规（符合FDA 21 CFR Part 11）

---

**文档版本**：v1.0  
**最后更新**：2025-12-30  
**下次更新**：Phase 1启动后更新开发进度

---

**🚀 准备好开始了吗？让我们开启REDCap与AI的融合之旅！**