feat(admin): Add user management and upgrade to module permission system

Features - User Management (Phase 4.1): - Database: Add user_modules table for fine-grained module permissions - Database: Add 4 user permissions (view/create/edit/delete) to role_permissions - Backend: UserService (780 lines) - CRUD with tenant isolation - Backend: UserController + UserRoutes (648 lines) - 13 API endpoints - Backend: Batch import users from Excel - Frontend: UserListPage (412 lines) - list/filter/search/pagination - Frontend: UserFormPage (341 lines) - create/edit with module config - Frontend: UserDetailPage (393 lines) - details/tenant/module management - Frontend: 3 modal components (592 lines) - import/assign/configure - API: GET/POST/PUT/DELETE /api/admin/users/* endpoints Architecture Upgrade - Module Permission System: - Backend: Add getUserModules() method in auth.service - Backend: Login API returns modules array in user object - Frontend: AuthContext adds hasModule() method - Frontend: Navigation filters modules based on user.modules - Frontend: RouteGuard checks requiredModule instead of requiredVersion - Frontend: Remove deprecated version-based permission system - UX: Only show accessible modules in navigation (clean UI) - UX: Smart redirect after login (avoid 403 for regular users) Fixes: - Fix UTF-8 encoding corruption in ~100 docs files - Fix pageSize type conversion in userService (String to Number) - Fix authUser undefined error in TopNavigation - Fix login redirect logic with role-based access check - Update Git commit guidelines v1.2 with UTF-8 safety rules Database Changes: - CREATE TABLE user_modules (user_id, tenant_id, module_code, is_enabled) - ADD UNIQUE CONSTRAINT (user_id, tenant_id, module_code) - INSERT 4 permissions + role assignments - UPDATE PUBLIC tenant with 8 module subscriptions Technical: - Backend: 5 new files (~2400 lines) - Frontend: 10 new files (~2500 lines) - Docs: 1 development record + 2 status updates + 1 guideline update - Total: ~4900 lines of code Status: User management 100% complete, module permission system operational
2026-01-16 13:42:10 +08:00
parent 98d862dbd4
commit 66255368b7
560 changed files with 70424 additions and 52353 deletions
--- a/Agent/04-开发计划/REDCap对接技术方案与实施指南.md
+++ b/Agent/04-开发计划/REDCap对接技术方案与实施指南.md
@@ -1,69 +1,69 @@
 # REDCap对接技术方案与实施指南

-**迚域悽<EFBFBD>?* V1.0  
-**蛻帛ｻｺ譌･譛滂ｼ?* 2026-01-02  
-**騾ら畑髦ｶ谿ｵ<EFBFBD>?* IIT Manager Agent MVP - Day 2  
-**譁<EFBFBD>｡｣諤ｧ雍ｨ<EFBFBD>?* 譬ｸ蠢<EFBDB8>橿譛ｯ蝓ｺ遏? 
-**驥崎ｦ∫ｨ句ｺｦ<EFBFBD>?* 箝絶ｭ絶ｭ絶ｭ絶ｭ?
+**版本：** V1.0  
+**创建日期：** 2026-01-02  
+**适用阶段：** IIT Manager Agent MVP - Day 2  
+**文档性质：** 核心技术基石  
+**重要程度：** ⭐⭐⭐⭐⭐

 ---

 ## 📋 文档目标

-譛ｬ譁<EFBFBD>｡｣譏ｯIIT Manager Agent荳山EDCap髮<EFBFBD><EFBFBD>逧?*譚<>ｨ∵橿譛ｯ謖<EFBDAF><E8AC96>?*<2A>梧<EFBFBD>遑ｮ<E98191><EFBDAE>
-1. 笨?REDCap蟇ｹ謗･譁ｹ蠑冗噪謚譛ｯ騾牙梛
-2. 笨?Data Entry Trigger (DET) 逧<EFBFBD>ｪ瑚ｯ∽ｸ朱<EFBFBD>鄂ｮ
-3. 笨?REST API逧<EFBFBD>ｽｿ逕ｨ譁ｹ豕?
-4. 笨?螳樊慮雍ｨ謗ｧ逧<EFBDA7>ｮ梧紛譫ｶ譫?
-5. 笨?Day 2逧<EFBFBD>ｼ蜿大ｮ樊命豁･鬪?
+本文档是IIT Manager Agent与REDCap集成的**权威技术指南**，明确：
+1. ✅ REDCap对接方式的技术选型
+2. ✅ Data Entry Trigger (DET) 的验证与配置
+3. ✅ REST API的使用方法
+4. ✅ 实时质控的完整架构
+5. ✅ Day 2的开发实施步骤

 ---

-## <EFBFBD>識 譬ｸ蠢<EFBDB8>ｻ楢ｮｺ<EFBDAE><EFBDBA>xecutive Summary<EFBFBD>?
+## 🎯 核心结论（Executive Summary）

-### 笨?**謚譛ｯ騾牙梛<E78999>咼ET<45>亥ｮ樊慮隗ｦ蜿托ｼ<E68998> + REST API<50>域焚謐ｮ隸ｻ蜀呻ｼ<E591BB>**
+### ✅ **技术选型：DET（实时触发） + REST API（数据读写）**

 **不采用：** External Module (EM)  
-**蜴溷屏<EFBFBD>?* EM髴隕￣HP蠑蜿代∽ｾｵ蜈･REDCap貅千<E8B285>√∫ｻｴ謚､謌先悽鬮倥∽ｸ埼ょ粋螟夜Κ邉ｻ扈滄寔謌<E5AF94>
+**原因：** EM需要PHP开发、侵入REDCap源码、维护成本高、不适合外部系统集成

-**驥<EFBFBD>畑譁ｹ譯茨ｼ?*
+**采用方案：**

-| 扈<EFBFBD>ｻｶ | 謚譛?| 逕ｨ騾?| 螳樊慮諤?|
+| 组件 | 技术 | 用途 | 实时性 |
 |------|-----|------|--------|
-| **Data Entry Trigger** | REDCap蜴溽函蜉溯<EFBFBD> | 謨ｰ謐ｮ菫晏ｭ俶慮螳樊慮騾夂衍 | 0遘貞ｻｶ霑?|
+| **Data Entry Trigger** | REDCap原生功能 | 数据保存时实时通知 | 0秒延迟 |
 | **REST API (Export)** | HTTP + JSON | 拉取数据、元数据 | 按需调用 |
-| **REST API (Import)** | HTTP + JSON | 蝗槫<EFBFBD>雍ｨ謗ｧ諢剰ｧ<EFBFBD>ｼ<EFBFBD>hase 2<>?| 謖蛾怙隹<E68099>畑 |
+| **REST API (Import)** | HTTP + JSON | 回写质控意见（Phase 2） | 按需调用 |
 | **轮询机制** | pg-boss定时任务 | 补充DET遗漏数据 | 30分钟 |

 ---

-## <EFBFBD>剥 謚譛ｯ隹<EFBDAF><E99AB9>皮ｻ捺<EFBDBB>?
+## 🔍 技术调研结果

-### 隹<EFBFBD><EFBFBD><EFBFBD>1<EFBFBD>啌EDCap謠蝉ｾ帷噪蟇ｹ謗･譁ｹ蠑?
+### 调研1：REDCap提供的对接方式

-**隹<EFBFBD><EFBFBD>疲擂貅撰ｼ?*
+**调研来源：**
 - REDCap 15.8.0源码
 - External Module Framework官方文档
- REDCap莠梧ｬ｡蠑蜿第ｷｱ蠎ｦ謖<EFBFBD><EFBFBD>?
+- REDCap二次开发深度指南

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

 | 方式 | 技术栈 | 适用场景 | 我们是否适用 |
 |------|--------|---------|-------------|
-| **External Module** | PHP + Hook | REDCap蜀<EFBFBD>Κ蜉溯<EFBFBD>謇ｩ螻輔ゞI螳壼宛 | 笶?荳埼ら畑 |
-| **REST API** | HTTP + JSON | 螟夜Κ邉ｻ扈滄寔謌舌∵焚謐ｮ蜷梧ｭ?| 笨?**騾ら畑** |
-| **Data Entry Trigger** | Webhook | 螳樊慮騾夂衍螟夜Κ邉ｻ扈<EFBFBD> | 笨?**騾ら畑** |
+| **External Module** | PHP + Hook | REDCap内部功能扩展、UI定制 | ❌ 不适用 |
+| **REST API** | HTTP + JSON | 外部系统集成、数据同步 | ✅ **适用** |
+| **Data Entry Trigger** | Webhook | 实时通知外部系统 | ✅ **适用** |

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

-**貅千<EFBFBD>∽ｽ咲ｽｮ<EFBFBD>?*
+**源码位置：**
 ```
 /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
 ```

-**蜈ｳ髞ｮ莉｣遐<EFBFBD>ｼ?*
+**关键代码：**
 ```php
 // DataEntry.php 核心实现
 global $data_entry_trigger_url, $data_entry_trigger_enabled;
@@ -74,88 +74,88 @@ if (!$data_entry_trigger_enabled || $data_entry_trigger_url == '') {
 $full_url = $pre_url . $data_entry_trigger_url;
 ```

-**鬪瑚ｯ∫ｻ楢ｮｺ<EFBFBD>?* 笨?DET譏ｯREDCap蜴溽函蜉溯<EFBFBD><EFBFBD>檎悄螳槫ｭ伜惠荳泌ｹｿ豕帑ｽｿ逕ｨ
+**验证结论：** ✅ DET是REDCap原生功能，真实存在且广泛使用

 ---

-## <EFBFBD>女<EFBFBD>?螳梧紛譫ｶ譫<EFBDB6>ｮｾ隶｡
+## 🏗️ 完整架构设计

-### 譫ｶ譫<EFBFBD><EFBFBD>?
+### 架构图

 ```
-笏娯楳笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏?
-笏? 1. CRC 蝨?REDCap 荳ｭ菫晏ｭ倩ｮｰ蠖?                        笏?
-笏?    - 蠖募<EFBFBD>謔｣閠<EFBFBD>焚謐?                                  笏?
-笏?    - 轤ｹ蜃ｻ"Save"謖蛾聴                                 笏?
-笏披楳笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏ｬ笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏?
-                   竊?遶句叉隗ｦ蜿托ｼ<E68998>EDCap DET<45>?遘貞ｻｶ霑滂ｼ<E6BB82>
-笏娯楳笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏?
-笏? 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遘貞<E98198>
-笏娯楳笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏?
-笏? 3. Node.js Webhook謗･謾ｶ蝎?                          笏?
-笏?    - 鬪瑚ｯ∬ｯｷ豎よ擂貅撰ｼ亥庄騾会ｼ<EFBFBD>                           笏?
-笏?    - 遶句叉霑泌屓200 OK<EFBFBD>?100ms<EFBFBD>御ｸ埼仆蝪朿EDCap<EFBFBD>?       笏?
-笏?    - 蠑よｭ･隹<EFBFBD>畑雍ｨ謗ｧ豬∫ｨ具ｼ<EFBFBD>etImmediate<EFBFBD>?              笏?
-笏披楳笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏ｬ笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏?
-                   竊?蠑よｭ･螟<EFBDA5>炊
-笏娯楳笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏?
-笏? 4. REDCap REST API - exportRecords                 笏?
-笏?    - 菴ｿ逕ｨAPI Token隶､隸<EFBFBD>                             笏?
-笏?    - 諡牙叙謖<EFBFBD>ｮ嗷ecord_id逧<EFBFBD>ｮ梧紛謨ｰ謐?                  笏?
-笏?    - 蛹<EFBFBD>性謇譛牙ｭ玲ｮｵ蛟ｼ縲∝<EFBFBD>謨ｰ謐ｮ                         笏?
-笏披楳笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏ｬ笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏?
-                   竊?
-笏娯楳笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏?
-笏? 5. 謗ｨ騾∝芦雍ｨ謗ｧ髦溷<EFBFBD>                                   笏?
-笏?    - jobQueue.send('iit:quality-check', record)    笏?
-笏?    - 蠑よｭ･螟<EFBFBD>炊<EFBFBD>御ｸ榊ｽｱ蜩榊ｮ樊慮蜩榊ｺ<EFBFBD>                       笏?
-笏披楳笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏ｬ笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏?
-                   竊?逕ｱQualityCheckAgent螟<EFBFBD>炊<EFBFBD><EFBFBD>ay 6<EFBFBD>?
-笏娯楳笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏?
-笏? 6. AI雍ｨ謗ｧ蛻<EFBFBD>梵                                       笏?
-笏?    - 隗<EFBFBD><EFBFBD>蠑墓梼鬪瑚ｯ<EFBFBD>                                   笏?
-笏?    - AI謗ｨ逅<EFBFBD>｣豬句ｼょｸ?                                笏?
-笏?    - 逕滓<EFBFBD>雍ｨ謗ｧ謚･蜻<EFBFBD>                                   笏?
-笏披楳笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏ｬ笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏?
-                   竊?3-5遘貞<EFBFBD>
-笏娯楳笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏?
-笏? 7. 螟壽ｸ<EFBFBD>驕灘渚鬥?                                      笏?
-笏?    A. 莨∽ｸ壼ｾｮ菫｡謗ｨ騾∫ｻ僂RC<EFBFBD>亥ｮ樊慮騾夂衍<EFBFBD>?                笏?
-笏?    B. REDCap API importQueries<EFBFBD>亥<EFBFBD>蝗櫁ｴｨ逍托ｼ<EFBFBD>          笏?
-笏?    C. IIT Manager蜑咲ｫｯ譏ｾ遉ｺ<EFBFBD>亥ｾ<EFBFBD>萱莠矩｡ｹ<EFBFBD><EFBFBD>               笏?
-笏披楳笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏?
+┌─────────────────────────────────────────────────────┐
+│  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前端显示（待办事项）               │
+└─────────────────────────────────────────────────────┘

-笏娯楳笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏?
-笏? 陦･蜈<EFBDA5>ｼ壼ｮ壽慮霓ｮ隸｢譛ｺ蛻ｶ<E89BBB>域ｯ?0蛻<30>帖<EFBFBD>?                     笏?
-笏?    - 髦ｲ豁｢DET驕玲ｼ乗焚謐ｮ                                笏?
-笏?    - 菴ｿ逕ｨdateRangeBegin蠅樣㍼諡牙叙                    笏?
-笏?    - 謗ｨ騾∝芦逶ｸ蜷檎噪雍ｨ謗ｧ髦溷<EFBFBD>?                          笏?
-笏披楳笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏笏?
+┌─────────────────────────────────────────────────────┐
+│  补充：定时轮询机制（每30分钟）                      │
+│     - 防止DET遗漏数据                                │
+│     - 使用dateRangeBegin增量拉取                    │
+│     - 推送到相同的质控队列                           │
+└─────────────────────────────────────────────────────┘
 ```

-### 螳樊慮諤ｧ蟇ｹ豈?
+### 实时性对比

 | 方案 | 延迟时间 | 我们的选择 |
 |------|---------|-----------|
-| **郤ｯ霓ｮ隸｢<EFBFBD>域ｯ?蛻<>帖<EFBFBD>?* | 譛鬮?蛻<>帖 | 笶?荳肴ｻ｡雜ｳ螳樊慮諤ｧ隕∵ｱ?|
-| **郤ｯ霓ｮ隸｢<EFBFBD>域ｯ?蛻<>帖<EFBFBD>?* | 譛鬮?蛻<>帖 | 笞<><E7AC9E><EFBFBD> 襍<>ｺ先ｵｪ雍ｹ縲∝ｻｶ霑滉ｻ埼ｫ?|
-| **DET + API** | 0遘定ｧｦ蜿?+ 3-5遘貞､<E8B29E><EFBDA4>?| 笨?**譛莨俶婿譯?* |
-| **DET + 霓ｮ隸｢陦･蜈<EFBFBD>** | 螳樊慮 + 蜿ｯ髱<EFBDAF> | 笨?**譛扈域楔譫?* |
+| **纯轮询（每5分钟）** | 最高5分钟 | ❌ 不满足实时性要求 |
+| **纯轮询（每1分钟）** | 最高1分钟 | ⚠️ 资源浪费、延迟仍高 |
+| **DET + API** | 0秒触发 + 3-5秒处理 | ✅ **最优方案** |
+| **DET + 轮询补充** | 实时 + 可靠 | ✅ **最终架构** |

-**扈楢ｮｺ<EFBFBD>?* CRC轤ｹ蜃ｻ"菫晏ｭ<E6998F>" 竊?5遘貞<E98198>謾ｶ蛻ｰ莨∽ｸ壼ｾｮ菫｡騾夂衍 笨?
+**结论：** CRC点击"保存" → 5秒内收到企业微信通知 ✅

 ---

-## <EFBFBD>逃 謚譛ｯ螳樒鴫隸ｦ隗?
+## 📦 技术实现详解

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

@@ -163,9 +163,9 @@ $full_url = $pre_url . $data_entry_trigger_url;

 ```
 1. 登录REDCap：http://localhost:8080/
-2. 菴ｿ逕ｨ邂｡逅<EFBFBD>遭雍ｦ謌ｷ<EFBFBD><EFBFBD>dmin / Admin123!<EFBFBD>?
-3. 霑帛<EFBFBD><EFBFBD>咾ontrol Center 竊?"Additional Customizations"
-4. 謇ｾ蛻ｰ<EFBFBD>?Data Entry Trigger" 騾蛾｡ｹ
+2. 使用管理员账户（Admin / Admin123!）
+3. 进入：Control Center → "Additional Customizations"
+4. 找到："Data Entry Trigger" 选项
 5. 设置为："Enabled"
 6. 保存配置
 ```
@@ -176,10 +176,10 @@ $full_url = $pre_url . $data_entry_trigger_url;

 ```
 1. 进入测试项目：test0102 (PID 16)
-2. 蟾ｦ萓ｧ闖懷黒 竊?Project Setup
-3. 謇ｾ蛻ｰ<EFBFBD>?Additional Customizations"
-4. 螻募ｼ<EFBFBD>?Data Entry Trigger URL"
-5. 蝪ｫ蜈･Webhook URL<EFBFBD>?
+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
@@ -190,22 +190,22 @@ $full_url = $pre_url . $data_entry_trigger_url;

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

-**菴ｿ逕ｨRequestBin/ngrok鬪瑚ｯ<EFBFBD>ｼ?*
+**使用RequestBin/ngrok验证：**

 ```bash
-# 菴ｿ逕ｨngrok蛻帛ｻｺ荳ｴ譌ｶ蜈ｬ鄂繕RL<EFBFBD>亥ｼ蜿第ｵ玖ｯ慕畑<EFBFBD>?
+# 使用ngrok创建临时公网URL（开发测试用）
 ngrok http 3001

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

-# 蝨ｨREDCap荳ｭ菫晏ｭ倅ｸ譚｡隶ｰ蠖?
+# 在REDCap中保存一条记录
 # 检查ngrok控制台是否收到POST请求
 ```

 #### DET的POST Payload格式

-**REDCap蜿鷹∫噪隸ｷ豎ゑｼ?*
+**REDCap发送的请求：**

 ```http
 POST /api/v1/iit/webhooks/redcap HTTP/1.1
@@ -221,7 +221,7 @@ project_id=16
 &redcap_url=http://localhost:8080/
 ```

-**蟄玲ｮｵ隸ｴ譏趣ｼ?*
+**字段说明：**

 | 字段 | 类型 | 说明 | 示例 |
 |------|-----|------|------|
@@ -229,7 +229,7 @@ project_id=16
 | `record` | string | 记录ID | "101" |
 | `instrument` | string | 表单名称 | "demographics" |
 | `redcap_event_name` | string | 事件名称（纵向研究） | "baseline_arm_1" |
-| `[instrument]_complete` | string | 陦ｨ蜊募ｮ梧<EFBFBD>迥ｶ諤<EFBFBD>ｼ<EFBFBD>0/1/2<EFBFBD>?| "2" |
+| `[instrument]_complete` | string | 表单完成状态（0/1/2） | "2" |
 | `redcap_url` | string | REDCap实例URL | "http://localhost:8080/" |

 ---
@@ -244,23 +244,23 @@ http://localhost:8080/api/

 #### API认证：Token

-**逕滓<EFBFBD>豁･鬪､<EFBFBD>?*
+**生成步骤：**
 ```
 1. 登录REDCap
 2. 进入项目：test0102 (PID 16)
-3. 蟾ｦ萓ｧ闖懷黒 竊?"API"
+3. 左侧菜单 → "API"
 4. 点击 "Generate API Token"
-5. 螟榊宛Token<EFBFBD>?2菴榊ｭ礼ｬｦ荳ｲ<E88DB3>?
+5. 复制Token（32位字符串）
 6. 保存到环境变量：
   REDCAP_API_TOKEN_TEST=YOUR_TOKEN_HERE
 ```

-**Token蟄伜お<EFBFBD>?*
- 笨?邇ｯ蠅<EFBDAF>序驥擾ｼ域耳闕撰ｼ<E692B0>
- 笨?謨ｰ謐ｮ蠎灘刈蟇<E58888>ｭ玲ｮｵ<EFBDAE><EFBDB5>itProject.redcapApiToken<EFBFBD>?
- 笶?荳崎ｦ∵署莠､蛻ｰGit
+**Token存储：**
+- ✅ 环境变量（推荐）
+- ✅ 数据库加密字段（IitProject.redcapApiToken）
+- ❌ 不要提交到Git

-#### API譁ｹ豕<EFBFBD>1<EFBFBD>壼ｯｼ蜃ｺ隶ｰ蠖?(exportRecords)
+#### API方法1：导出记录 (exportRecords)

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

@@ -277,28 +277,28 @@ curl -X POST http://localhost:8080/api/ \
  -F "dateRangeBegin=2026-01-01 00:00:00"
 ```

-**蜿よ焚隸ｴ譏趣ｼ?*
+**参数说明：**

 | 参数 | 必填 | 说明 | 示例 |
 |------|-----|------|------|
-| `token` | 笨?| API Token | "ABC123..." |
-| `content` | 笨?| 蝗ｺ螳壼?| "record" |
-| `format` | 笨?| 霑泌屓譬ｼ蠑<EFBDBC> | "json" |
-| `type` | 笨?| 謨ｰ謐ｮ扈捺桷 | "flat" |
-| `records` | 笶?| 謖<>ｮ夊ｮｰ蠖肘D | ["101", "102"] |
-| `fields` | 笶?| 謖<>ｮ壼ｭ玲ｮｵ | ["age", "gender"] |
-| `dateRangeBegin` | 笶?| 譌ｶ髣ｴ霑<EFBDB4>ｻ､<EFBDBB>亥｢樣㍼蜷梧ｭ･蜈ｳ髞ｮ<E9AB9E><EFBDAE> | "2026-01-01 00:00:00" |
-| `dateRangeEnd` | 笶?| 扈捺據譌ｶ髣ｴ | "2026-01-31 23:59:59" |
+| `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": "荳?,
+    "first_name": "张",
+    "last_name": "三",
    "age": "30",
    "gender": "1",
    "demographics_complete": "2"
@@ -308,9 +308,9 @@ curl -X POST http://localhost:8080/api/ \

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

-**逕ｨ騾費ｼ<EFBFBD>** 闔ｷ蜿門ｭ玲ｮｵ螳壻ｹ峨∬｡ｨ蜊慕ｻ捺<EFBDBB>?
+**用途：** 获取字段定义、表单结构

-**隸ｷ豎ら､ｺ萓具ｼ?*
+**请求示例：**

 ```bash
 curl -X POST http://localhost:8080/api/ \
@@ -319,7 +319,7 @@ curl -X POST http://localhost:8080/api/ \
  -F "format=json"
 ```

-**蜩榊ｺ皮､ｺ萓具ｼ?*
+**响应示例：**

 ```json
 [
@@ -346,11 +346,11 @@ curl -X POST http://localhost:8080/api/ \
 ]
 ```

-#### API譁ｹ豕<EFBFBD>3<EFBFBD>壼ｯｼ蜈･隶ｰ蠖?(importRecords) - Phase 2
+#### API方法3：导入记录 (importRecords) - Phase 2

-**逕ｨ騾費ｼ<EFBFBD>** 蝗槫<E89D97>謨ｰ謐ｮ<E8AC90>亥ｦりｴｨ謗ｧ諢剰ｧ√、I蟒ｺ隶ｮ<E99AB6>?
+**用途：** 回写数据（如质控意见、AI建议）

-**隸ｷ豎ら､ｺ萓具ｼ?*
+**请求示例：**

 ```bash
 curl -X POST http://localhost:8080/api/ \
@@ -368,7 +368,7 @@ curl -X POST http://localhost:8080/api/ \

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

-**譁<EFBFBD>ｻｶ<EFBFBD>?* `backend/src/modules/iit-manager/adapters/RedcapAdapter.ts`
+**文件：** `backend/src/modules/iit-manager/adapters/RedcapAdapter.ts`

 ```typescript
 import axios from 'axios';
@@ -452,7 +452,7 @@ export class RedcapAdapter {
  }

  /**
-   * 蟇ｼ蜃ｺ蜈<EFBFBD>焚謐ｮ<EFBFBD>亥ｭ玲ｮｵ螳壻ｹ会ｼ?
+   * 导出元数据（字段定义）
   */
  async exportMetadata(): Promise<any[]> {
    const formData = new FormData();
@@ -523,7 +523,7 @@ export class RedcapAdapter {

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

-**譁<EFBFBD>ｻｶ<EFBFBD>?* `backend/src/modules/iit-manager/controllers/webhookController.ts`
+**文件：** `backend/src/modules/iit-manager/controllers/webhookController.ts`

 ```typescript
 import { FastifyRequest, FastifyReply } from 'fastify';
@@ -536,7 +536,7 @@ export class WebhookController {
  /**
   * 接收REDCap Data Entry Trigger Webhook
   * 
-   * 諤ｧ閭ｽ隕∵ｱゑｼ壼桃蠎疲慮髣?< 100ms<6D>井ｸ埼仆蝪朿EDCap<EFBFBD>?
+   * 性能要求：响应时间 < 100ms（不阻塞REDCap）
   */
  async handleRedcapWebhook(
    request: FastifyRequest,
@@ -569,7 +569,7 @@ export class WebhookController {
      event: redcap_event_name
    });

-    // 遶句叉霑泌屓200<EFBFBD>井ｸ埼仆蝪朿EDCap<EFBFBD>?
+    // 立即返回200（不阻塞REDCap）
    const responseTime = Date.now() - startTime;
    reply.code(200).send({
      status: 'received',
@@ -577,7 +577,7 @@ export class WebhookController {
      response_time_ms: responseTime
    });

-    // 蠑よｭ･螟<EFBFBD>炊<EFBFBD>井ｸ埼仆蝪曰TTP蜩榊ｺ費ｼ?
+    // 异步处理（不阻塞HTTP响应）
    setImmediate(async () => {
      try {
        await this.processWebhook({
@@ -589,7 +589,7 @@ export class WebhookController {
        });
      } catch (error) {
        logger.error('Webhook processing failed:', error);
-        // 荳肴鴨蜃ｺ髞呵ｯｯ<EFBFBD>悟屏荳ｺ蟾ｲ扈剰ｿ泌屓200莠?
+        // 不抛出错误，因为已经返回200了
      }
    });
  }
@@ -616,7 +616,7 @@ export class WebhookController {
      return;
    }

-    // 2. 蟷らｭ画ｧ譽譟･<EFBFBD>磯亟豁｢驥榊､榊､<EFBFBD>炊<EFBFBD>?
+    // 2. 幂等性检查（防止重复处理）
    const isDuplicate = await this.checkDuplicate(
      project.id,
      record,
@@ -635,7 +635,7 @@ export class WebhookController {
    );

    const records = await adapter.exportRecords({
-      records: [record]  // 蜿ｪ諡牙叙霑吩ｸ譚｡隶ｰ蠖?
+      records: [record]  // 只拉取这一条记录
    });

    if (records.length === 0) {
@@ -699,7 +699,7 @@ export class WebhookController {

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

-**譁<EFBFBD>ｻｶ<EFBFBD>?* `backend/src/modules/iit-manager/services/SyncManager.ts`
+**文件：** `backend/src/modules/iit-manager/services/SyncManager.ts`

 ```typescript
 import { prisma } from '@/config/database';
@@ -709,10 +709,10 @@ import { RedcapAdapter } from '../adapters/RedcapAdapter';

 export class SyncManager {
  /**
-   * 蛻晏ｧ句喧蜷梧ｭ･<EFBFBD>域ｳｨ蜀悟ｮ壽慮莉ｻ蜉｡<EFBFBD>?
+   * 初始化同步（注册定时任务）
   */
  async initializeSync(projectId: string, interval: string = '*/30 * * * *'): Promise<void> {
-    // 豕ｨ蜀悟ｮ壽慮莉ｻ蜉｡<EFBFBD>域ｯ<EFBFBD>30蛻<EFBFBD>帖<EFBFBD>?
+    // 注册定时任务（每30分钟）
    await jobQueue.schedule(
      'iit:redcap:poll',
      interval,
@@ -783,7 +783,7 @@ export class SyncManager {
   * 停止同步（取消定时任务）
   */
  async stopSync(projectId: string): Promise<void> {
-    // pg-boss荳肴髪謖∫峩謗･蜿匁ｶ<EFBFBD>chedule<EFBFBD>碁怙隕∝惠Worker荳ｭ譽譟･鬘ｹ逶ｮ迥ｶ諤?
+    // pg-boss不支持直接取消schedule，需要在Worker中检查项目状态
    logger.info(`Sync stopped for project ${projectId}`);
  }
 }
@@ -791,7 +791,7 @@ export class SyncManager {

 #### 3.4 路由配置

-**譁<EFBFBD>ｻｶ<EFBFBD>?* `backend/src/modules/iit-manager/routes/index.ts`
+**文件：** `backend/src/modules/iit-manager/routes/index.ts`

 ```typescript
 import { FastifyInstance } from 'fastify';
@@ -802,12 +802,12 @@ export async function iitManagerRoutes(fastify: FastifyInstance) {
  const webhookController = new WebhookController();
  const syncManager = new SyncManager();

-  // Webhook遶ｯ轤ｹ<EFBFBD>域磁謾ｶREDCap DET<EFBFBD>?
+  // Webhook端点（接收REDCap DET）
  fastify.post('/webhooks/redcap', async (request, reply) => {
    return webhookController.handleRedcapWebhook(request, reply);
  });

-  // 謇句勘隗ｦ蜿大酔豁･<EFBFBD>域ｵ玖ｯ慕畑<EFBFBD>?
+  // 手动触发同步（测试用）
  fastify.post('/projects/:id/sync', async (request, reply) => {
    const { id } = request.params as { id: string };
    await syncManager.handlePoll(id);
@@ -818,7 +818,7 @@ export async function iitManagerRoutes(fastify: FastifyInstance) {

 #### 3.5 Worker注册

-**譁<EFBFBD>ｻｶ<EFBFBD>?* `backend/src/modules/iit-manager/index.ts`
+**文件：** `backend/src/modules/iit-manager/index.ts`

 ```typescript
 import { jobQueue } from '@/common/jobs';
@@ -844,19 +844,19 @@ export async function initializeIITManager() {

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

-**豁･鬪､<EFBFBD>?*
+**步骤：**
 1. 配置ngrok：`ngrok http 3001`
 2. 将ngrok URL配置到REDCap DET
-3. 蝨ｨREDCap荳ｭ菫晏ｭ倅ｸ譚｡隶ｰ蠖?
+3. 在REDCap中保存一条记录
 4. 检查ngrok控制台是否收到POST请求

-**鬚<EFBFBD>悄扈捺棡<EFBFBD>?*
- 笨?ngrok謾ｶ蛻ｰPOST隸ｷ豎<EFBFBD>
- 笨?Payload蛹<EFBFBD>性project_id縲〉ecord遲牙ｭ玲ｮ?
+**预期结果：**
+- ✅ ngrok收到POST请求
+- ✅ Payload包含project_id、record等字段

 ### 测试2：验证API Token

-**豬玖ｯ戊<EFBFBD>譛ｬ<EFBFBD>?* `test-redcap-api.ts`
+**测试脚本：** `test-redcap-api.ts`

 ```typescript
 import { RedcapAdapter } from './adapters/RedcapAdapter';
@@ -871,11 +871,11 @@ async function testRedcapAPI() {
  const records = await adapter.exportRecords();
  console.log('Records:', records);

-  // 豬玖ｯ募ｯｼ蜃ｺ蜈<EFBFBD>焚謐?
+  // 测试导出元数据
  const metadata = await adapter.exportMetadata();
  console.log('Metadata fields:', metadata.length);

-  console.log('笨?REDCap API test passed!');
+  console.log('✅ REDCap API test passed!');
 }

 testRedcapAPI();
@@ -883,7 +883,7 @@ testRedcapAPI();

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

-**豬玖ｯ戊<EFBFBD>譛ｬ<EFBFBD>?* `test-redcap-integration.ts`
+**测试脚本：** `test-redcap-integration.ts`

 ```typescript
 async function testIntegration() {
@@ -898,11 +898,11 @@ async function testIntegration() {
    }
  });

-  // 2. 蛻晏ｧ句喧蜷梧ｭ?
+  // 2. 初始化同步
  const syncManager = new SyncManager();
  await syncManager.initializeSync(project.id);

-  // 3. 謇句勘隗ｦ蜿台ｸ谺｡霓ｮ隸?
+  // 3. 手动触发一次轮询
  await syncManager.handlePoll(project.id);

  // 4. 模拟Webhook
@@ -918,7 +918,7 @@ async function testIntegration() {
    {} as any
  );

-  console.log('笨?Integration test passed!');
+  console.log('✅ Integration test passed!');
 }
 ```

@@ -926,18 +926,18 @@ async function testIntegration() {

 ## 📋 Day 2实施清单

-### 髦ｶ谿ｵ1<EFBFBD>夂識蠅<EFBFBD>㊥螟<EFBFBD>ｼ<EFBFBD>30蛻<EFBFBD>帖<EFBFBD>?
+### 阶段1：环境准备（30分钟）

 - [ ] 在REDCap Control Center启用DET功能
 - [ ] 在test0102项目生成API Token
- [ ] 驟咲ｽｮ邇ｯ蠅<EFBFBD>序驥擾ｼ?
+- [ ] 配置环境变量：
  ```env
  REDCAP_BASE_URL=http://localhost:8080
  REDCAP_API_TOKEN_TEST=YOUR_TOKEN_HERE
  ```
 - [ ] 使用curl测试API是否可用

-### 髦ｶ谿ｵ2<EFBFBD>壼ｼ蜿然edcapAdapter<EFBFBD>?.5蟆乗慮<EFBFBD>?
+### 阶段2：开发RedcapAdapter（1.5小时）

 - [ ] 创建文件：`adapters/RedcapAdapter.ts`
 - [ ] 实现 `exportRecords()` 方法
@@ -945,15 +945,15 @@ async function testIntegration() {
 - [ ] 实现 `formatRedcapDate()` 工具方法
 - [ ] 编写单元测试：`RedcapAdapter.test.ts`

-### 髦ｶ谿ｵ3<EFBFBD>壼ｼ蜿糎ebhookController<EFBFBD>?蟆乗慮<E4B997>?
+### 阶段3：开发WebhookController（2小时）

 - [ ] 创建文件：`controllers/webhookController.ts`
 - [ ] 实现 `handleRedcapWebhook()` 方法
 - [ ] 实现 `processWebhook()` 私有方法
- [ ] 螳樒鴫 `checkDuplicate()` 蟷らｭ画ｧ譽譟?
+- [ ] 实现 `checkDuplicate()` 幂等性检查
 - [ ] 配置路由：`POST /api/v1/iit/webhooks/redcap`

-### 髦ｶ谿ｵ4<EFBFBD>壼ｼ蜿全yncManager<EFBFBD>?.5蟆乗慮<EFBFBD>?
+### 阶段4：开发SyncManager（1.5小时）

 - [ ] 创建文件：`services/SyncManager.ts`
 - [ ] 实现 `initializeSync()` 方法
@@ -961,19 +961,19 @@ async function testIntegration() {
 - [ ] 实现 `stopSync()` 方法
 - [ ] 注册Worker：`iit:redcap:poll`

-### 髦ｶ谿ｵ5<EFBFBD>夐寔謌先ｵ玖ｯ包ｼ<EFBFBD>1蟆乗慮<EFBFBD>?
+### 阶段5：集成测试（1小时）

 - [ ] 配置ngrok/RequestBin测试DET
 - [ ] 运行 `test-redcap-api.ts`
 - [ ] 运行 `test-redcap-integration.ts`
- [ ] 鬪瑚ｯ∫ｫｯ蛻ｰ遶ｯ豬∫ｨ?
+- [ ] 验证端到端流程
 - [ ] 记录测试结果

-### 髦ｶ谿ｵ6<EFBFBD>壽枚譯｣譖ｴ譁ｰ<EFBFBD><EFBFBD>30蛻<EFBFBD>帖<EFBFBD>?
+### 阶段6：文档更新（30分钟）

- [ ] 譖ｴ譁ｰMVP蠑蜿台ｻｻ蜉｡貂<EFBDA1>黒<EFBFBD><E9BB92>ay 2螳梧<E89EB3><E6A2A7>?
- [ ] 隶ｰ蠖柊PI Token蜥碁<EFBFBD>鄂ｮ菫｡諱?
- [ ] 譖ｴ譁ｰ譫ｶ譫<EFBDB6><E8ADAB>?
+- [ ] 更新MVP开发任务清单（Day 2完成）
+- [ ] 记录API Token和配置信息
+- [ ] 更新架构图
 - [ ] 提交Git

 ---
@@ -982,48 +982,48 @@ async function testIntegration() {

 ### 1. DET配置要点

-**蟶ｸ隗<EFBFBD>漠隸ｯ<EFBFBD>?*
- 笶?蠢倩ｮｰ蝨ｨControl Center蜷ｯ逕ｨDET蜈ｨ螻蠑蜈?
- 笶?Webhook URL蝪ｫ蜀咎漠隸ｯ<EFBFBD>亥､壻ｺ<EFBFBD>万譚<EFBFBD>縲∝ｰ台ｺ<EFBFBD>ｷｯ蠕<EFBFBD>ｼ<EFBFBD>
- 笶?譛ｬ蝨ｰ蠑蜿醍識蠅<E8AD98>裏豕墓磁謾ｶ螟也ｽ糎ebhook
+**常见错误：**
+- ❌ 忘记在Control Center启用DET全局开关
+- ❌ Webhook URL填写错误（多了斜杠、少了路径）
+- ❌ 本地开发环境无法接收外网Webhook

-**隗｣蜀ｳ譁ｹ譯茨ｼ?*
- 笨?菴ｿ逕ｨngrok蛻帛ｻｺ荳ｴ譌ｶ蜈ｬ鄂繕RL豬玖ｯ<E78E96>
- 笨?蠑蜿醍識蠅<E8AD98>庄蜈育畑RequestBin鬪瑚ｯ￣ayload譬ｼ蠑<EFBFBD>
- 笨?逕滉ｺｧ邇ｯ蠅<EFBDAF>｡ｮ菫拔RL蜿ｯ隶ｿ髣ｮ<E9ABA3>磯亟轣ｫ蠅吶？TTPS<EFBFBD>?
+**解决方案：**
+- ✅ 使用ngrok创建临时公网URL测试
+- ✅ 开发环境可先用RequestBin验证Payload格式
+- ✅ 生产环境确保URL可访问（防火墙、HTTPS）

 ### 2. API Token安全

-**螳牙<EFBFBD>螳櫁ｷｵ<EFBFBD>?*
- 笨?蟄伜お蝨ｨ邇ｯ蠅<EFBDAF>序驥乗<E9A9A5>謨ｰ謐ｮ蠎灘刈蟇<E58888>ｭ玲ｮ?
- 笨?螳壽悄霓ｮ謐｢Token
- 笨?譛蟆乗揀髯仙次蛻呻ｼ亥宵蠑蜷ｯ髴隕∫噪譚<E599AA>剞<EFBFBD>?
- 笶?荳崎ｦ∵署莠､蛻ｰGit
- 笶?荳崎ｦ∝惠譌･蠢嶺ｸｭ謇灘魂螳梧紛Token
+**安全实践：**
+- ✅ 存储在环境变量或数据库加密字段
+- ✅ 定期轮换Token
+- ✅ 最小权限原则（只开启需要的权限）
+- ❌ 不要提交到Git
+- ❌ 不要在日志中打印完整Token

 ### 3. 性能优化

-**Webhook蜩榊ｺ疲慮髣ｴ<EFBFBD>?*
- 笨?蠢<>｡ｻ < 100ms<6D>育ｫ句叉霑泌<E99C91>?00<30>?
- 笨?菴ｿ逕ｨ `setImmediate()` 蠑よｭ･螟<EFBDA5>炊
- 笶?荳崎ｦ∝惠Webhook荳ｭ謇ｧ陦瑚玲慮謫堺ｽ<E5A0BA>
+**Webhook响应时间：**
+- ✅ 必须 < 100ms（立即返回200）
+- ✅ 使用 `setImmediate()` 异步处理
+- ❌ 不要在Webhook中执行耗时操作

-**API隹<EFBFBD>畑鬚醍紫<EFBFBD>?*
- 笨?蠅樣㍼諡牙叙<E78999>井ｽｿ逕ｨdateRangeBegin<EFBFBD>?
- 笨?謖<>ｮ壼ｭ玲ｮｵ<EFBDAE>亥㍼蟆第焚謐ｮ驥擾ｼ?
- 笨?蜷育炊隶ｾ鄂ｮtimeout<75>?0遘抵ｼ<E68AB5>
+**API调用频率：**
+- ✅ 增量拉取（使用dateRangeBegin）
+- ✅ 指定字段（减少数据量）
+- ✅ 合理设置timeout（30秒）

 ### 4. 错误处理

-**DET Webhook螟ｱ雍･<EFBFBD>?*
- REDCap莨夐㍾隸?谺｡<E8B0BA>磯龍髫<E9BE8D>1蛻<31>帖<EFBFBD>?
+**DET Webhook失败：**
+- REDCap会重试3次（间隔1分钟）
 - 如果仍失败，REDCap会记录到日志
 - 我们的轮询机制可以补充遗漏的数据

-**API隹<EFBFBD>畑螟ｱ雍･<EFBFBD>?*
- 螳樒鴫驥崎ｯ墓惻蛻ｶ<E89BBB>?谺｡<E8B0BA>梧欠謨ｰ騾驕ｿ<E9A995><EFBDBF>
+**API调用失败：**
+- 实现重试机制（3次，指数退避）
 - 记录失败日志
- 蜻願ｭｦ騾夂衍邂｡逅<EFBDA1><E98085>?
+- 告警通知管理员

 ---

@@ -1031,42 +1031,41 @@ async function testIntegration() {

 ### Day 2完成标准

- [ ] 笨?REDCap API Token蟾ｲ逕滓<EFBFBD>蟷ｶ鬪瑚ｯ<EFBFBD>
- [ ] 笨?RedcapAdapter蜿ｯ莉･諡牙叙豬玖ｯ墓焚謐ｮ
- [ ] 笨?DET蟾ｲ驟咲ｽｮ蟷ｶ謌仙粥謗･謾ｶWebhook
- [ ] 笨?Webhook蜿ｯ莉･隗ｦ蜿羨PI諡牙叙
- [ ] 笨?霓ｮ隸｢譛ｺ蛻ｶ蜿ｯ莉･螳壽慮霑占｡<E58DA0>
- [ ] 笨?謨ｰ謐ｮ謗ｨ騾∝芦雍ｨ謗ｧ髦溷<E9ABA6>
- [ ] 笨?蜊募<E89C8A>豬玖ｯ募<EFBDAF>驛ｨ騾夊ｿ<E5A48A>
- [ ] 笨?遶ｯ蛻ｰ遶ｯ髮<EFBDAF><E9ABAE>豬玖ｯ暮夊ｿ<E5A48A>
+- [ ] ✅ REDCap API Token已生成并验证
+- [ ] ✅ RedcapAdapter可以拉取测试数据
+- [ ] ✅ DET已配置并成功接收Webhook
+- [ ] ✅ Webhook可以触发API拉取
+- [ ] ✅ 轮询机制可以定时运行
+- [ ] ✅ 数据推送到质控队列
+- [ ] ✅ 单元测试全部通过
+- [ ] ✅ 端到端集成测试通过

 ### 性能指标

 - [ ] Webhook响应时间 < 100ms
- [ ] API隹<EFBFBD>畑謌仙粥邇?> 99%
- [ ] 遶ｯ蛻ｰ遶ｯ蟒ｶ霑?< 5遘抵ｼ<E68AB5>ET隗ｦ蜿<EFBDA6> 竊?莨∝ｾｮ騾夂衍<E5A482>?
+- [ ] API调用成功率 > 99%
+- [ ] 端到端延迟 < 5秒（DET触发 → 企微通知）

 ---

 ## 🔗 相关文档

- **MVP蠑蜿台ｻｻ蜉｡貂<EFBFBD>黒<EFBFBD><EFBFBD>** `MVP蠑蜿台ｻｻ蜉｡貂<EFBFBD><EFBFBD>?md`
- **螳梧紛謚譛ｯ譁ｹ譯茨ｼ<E88CA8>** `IIT Manager Agent 螳梧紛謚譛ｯ蠑蜿第婿譯?(V1.1).md`
- **REDCap莠梧ｬ｡蠑蜿第欠蜊暦ｼ<EFBFBD>** `../../Redcap/03-API蟇ｹ謗･荳主ｼ蜿?33-REDCap莠梧ｬ｡蠑蜿第ｷｱ蠎ｦ謖<EFBDA6><E8AC96>?md`
- **REDCap驛ｨ鄂ｲ謇句<EFBFBD><EFBFBD>?* `../../Redcap/01-驛ｨ鄂ｲ荳朱<EFBFBD>鄂?10-REDCap_Docker驛ｨ鄂ｲ謫堺ｽ懈焔蜀<EFBFBD>.md`
+- **MVP开发任务清单：** `MVP开发任务清单.md`
+- **完整技术方案：** `IIT Manager Agent 完整技术开发方案 (V1.1).md`
+- **REDCap二次开发指南：** `../../Redcap/03-API对接与开发/33-REDCap二次开发深度指南.md`
+- **REDCap部署手册：** `../../Redcap/01-部署与配置/10-REDCap_Docker部署操作手册.md`

 ---

 ## 📝 更新日志

-| 譌･譛<EFBFBD> | 迚域悽 | 譖ｴ譁ｰ蜀<EFBDB0>ｮｹ | 譖ｴ譁ｰ莠?|
+| 日期 | 版本 | 更新内容 | 更新人 |
 |------|------|---------|--------|
 | 2026-01-02 | V1.0 | 初始版本，完成技术调研和方案设计 | AI Assistant |

 ---

-**霑呎弍IIT Manager Agent逧<EFBFBD>橿譛ｯ蝓ｺ遏ｳ譁<EFBFBD>｡｣<EFBFBD>瑚ｯｷ螯･蝟<EFBFBD>ｿ晉ｮ｡<EFBFBD><EFBFBD>** 箝絶ｭ絶ｭ絶ｭ絶ｭ?
-
+**这是IIT Manager Agent的技术基石文档，请妥善保管！** ⭐⭐⭐⭐⭐