feat(aia): Complete AIA V2.0 with universal streaming capabilities
Major Changes: - Add StreamingService with OpenAI Compatible format - Upgrade Chat component V2 with Ant Design X integration - Implement AIA module with 12 intelligent agents - Update API routes to unified /api/v1 prefix - Update system documentation Backend (~1300 lines): - common/streaming: OpenAI Compatible adapter - modules/aia: 12 agents, conversation service, streaming integration - Update route versions (RVW, PKB to v1) Frontend (~3500 lines): - modules/aia: AgentHub + ChatWorkspace (100% prototype restoration) - shared/Chat: AIStreamChat, ThinkingBlock, useAIStream Hook - Update API endpoints to v1 Documentation: - AIA module status guide - Universal capabilities catalog - System overview updates - All module documentation sync Tested: Stream response verified, authentication working Status: AIA V2.0 core completed (85%)
This commit is contained in:
@@ -1,41 +1,41 @@
|
||||
# Day 2 - REDCap 实时集成开发完成记录
|
||||
# Day 2 - REDCap 瀹炴椂闆嗘垚寮€鍙戝畬鎴愯<EFBFBD>褰?
|
||||
|
||||
> **开发日期**: 2026-01-02
|
||||
> **开发者**: AI Assistant + 用户
|
||||
> **寮€鍙戞棩鏈?*: 2026-01-02
|
||||
> **寮€鍙戣€?*: AI Assistant + 鐢ㄦ埛
|
||||
> **鏂囨。鐗堟湰**: v1.0
|
||||
> **开发阶段**: Day 2 - REDCap对接与实时同步
|
||||
> **寮€鍙戦樁娈?*: Day 2 - REDCap瀵规帴涓庡疄鏃跺悓姝?
|
||||
|
||||
---
|
||||
|
||||
## 📋 开发概述
|
||||
## 馃搵 寮€鍙戞<E98D99>杩?
|
||||
|
||||
Day 2的核心目标是实现 **IIT Manager Agent 与 REDCap 的实时数据集成**,采用 REDCap 原生的 **Data Entry Trigger (DET)** + **REST API** 技术方案,实现零延迟的数据同步和双向通信。
|
||||
Day 2鐨勬牳蹇冪洰鏍囨槸瀹炵幇 **IIT Manager Agent 涓?REDCap 鐨勫疄鏃舵暟鎹<EFBFBD>泦鎴?*锛岄噰鐢?REDCap 鍘熺敓鐨?**Data Entry Trigger (DET)** + **REST API** 鎶€鏈<EFBFBD>柟妗堬紝瀹炵幇闆跺欢杩熺殑鏁版嵁鍚屾<EFBFBD>鍜屽弻鍚戦€氫俊銆?
|
||||
|
||||
### 核心价值
|
||||
### 鏍稿績浠峰€?
|
||||
|
||||
1. ✅ **实时性**: Webhook响应时间<10ms,数据录入后立即触发
|
||||
2. ✅ **可靠性**: DET + 定时轮询双保险机制
|
||||
3. ✅ **云原生**: 完全基于Postgres-Only架构,使用pg-boss队列
|
||||
4. ✅ **标准化**: 符合团队开发规范(队列名称、Worker注册等)
|
||||
1. 鉁?**瀹炴椂鎬?*: Webhook鍝嶅簲鏃堕棿<10ms锛屾暟鎹<E69A9F>綍鍏ュ悗绔嬪嵆瑙﹀彂
|
||||
2. 鉁?**鍙<>潬鎬?*: DET + 瀹氭椂杞<E6A482><E69D9E>鍙屼繚闄╂満鍒?
|
||||
3. 鉁?**浜戝師鐢?*: 瀹屽叏鍩轰簬Postgres-Only鏋舵瀯锛屼娇鐢╬g-boss闃熷垪
|
||||
4. 鉁?**鏍囧噯鍖?*: 绗﹀悎鍥㈤槦寮€鍙戣<E98D99>鑼冿紙闃熷垪鍚嶇О銆乄orker娉ㄥ唽绛夛級
|
||||
|
||||
---
|
||||
|
||||
## 🎯 完成的功能模块
|
||||
## 馃幆 瀹屾垚鐨勫姛鑳芥ā鍧?
|
||||
|
||||
### 1. RedcapAdapter (API适配器)
|
||||
### 1. RedcapAdapter (API閫傞厤鍣?
|
||||
|
||||
**鏂囦欢**: `backend/src/modules/iit-manager/adapters/RedcapAdapter.ts`
|
||||
|
||||
**鏍稿績鍔熻兘**:
|
||||
- ✅ `testConnection()` - 连接测试
|
||||
- ✅ `exportMetadata()` - 导出字段定义(17个字段)
|
||||
- ✅ `exportRecords()` - 导出记录(支持全量/增量/指定记录)
|
||||
- ✅ `importRecords()` - 导入记录(Phase 2预留)
|
||||
- 鉁?`testConnection()` - 杩炴帴娴嬭瘯
|
||||
- 鉁?`exportMetadata()` - 瀵煎嚭瀛楁<EFBFBD>瀹氫箟锛?7涓<37>瓧娈碉級
|
||||
- 鉁?`exportRecords()` - 瀵煎嚭璁板綍锛堟敮鎸佸叏閲?澧為噺/鎸囧畾璁板綍锛?
|
||||
- 鉁?`importRecords()` - 瀵煎叆璁板綍锛圥hase 2棰勭暀锛?
|
||||
|
||||
**鍏抽敭鍙傛暟**:
|
||||
- `baseUrl`: `http://localhost:8080`
|
||||
- `apiToken`: `FCB30F9CBD12EE9E8E9B3E3A0106701B`
|
||||
- `timeout`: 30秒
|
||||
- `timeout`: 30绉?
|
||||
|
||||
**瀹為檯鎬ц兘**:
|
||||
```
|
||||
@@ -46,22 +46,22 @@ Day 2的核心目标是实现 **IIT Manager Agent 与 REDCap 的实时数据集
|
||||
|
||||
---
|
||||
|
||||
### 2. WebhookController (Webhook接收器)
|
||||
### 2. WebhookController (Webhook鎺ユ敹鍣?
|
||||
|
||||
**鏂囦欢**: `backend/src/modules/iit-manager/controllers/WebhookController.ts`
|
||||
|
||||
**鏍稿績閫昏緫**:
|
||||
```typescript
|
||||
1. 立即返回200 OK(<10ms)
|
||||
1. 绔嬪嵆杩斿洖200 OK锛?10ms锛?
|
||||
2. 楠岃瘉project_id鏄<EFBFBD>惁鍦ㄩ厤缃<EFBFBD>腑
|
||||
3. 幂等性检查(防止重复处理)
|
||||
4. 记录审计日志(WEBHOOK_RECEIVED)
|
||||
5. 推送到质控队列(iit_quality_check)
|
||||
3. 骞傜瓑鎬ф<EFBFBD>鏌ワ紙闃叉<EFBFBD>閲嶅<EFBFBD>澶勭悊锛?
|
||||
4. 璁板綍瀹¤<EFBFBD>鏃ュ織锛圵EBHOOK_RECEIVED锛?
|
||||
5. 鎺ㄩ€佸埌璐ㄦ帶闃熷垪锛坕it_quality_check锛?
|
||||
```
|
||||
|
||||
**REDCap DET鏍煎紡鏀<E7B4A1>寔**:
|
||||
- ✅ 添加了 `application/x-www-form-urlencoded` 解析器
|
||||
- ✅ 支持REDCap原生POST格式
|
||||
- 鉁?娣诲姞浜?`application/x-www-form-urlencoded` 瑙f瀽鍣?
|
||||
- 鉁?鏀<>寔REDCap鍘熺敓POST鏍煎紡
|
||||
|
||||
**Webhook瀛楁<E7809B>**:
|
||||
```json
|
||||
@@ -77,19 +77,19 @@ Day 2的核心目标是实现 **IIT Manager Agent 与 REDCap 的实时数据集
|
||||
|
||||
---
|
||||
|
||||
### 3. SyncManager (轮询管理器)
|
||||
### 3. SyncManager (杞<EFBFBD><EFBFBD>绠$悊鍣?
|
||||
|
||||
**鏂囦欢**: `backend/src/modules/iit-manager/services/SyncManager.ts`
|
||||
|
||||
**鏍稿績鍔熻兘**:
|
||||
- ✅ `initScheduledJob()` - 初始化定时任务(每5分钟)
|
||||
- ✅ `handlePoll()` - 轮询所有active项目
|
||||
- ✅ `manualSync()` - 手动同步指定项目
|
||||
- ✅ `fullSync()` - 全量同步
|
||||
- 鉁?`initScheduledJob()` - 鍒濆<EFBFBD>鍖栧畾鏃朵换鍔★紙姣?鍒嗛挓锛?
|
||||
- 鉁?`handlePoll()` - 杞<EFBFBD><EFBFBD>鎵€鏈塧ctive椤圭洰
|
||||
- 鉁?`manualSync()` - 鎵嬪姩鍚屾<EFBFBD>鎸囧畾椤圭洰
|
||||
- 鉁?`fullSync()` - 鍏ㄩ噺鍚屾<EFBFBD>
|
||||
|
||||
**澧為噺鍚屾<E98D9A>绛栫暐**:
|
||||
```typescript
|
||||
// 基于lastSyncAt时间戳
|
||||
// 鍩轰簬lastSyncAt鏃堕棿鎴?
|
||||
dateRangeBegin: lastSyncAt || createdAt - 24h
|
||||
```
|
||||
|
||||
@@ -108,20 +108,20 @@ dateRangeBegin: lastSyncAt || createdAt - 24h
|
||||
|
||||
1. **iit_redcap_poll** (瀹氭椂杞<E6A482><E69D9E>)
|
||||
- 闃熷垪鍚嶇О: `iit_redcap_poll`
|
||||
- 触发频率: 每5分钟(Cron: `*/5 * * * *`)
|
||||
- 并发数: 1
|
||||
- 功能: 轮询所有active项目的增量数据
|
||||
- 瑙﹀彂棰戠巼: 姣?鍒嗛挓锛圕ron: `*/5 * * * *`锛?
|
||||
- 骞跺彂鏁? 1
|
||||
- 鍔熻兘: 杞<><E69D9E>鎵€鏈塧ctive椤圭洰鐨勫<E990A8>閲忔暟鎹?
|
||||
|
||||
2. **iit_quality_check** (璐ㄦ帶浠诲姟)
|
||||
- 闃熷垪鍚嶇О: `iit_quality_check`
|
||||
- 触发方式: Webhook/SyncManager推送
|
||||
- 功能: 质控逻辑(Phase 1.5实现)
|
||||
- 瑙﹀彂鏂瑰紡: Webhook/SyncManager鎺ㄩ€?
|
||||
- 鍔熻兘: 璐ㄦ帶閫昏緫锛圥hase 1.5瀹炵幇锛?
|
||||
|
||||
**鍏抽敭淇<E695AD><E6B787>**:
|
||||
- ❌ 初始: `await jobQueue.work('iit:redcap:poll', ...)`
|
||||
- ✅ 修复: `jobQueue.process('iit_redcap_poll', ...)`
|
||||
- ❌ 初始: 队列名称使用冒号 `iit:quality-check`
|
||||
- ✅ 修复: 使用下划线 `iit_quality_check`
|
||||
- 鉂?鍒濆<E98D92>: `await jobQueue.work('iit:redcap:poll', ...)`
|
||||
- 鉁?淇<><E6B787>: `jobQueue.process('iit_redcap_poll', ...)`
|
||||
- 鉂?鍒濆<E98D92>: 闃熷垪鍚嶇О浣跨敤鍐掑彿 `iit:quality-check`
|
||||
- 鉁?淇<><E6B787>: 浣跨敤涓嬪垝绾?`iit_quality_check`
|
||||
|
||||
---
|
||||
|
||||
@@ -131,13 +131,13 @@ dateRangeBegin: lastSyncAt || createdAt - 24h
|
||||
|
||||
**娉ㄥ唽鐨凙PI绔<49>偣**:
|
||||
|
||||
| 端点 | 方法 | 功能 | 状态 |
|
||||
| 绔<EFBFBD>偣 | 鏂规硶 | 鍔熻兘 | 鐘舵€?|
|
||||
|------|------|------|------|
|
||||
| `/api/v1/iit/health` | GET | 健康检查 | ✅ |
|
||||
| `/api/v1/iit/webhooks/redcap` | POST | DET回调接收 | ✅ |
|
||||
| `/api/v1/iit/webhooks/health` | GET | Webhook健康检查 | ✅ |
|
||||
| `/api/v1/iit/projects/:id/sync` | POST | 手动同步 | ✅ |
|
||||
| `/api/v1/iit/projects/:id/full-sync` | POST | 全量同步 | ✅ |
|
||||
| `/api/v1/iit/health` | GET | 鍋ュ悍妫€鏌?| 鉁?|
|
||||
| `/api/v1/iit/webhooks/redcap` | POST | DET鍥炶皟鎺ユ敹 | 鉁?|
|
||||
| `/api/v1/iit/webhooks/health` | GET | Webhook鍋ュ悍妫€鏌?| 鉁?|
|
||||
| `/api/v1/iit/projects/:id/sync` | POST | 鎵嬪姩鍚屾<EFBFBD> | 鉁?|
|
||||
| `/api/v1/iit/projects/:id/full-sync` | POST | 鍏ㄩ噺鍚屾<EFBFBD> | 鉁?|
|
||||
|
||||
---
|
||||
|
||||
@@ -150,7 +150,7 @@ dateRangeBegin: lastSyncAt || createdAt - 24h
|
||||
Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@/common'
|
||||
```
|
||||
|
||||
**原因**: 项目使用相对路径,而不是路径别名 `@/common`
|
||||
**鍘熷洜**: 椤圭洰浣跨敤鐩稿<EFBFBD>璺<EFBFBD>緞锛岃€屼笉鏄<EFBFBD>矾寰勫埆鍚?`@/common`
|
||||
|
||||
**瑙e喅鏂规<E98F82>**:
|
||||
```typescript
|
||||
@@ -167,7 +167,7 @@ import { jobQueue } from '../../../common/jobs/index.js';
|
||||
|
||||
---
|
||||
|
||||
### 问题2: 数据库字段名称不一致
|
||||
### 闂<EFBFBD><EFBFBD>2: 鏁版嵁搴撳瓧娈靛悕绉颁笉涓€鑷?
|
||||
|
||||
**閿欒<E996BF>淇℃伅**:
|
||||
```sql
|
||||
@@ -176,16 +176,16 @@ ERROR: column "redcapProjectId" does not exist
|
||||
|
||||
**鍘熷洜**: Prisma浣跨敤camelCase锛屼絾PostgreSQL瀹為檯浣跨敤snake_case
|
||||
|
||||
**数据库真实情况**:
|
||||
**鏁版嵁搴撶湡瀹炴儏鍐?*:
|
||||
```sql
|
||||
-- 琛ㄥ悕: iit_schema.projects (not IitProject)
|
||||
-- 字段名: redcap_project_id (not redcapProjectId)
|
||||
-- 瀛楁<EFBFBD>鍚? redcap_project_id (not redcapProjectId)
|
||||
```
|
||||
|
||||
**瑙e喅鏂规<E98F82>**:
|
||||
1. ✅ TypeScript代码中继续使用Prisma的camelCase(自动映射)
|
||||
2. ✅ 原始SQL语句改为snake_case
|
||||
3. ✅ JSON字段使用 `'{}'::jsonb` 类型转换
|
||||
1. 鉁?TypeScript浠g爜涓<EFBFBD>户缁<EFBFBD>娇鐢≒risma鐨刢amelCase锛堣嚜鍔ㄦ槧灏勶級
|
||||
2. 鉁?鍘熷<E98D98>SQL璇<4C>彞鏀逛负snake_case
|
||||
3. 鉁?JSON瀛楁<EFBFBD>浣跨敤 `'{}'::jsonb` 绫诲瀷杞<EFBFBD>崲
|
||||
|
||||
**淇<>敼鏂囦欢**:
|
||||
- 娴嬭瘯鑴氭湰涓<E6B9B0>殑SQL璇<4C>彞
|
||||
@@ -200,18 +200,18 @@ ERROR: column "redcapProjectId" does not exist
|
||||
Name can only contain alphanumeric characters, underscores, hyphens, or periods
|
||||
```
|
||||
|
||||
**原因**: 初始使用连字符 `-`,但实际测试发现不稳定
|
||||
**鍘熷洜**: 鍒濆<EFBFBD>浣跨敤杩炲瓧绗?`-`锛屼絾瀹為檯娴嬭瘯鍙戠幇涓嶇ǔ瀹?
|
||||
|
||||
**鍥㈤槦鏍囧噯**:
|
||||
```typescript
|
||||
❌ 'iit:quality-check' // 冒号
|
||||
❌ 'iit-quality-check' // 连字符(不稳定)
|
||||
✅ 'iit_quality_check' // 下划线(推荐)
|
||||
鉂?'iit:quality-check' // 鍐掑彿
|
||||
鉂?'iit-quality-check' // 杩炲瓧绗︼紙涓嶇ǔ瀹氾級
|
||||
鉁?'iit_quality_check' // 涓嬪垝绾匡紙鎺ㄨ崘锛?
|
||||
```
|
||||
|
||||
**淇<>敼**:
|
||||
- `iit:quality-check` → `iit_quality_check`
|
||||
- `iit:redcap:poll` → `iit_redcap_poll`
|
||||
- `iit:quality-check` 鈫?`iit_quality_check`
|
||||
- `iit:redcap:poll` 鈫?`iit_redcap_poll`
|
||||
|
||||
**渚濇嵁鏂囨。**: `AIclinicalresearch\docs\02-閫氱敤鑳藉姏灞俓Postgres-Only寮傛<E5AFAE>浠诲姟澶勭悊鎸囧崡.md`
|
||||
|
||||
@@ -219,20 +219,20 @@ Name can only contain alphanumeric characters, underscores, hyphens, or periods
|
||||
|
||||
### 闂<><E99782>4: Worker娉ㄥ唽鏂规硶閿欒<E996BF>
|
||||
|
||||
**错误**: 使用了 `await jobQueue.work()`
|
||||
**閿欒<EFBFBD>**: 浣跨敤浜?`await jobQueue.work()`
|
||||
|
||||
**姝g‘鏂规硶**: 浣跨敤 `jobQueue.process()`
|
||||
|
||||
**瀵规瘮**:
|
||||
```typescript
|
||||
// ❌ 错误
|
||||
// 鉂?閿欒<E996BF>
|
||||
await jobQueue.work(
|
||||
'iit_redcap_poll',
|
||||
{ teamSize: 1, teamConcurrency: 1 },
|
||||
async (job) => { ... }
|
||||
);
|
||||
|
||||
// ✅ 正确
|
||||
// 鉁?姝g‘
|
||||
jobQueue.process('iit_redcap_poll', async (job) => {
|
||||
// ...
|
||||
return { success: true };
|
||||
@@ -241,7 +241,7 @@ jobQueue.process('iit_redcap_poll', async (job) => {
|
||||
|
||||
---
|
||||
|
||||
### 问题5: REDCap DET格式不兼容
|
||||
### 闂<EFBFBD><EFBFBD>5: REDCap DET鏍煎紡涓嶅吋瀹?
|
||||
|
||||
**閿欒<E996BF>淇℃伅**:
|
||||
```
|
||||
@@ -250,7 +250,7 @@ Unsupported Media Type: application/x-www-form-urlencoded
|
||||
|
||||
**鍘熷洜**: REDCap DET鍙戦€佺殑鏄<E6AE91>〃鍗曟牸寮忥紝鑰屼笉鏄疛SON
|
||||
|
||||
**解决方案**: 添加Content-Type解析器
|
||||
**瑙e喅鏂规<EFBFBD>**: 娣诲姞Content-Type瑙f瀽鍣?
|
||||
```typescript
|
||||
fastify.addContentTypeParser(
|
||||
'application/x-www-form-urlencoded',
|
||||
@@ -274,23 +274,23 @@ fastify.addContentTypeParser(
|
||||
|
||||
### 闂<><E99782>6: Docker缃戠粶璁块棶闂<E6A3B6><E99782>
|
||||
|
||||
**问题**: REDCap容器无法通过 `localhost` 访问宿主机服务
|
||||
**闂<EFBFBD><EFBFBD>**: REDCap瀹瑰櫒鏃犳硶閫氳繃 `localhost` 璁块棶瀹夸富鏈烘湇鍔?
|
||||
|
||||
**DET URL閰嶇疆**:
|
||||
```
|
||||
❌ http://localhost:3001/api/v1/iit/webhooks/redcap
|
||||
✅ http://host.docker.internal:3001/api/v1/iit/webhooks/redcap
|
||||
鉂?http://localhost:3001/api/v1/iit/webhooks/redcap
|
||||
鉁?http://host.docker.internal:3001/api/v1/iit/webhooks/redcap
|
||||
```
|
||||
|
||||
**楠岃瘉鏂规硶**:
|
||||
```bash
|
||||
docker exec redcap-apache curl http://host.docker.internal:3001/api/v1/iit/health
|
||||
# ✅ 成功返回
|
||||
# 鉁?鎴愬姛杩斿洖
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ 测试验证
|
||||
## 鉁?娴嬭瘯楠岃瘉
|
||||
|
||||
### 1. API杩炴帴娴嬭瘯
|
||||
|
||||
@@ -298,11 +298,11 @@ docker exec redcap-apache curl http://host.docker.internal:3001/api/v1/iit/healt
|
||||
|
||||
**缁撴灉**:
|
||||
```
|
||||
✅ 连接成功
|
||||
✅ 元数据导出: 17个字段
|
||||
✅ 记录导出: 6条记录 (ID: 1,2,3,4,5,6)
|
||||
✅ 增量同步: 成功获取最近1小时数据
|
||||
✅ 指定记录: 成功导出单条记录
|
||||
鉁?杩炴帴鎴愬姛
|
||||
鉁?鍏冩暟鎹<E69A9F><E98EB9>鍑? 17涓<37>瓧娈?
|
||||
鉁?璁板綍瀵煎嚭: 6鏉¤<E98F89>褰?(ID: 1,2,3,4,5,6)
|
||||
鉁?澧為噺鍚屾<E98D9A>: 鎴愬姛鑾峰彇鏈€杩?灏忔椂鏁版嵁
|
||||
鉁?鎸囧畾璁板綍: 鎴愬姛瀵煎嚭鍗曟潯璁板綍
|
||||
```
|
||||
|
||||
---
|
||||
@@ -313,11 +313,11 @@ docker exec redcap-apache curl http://host.docker.internal:3001/api/v1/iit/healt
|
||||
|
||||
**缁撴灉**:
|
||||
```
|
||||
✅ 健康检查: ok
|
||||
✅ Webhook发送成功: 200
|
||||
✅ 响应时间: <10ms (优秀)
|
||||
✅ 幂等性检查: 通过
|
||||
✅ 无效请求拦截: 400错误
|
||||
鉁?鍋ュ悍妫€鏌? ok
|
||||
鉁?Webhook鍙戦€佹垚鍔? 200
|
||||
鉁?鍝嶅簲鏃堕棿: <10ms (浼樼<EFBFBD>)
|
||||
鉁?骞傜瓑鎬ф<E98EAC>鏌? 閫氳繃
|
||||
鉁?鏃犳晥璇锋眰鎷︽埅: 400閿欒<EFBFBD>
|
||||
```
|
||||
|
||||
---
|
||||
@@ -326,21 +326,21 @@ docker exec redcap-apache curl http://host.docker.internal:3001/api/v1/iit/healt
|
||||
|
||||
**娴嬭瘯鑴氭湰**: `test-redcap-integration.ts`
|
||||
|
||||
**结果**: **12/12 通过** ✅
|
||||
**缁撴灉**: **12/12 閫氳繃** 鉁?
|
||||
|
||||
```
|
||||
✅ 1. 后端服务运行正常
|
||||
✅ 2. 项目配置存在
|
||||
✅ 3. REDCap API连接成功
|
||||
✅ 4. 元数据获取成功
|
||||
✅ 5. 记录获取成功
|
||||
✅ 6. Webhook响应速度<100ms
|
||||
✅ 7. 异步处理等待完成
|
||||
✅ 8. 审计日志记录完整
|
||||
✅ 9. 增量同步成功
|
||||
✅ 10. 手动同步成功 ⭐
|
||||
✅ 11. Webhook健康检查
|
||||
✅ 12. 幂等性测试通过
|
||||
鉁?1. 鍚庣<EFBFBD>鏈嶅姟杩愯<EFBFBD>姝e父
|
||||
鉁?2. 椤圭洰閰嶇疆瀛樺湪
|
||||
鉁?3. REDCap API杩炴帴鎴愬姛
|
||||
鉁?4. 鍏冩暟鎹<EFBFBD>幏鍙栨垚鍔?
|
||||
鉁?5. 璁板綍鑾峰彇鎴愬姛
|
||||
鉁?6. Webhook鍝嶅簲閫熷害<100ms
|
||||
鉁?7. 寮傛<EFBFBD>澶勭悊绛夊緟瀹屾垚
|
||||
鉁?8. 瀹¤<EFBFBD>鏃ュ織璁板綍瀹屾暣
|
||||
鉁?9. 澧為噺鍚屾<EFBFBD>鎴愬姛
|
||||
鉁?10. 鎵嬪姩鍚屾<EFBFBD>鎴愬姛 猸?
|
||||
鉁?11. Webhook鍋ュ悍妫€鏌?
|
||||
鉁?12. 骞傜瓑鎬ф祴璇曢€氳繃
|
||||
```
|
||||
|
||||
---
|
||||
@@ -361,7 +361,7 @@ docker exec redcap-apache curl http://host.docker.internal:3001/api/v1/iit/healt
|
||||
WEBHOOK_RECEIVED | 6 | instrument: demographics, project_id: 16
|
||||
```
|
||||
|
||||
**验证结果**: ✅ 数据完全一致
|
||||
**楠岃瘉缁撴灉**: 鉁?鏁版嵁瀹屽叏涓€鑷?
|
||||
|
||||
---
|
||||
|
||||
@@ -369,24 +369,24 @@ docker exec redcap-apache curl http://host.docker.internal:3001/api/v1/iit/healt
|
||||
|
||||
### API鍝嶅簲鏃堕棿
|
||||
|
||||
| 操作 | 耗时 | 数据量 |
|
||||
| 鎿嶄綔 | 鑰楁椂 | 鏁版嵁閲?|
|
||||
|------|------|--------|
|
||||
| exportMetadata | 260-560ms | 17个字段 |
|
||||
| exportRecords (全量) | 450-1,400ms | 6条记录 |
|
||||
| exportMetadata | 260-560ms | 17涓<EFBFBD>瓧娈?|
|
||||
| exportRecords (鍏ㄩ噺) | 450-1,400ms | 6鏉¤<EFBFBD>褰?|
|
||||
| exportRecords (澧為噺) | 300-800ms | 鍙樺寲璁板綍 |
|
||||
| Webhook鍝嶅簲 | **<10ms** | 绔嬪嵆杩斿洖 |
|
||||
|
||||
### 实时性验证
|
||||
### 瀹炴椂鎬ч獙璇?
|
||||
|
||||
| 指标 | 目标 | 实际 | 状态 |
|
||||
| 鎸囨爣 | 鐩<>爣 | 瀹為檯 | 鐘舵€?|
|
||||
|------|------|------|------|
|
||||
| Webhook响应时间 | <100ms | **7ms** | ✅ 优秀 |
|
||||
| DET触发延迟 | 0秒 | **0秒** | ✅ 完美 |
|
||||
| 数据同步准确性 | 100% | **100%** | ✅ 完美 |
|
||||
| Webhook鍝嶅簲鏃堕棿 | <100ms | **7ms** | 鉁?浼樼<E6B5BC> |
|
||||
| DET瑙﹀彂寤惰繜 | 0绉?| **0绉?* | 鉁?瀹岀編 |
|
||||
| 鏁版嵁鍚屾<EFBFBD>鍑嗙‘鎬?| 100% | **100%** | 鉁?瀹岀編 |
|
||||
|
||||
---
|
||||
|
||||
## 🗄️ 数据库配置
|
||||
## 馃梽锔?鏁版嵁搴撻厤缃?
|
||||
|
||||
### REDCap椤圭洰閰嶇疆
|
||||
|
||||
@@ -418,7 +418,7 @@ INSERT INTO iit_schema.projects (
|
||||
|
||||
### REDCap椤圭洰淇℃伅
|
||||
|
||||
| 字段 | 值 |
|
||||
| 瀛楁<EFBFBD> | 鍊?|
|
||||
|------|-----|
|
||||
| **椤圭洰鍚嶇О** | test0102 |
|
||||
| **Project ID** | 16 (int) |
|
||||
@@ -435,8 +435,8 @@ INSERT INTO iit_schema.projects (
|
||||
- height, weight, bmi
|
||||
- comments, demographics_complete
|
||||
|
||||
**2. ddcd (自定义表单)**
|
||||
- zhiliaoshi (治疗室)
|
||||
**2. ddcd (鑷<EFBFBD>畾涔夎〃鍗?**
|
||||
- zhiliaoshi (娌荤枟瀹?
|
||||
- shifou (鏄<>惁)
|
||||
- ddcd_complete
|
||||
|
||||
@@ -480,37 +480,37 @@ INSERT INTO iit_schema.projects (
|
||||
|
||||
### 1. 鎶€鏈<E282AC>€夊瀷楠岃瘉
|
||||
|
||||
**✅ REDCap DET + REST API方案优势**:
|
||||
- 零开发成本(REDCap原生支持)
|
||||
- 零延迟(实时触发)
|
||||
**鉁?REDCap DET + REST API鏂规<EFBFBD>浼樺娍**:
|
||||
- 闆跺紑鍙戞垚鏈<EFBFBD>紙REDCap鍘熺敓鏀<EFBFBD>寔锛?
|
||||
- 闆跺欢杩燂紙瀹炴椂瑙﹀彂锛?
|
||||
- 楂樺彲闈狅紙Webhook + 杞<><E69D9E>鍙屼繚闄╋級
|
||||
- 易维护(标准HTTP接口)
|
||||
- 鏄撶淮鎶わ紙鏍囧噯HTTP鎺ュ彛锛?
|
||||
|
||||
**❌ 放弃的方案**:
|
||||
**鉂?鏀惧純鐨勬柟妗?*:
|
||||
- External Module锛堥渶瑕丳HP寮€鍙戯級
|
||||
- 纯轮询(延迟高,资源浪费)
|
||||
- 绾<EFBFBD>疆璇<EFBFBD>紙寤惰繜楂橈紝璧勬簮娴<EFBFBD>垂锛?
|
||||
|
||||
---
|
||||
|
||||
### 2. 开发规范遵循
|
||||
### 2. 寮€鍙戣<EFBFBD>鑼冮伒寰?
|
||||
|
||||
**✅ 符合团队标准**:
|
||||
- 队列名称: 使用下划线(`iit_quality_check`)
|
||||
**鉁?绗﹀悎鍥㈤槦鏍囧噯**:
|
||||
- 闃熷垪鍚嶇О: 浣跨敤涓嬪垝绾匡紙`iit_quality_check`锛?
|
||||
- Worker娉ㄥ唽: 浣跨敤 `jobQueue.process()`
|
||||
- 审计日志: 记录所有关键操作
|
||||
- 错误处理: 统一异常捕获和日志记录
|
||||
- 瀹¤<EFBFBD>鏃ュ織: 璁板綍鎵€鏈夊叧閿<E58FA7>搷浣?
|
||||
- 閿欒<EFBFBD>澶勭悊: 缁熶竴寮傚父鎹曡幏鍜屾棩蹇楄<E8B987>褰?
|
||||
|
||||
**参考文档**:
|
||||
**鍙傝€冩枃妗?*:
|
||||
- `Postgres-Only寮傛<E5AFAE>浠诲姟澶勭悊鎸囧崡.md`
|
||||
- `REDCap瀵规帴鎶€鏈<E282AC>柟妗堜笌瀹炴柦鎸囧崡.md`
|
||||
|
||||
---
|
||||
|
||||
### 3. 调试技巧
|
||||
### 3. 璋冭瘯鎶€宸?
|
||||
|
||||
**Docker瀹瑰櫒璋冭瘯**:
|
||||
```bash
|
||||
# 测试网络连通性
|
||||
# 娴嬭瘯缃戠粶杩為€氭€?
|
||||
docker exec redcap-apache curl http://host.docker.internal:3001/api/v1/iit/health
|
||||
|
||||
# 鏌ヨ<E98F8C>瀹¤<E780B9>鏃ュ織
|
||||
@@ -522,7 +522,7 @@ docker exec ai-clinical-postgres psql -U postgres -d ai_clinical_research \
|
||||
-c "SELECT name, redcap_project_id, status FROM iit_schema.projects;"
|
||||
```
|
||||
|
||||
**REDCap数据库查询**:
|
||||
**REDCap鏁版嵁搴撴煡璇?*:
|
||||
```bash
|
||||
docker exec redcap-mysql mysql -u redcap_user -predcap_pass_dev_456 redcap \
|
||||
-e "SELECT project_id, app_title FROM redcap_projects WHERE project_id = 16;"
|
||||
@@ -534,26 +534,26 @@ docker exec redcap-mysql mysql -u redcap_user -predcap_pass_dev_456 redcap \
|
||||
|
||||
| 鏂囨。鍚嶇О | 璺<>緞 | 璇存槑 |
|
||||
|---------|------|------|
|
||||
| REDCap对接技术方案 | `04-开发计划/REDCap对接技术方案与实施指南.md` | Day 2技术方案 |
|
||||
| MVP开发任务清单 | `04-开发计划/MVP开发任务清单.md` | 整体开发计划 |
|
||||
| Postgres-Only异步任务处理指南 | `docs/02-通用能力层/Postgres-Only异步任务处理指南.md` | 队列开发规范 |
|
||||
| 模块当前状态 | `00-模块当前状态与开发指南.md` | 模块整体状态 |
|
||||
| REDCap瀵规帴鎶€鏈<EFBFBD>柟妗?| `04-寮€鍙戣<E98D99>鍒?REDCap瀵规帴鎶€鏈<E282AC>柟妗堜笌瀹炴柦鎸囧崡.md` | Day 2鎶€鏈<EFBFBD>柟妗?|
|
||||
| MVP寮€鍙戜换鍔℃竻鍗?| `04-寮€鍙戣<E98D99>鍒?MVP寮€鍙戜换鍔℃竻鍗?md` | 鏁翠綋寮€鍙戣<E98D99>鍒?|
|
||||
| Postgres-Only寮傛<EFBFBD>浠诲姟澶勭悊鎸囧崡 | `docs/02-閫氱敤鑳藉姏灞?Postgres-Only寮傛<EFBFBD>浠诲姟澶勭悊鎸囧崡.md` | 闃熷垪寮€鍙戣<E98D99>鑼?|
|
||||
| 妯″潡褰撳墠鐘舵€?| `00-妯″潡褰撳墠鐘舵€佷笌寮€鍙戞寚鍗?md` | 妯″潡鏁翠綋鐘舵€?|
|
||||
|
||||
---
|
||||
|
||||
## 🚀 下一步计划
|
||||
## 馃殌 涓嬩竴姝ヨ<E5A79D>鍒?
|
||||
|
||||
### Phase 1.5 - 璐ㄦ帶閫昏緫瀹炵幇
|
||||
|
||||
**目标**: 实现AI驱动的数据质控
|
||||
**鐩<EFBFBD>爣**: 瀹炵幇AI椹卞姩鐨勬暟鎹<EFBFBD>川鎺?
|
||||
|
||||
**鏍稿績鍔熻兘**:
|
||||
1. 瀹炵幇 `iit_quality_check` Worker鐨勮川鎺ч€昏緫
|
||||
2. 调用Dify工作流进行数据验证
|
||||
3. 生成质控建议(shadow state)
|
||||
4. 返回结果给研究者
|
||||
2. 璋冪敤Dify宸ヤ綔娴佽繘琛屾暟鎹<EFBFBD>獙璇?
|
||||
3. 鐢熸垚璐ㄦ帶寤鸿<EFBFBD>锛坰hadow state锛?
|
||||
4. 杩斿洖缁撴灉缁欑爺绌惰€?
|
||||
|
||||
**预估工作量**: 1-2天
|
||||
**棰勪及宸ヤ綔閲?*: 1-2澶?
|
||||
|
||||
---
|
||||
|
||||
@@ -565,26 +565,26 @@ docker exec redcap-mysql mysql -u redcap_user -predcap_pass_dev_456 redcap \
|
||||
1. 瀹屽杽 `importRecords()` API
|
||||
2. 瀹炵幇shadow state瀹℃壒娴佺▼
|
||||
3. 缁忕爺绌惰€呯‘璁ゅ悗鍚屾<E98D9A>鍒癛EDCap
|
||||
4. 处理冲突和版本控制
|
||||
4. 澶勭悊鍐茬獊鍜岀増鏈<EFBFBD>帶鍒?
|
||||
|
||||
**预估工作量**: 2-3天
|
||||
**棰勪及宸ヤ綔閲?*: 2-3澶?
|
||||
|
||||
---
|
||||
|
||||
## ✅ 验收清单
|
||||
## 鉁?楠屾敹娓呭崟
|
||||
|
||||
- [x] RedcapAdapter API适配器完成
|
||||
- [x] WebhookController Webhook接收器完成
|
||||
- [x] SyncManager 轮询管理器完成
|
||||
- [x] Worker注册和队列配置完成
|
||||
- [x] RedcapAdapter API閫傞厤鍣ㄥ畬鎴?
|
||||
- [x] WebhookController Webhook鎺ユ敹鍣ㄥ畬鎴?
|
||||
- [x] SyncManager 杞<EFBFBD><EFBFBD>绠$悊鍣ㄥ畬鎴?
|
||||
- [x] Worker娉ㄥ唽鍜岄槦鍒楅厤缃<EFBFBD>畬鎴?
|
||||
- [x] 璺<>敱閰嶇疆鍜孋ontent-Type瑙f瀽瀹屾垚
|
||||
- [x] 单元测试脚本通过(test-redcap-api.ts)
|
||||
- [x] Webhook测试通过(test-redcap-webhook.ts)
|
||||
- [x] 集成测试通过(test-redcap-integration.ts,12/12)
|
||||
- [x] 真实场景测试通过(新增+编辑记录)
|
||||
- [x] 鍗曞厓娴嬭瘯鑴氭湰閫氳繃锛坱est-redcap-api.ts锛?
|
||||
- [x] Webhook娴嬭瘯閫氳繃锛坱est-redcap-webhook.ts锛?
|
||||
- [x] 闆嗘垚娴嬭瘯閫氳繃锛坱est-redcap-integration.ts锛?2/12锛?
|
||||
- [x] 鐪熷疄鍦烘櫙娴嬭瘯閫氳繃锛堟柊澧?缂栬緫璁板綍锛?
|
||||
- [x] 瀹¤<E780B9>鏃ュ織璁板綍瀹屾暣
|
||||
- [x] 性能指标达标(Webhook<10ms)
|
||||
- [x] 符合团队开发规范
|
||||
- [x] 鎬ц兘鎸囨爣杈炬爣锛圵ebhook<10ms锛?
|
||||
- [x] 绗﹀悎鍥㈤槦寮€鍙戣<EFBFBD>鑼?
|
||||
- [x] 鏂囨。鏇存柊瀹屾垚
|
||||
|
||||
---
|
||||
@@ -594,7 +594,7 @@ docker exec redcap-mysql mysql -u redcap_user -predcap_pass_dev_456 redcap \
|
||||
### A. 鐜<><E9909C>淇℃伅
|
||||
|
||||
```yaml
|
||||
开发环境:
|
||||
寮€鍙戠幆澧?
|
||||
- OS: Windows 11
|
||||
- Node.js: v22.18.0
|
||||
- PostgreSQL: 16.1 (Docker)
|
||||
@@ -604,8 +604,8 @@ docker exec redcap-mysql mysql -u redcap_user -predcap_pass_dev_456 redcap \
|
||||
|
||||
Docker瀹瑰櫒:
|
||||
- redcap-apache: REDCap搴旂敤
|
||||
- redcap-mysql: REDCap数据库
|
||||
- ai-clinical-postgres: IIT数据库
|
||||
- redcap-mysql: REDCap鏁版嵁搴?
|
||||
- ai-clinical-postgres: IIT鏁版嵁搴?
|
||||
```
|
||||
|
||||
### B. 鍏抽敭浠g爜鏂囦欢娓呭崟
|
||||
@@ -613,26 +613,27 @@ Docker容器:
|
||||
```
|
||||
backend/src/modules/iit-manager/
|
||||
鈹溾攢鈹€ adapters/
|
||||
│ └── RedcapAdapter.ts (271行)
|
||||
鈹? 鈹斺攢鈹€ RedcapAdapter.ts (271琛?
|
||||
鈹溾攢鈹€ controllers/
|
||||
│ └── WebhookController.ts (327行)
|
||||
鈹? 鈹斺攢鈹€ WebhookController.ts (327琛?
|
||||
鈹溾攢鈹€ services/
|
||||
│ └── SyncManager.ts (398行)
|
||||
鈹? 鈹斺攢鈹€ SyncManager.ts (398琛?
|
||||
鈹溾攢鈹€ routes/
|
||||
│ └── index.ts (203行)
|
||||
├── index.ts (91行)
|
||||
├── test-redcap-api.ts (189行)
|
||||
├── test-redcap-webhook.ts (274行)
|
||||
└── test-redcap-integration.ts (449行)
|
||||
鈹? 鈹斺攢鈹€ index.ts (203琛?
|
||||
鈹溾攢鈹€ index.ts (91琛?
|
||||
鈹溾攢鈹€ test-redcap-api.ts (189琛?
|
||||
鈹溾攢鈹€ test-redcap-webhook.ts (274琛?
|
||||
鈹斺攢鈹€ test-redcap-integration.ts (449琛?
|
||||
```
|
||||
|
||||
**总代码量**: ~2,200行
|
||||
**鎬讳唬鐮侀噺**: ~2,200琛?
|
||||
|
||||
---
|
||||
|
||||
**文档维护者**: 开发团队
|
||||
**最后更新**: 2026-01-02
|
||||
**状态**: ✅ Day 2 开发完成
|
||||
**鏂囨。缁存姢鑰?*: 寮€鍙戝洟闃?
|
||||
**鏈€鍚庢洿鏂?*: 2026-01-02
|
||||
**鐘舵€?*: 鉁?Day 2 寮€鍙戝畬鎴?
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user