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

docs/03-业务模块/IIT Manager Agent/04-开发计划/Day2-开发完成总结.md

@@ -1,57 +1,76 @@
 # IIT Manager Agent - Day 2 开发完成总结
 
 **日期**: 2026-01-02  
-**寮€鍙戣€?*: AI Assistant  
-**鐘舵€?*: 鉁?鍏ㄩ儴瀹屾垚
+**开发者**: AI Assistant  
+**状态**: ✅ 全部完成
 
 ---
 
 ## 📋 任务完成清单
 
 - [x] 环境准备：DET配置 + API Token获取
-- [x] 寮€鍙?RedcapAdapter锛圓PI閫傞厤鍣<EFBFBD>級
-- [x] 寮€鍙?WebhookController锛圵ebhook鎺ユ敹鍣<EFBFBD>級
-- [x] 寮€鍙?SyncManager锛堣疆璇㈢<EFBFBD>鐞嗭級
+- [x] 开发 RedcapAdapter（API适配器）
+- [x] 开发 WebhookController（Webhook接收器）
+- [x] 开发 SyncManager（轮询管理）
 - [x] 配置路由和Worker注册
-- [x] 缂栧啓娴嬭瘯鑴氭湰锛圓PI + Webhook + 闆嗘垚锛?- [x] 绔<>埌绔<E59F8C>獙璇佹祴璇曞噯澶?
+- [x] 编写测试脚本（API + Webhook + 集成）
+- [x] 端到端验证测试准备
+
 ---
 
 ## 🎯 核心成果
 
-### 1. RedcapAdapter - API閫傞厤鍣?
+### 1. RedcapAdapter - API适配器
+
 **文件**: `backend/src/modules/iit-manager/adapters/RedcapAdapter.ts`
 
 **功能**:
-- 鉁?`exportRecords()` - 鏀<EFBFBD>寔澧為噺鍚屾<EFBFBD>锛坉ateRangeBegin锛?- 鉁?`exportMetadata()` - 鑾峰彇瀛楁<E7809B>瀹氫箟
-- 鉁?`importRecords()` - 鍥炲啓鏁版嵁锛圥hase 2棰勭暀锛?- 鉁?`testConnection()` - 杩炴帴娴嬭瘯
-- 鉁?瀹屾暣鐨勯敊璇<E6958A><E79287>鐞嗗拰鏃ュ織璁板綍
-- 鉁?鎬ц兘鐩戞帶锛堣<E9949B>姹傝€楁椂锛?
-**鎶€鏈<E282AC>寒鐐?*:
-- 浣跨敤 `form-data` 鏋勯€?multipart/form-data 璇锋眰
-- 鏅鸿兘鏃ユ湡鏍煎紡鍖栵紙REDCap鏍煎紡锛歒YYY-MM-DD HH:MM:SS锛?- Axios 瀹炰緥鍖栵紝鏀<E7B49D>寔瓒呮椂閰嶇疆
-- 鍙嬪ソ鐨勯敊璇<E6958A>俊鎭<E4BF8A>紙杩炴帴澶辫触銆佹潈闄愪笉瓒炽€佺<E282AC>鐐逛笉瀛樺湪锛?
+- ✅ `exportRecords()` - 支持增量同步（dateRangeBegin）
+- ✅ `exportMetadata()` - 获取字段定义
+- ✅ `importRecords()` - 回写数据（Phase 2预留）
+- ✅ `testConnection()` - 连接测试
+- ✅ 完整的错误处理和日志记录
+- ✅ 性能监控（请求耗时）
+
+**技术亮点**:
+- 使用 `form-data` 构造 multipart/form-data 请求
+- 智能日期格式化（REDCap格式：YYYY-MM-DD HH:MM:SS）
+- Axios 实例化，支持超时配置
+- 友好的错误信息（连接失败、权限不足、端点不存在）
+
 ---
 
-### 2. WebhookController - Webhook鎺ユ敹鍣?
+### 2. WebhookController - Webhook接收器
+
 **文件**: `backend/src/modules/iit-manager/controllers/WebhookController.ts`
 
 **功能**:
-- 鉁?鎺ユ敹 REDCap DET Webhook
-- 鉁?**鏋侀€熷搷搴?*锛?100ms 杩斿洖 200 OK
-- 鉁?寮傛<E5AFAE>澶勭悊锛坄setImmediate`锛?- 鉁?**骞傜瓑鎬ф<E98EAC>鏌?*锛?鍒嗛挓鍐呴槻閲嶅<E996B2>
-- 鉁?鎷夊彇瀹屾暣璁板綍鏁版嵁
-- 鉁?鎺ㄩ€佸埌璐ㄦ帶闃熷垪锛坧g-boss锛?- 鉁?瀹屾暣鐨勫<E990A8>璁℃棩蹇?
+- ✅ 接收 REDCap DET Webhook
+- ✅ **极速响应**：<100ms 返回 200 OK
+- ✅ 异步处理（`setImmediate`）
+- ✅ **幂等性检查**：5分钟内防重复
+- ✅ 拉取完整记录数据
+- ✅ 推送到质控队列（pg-boss）
+- ✅ 完整的审计日志
+
 **性能目标**:
-- 鍚屾<EFBFBD>鍝嶅簲锛?100ms 鉁?- 鏁版嵁鎷夊彇锛?2s
-- 绔<EFBFBD>埌绔<EFBFBD>€氱煡锛?5s
+- 同步响应：<100ms ✅
+- 数据拉取：<2s
+- 端到端通知：<5s
 
 **架构设计**:
 ```
-REDCap DET 鈫?Webhook鎺ユ敹鍣?鈫?绔嬪嵆杩斿洖200 OK
-                鈫?(寮傛<E5AFAE>)
+REDCap DET → Webhook接收器 → 立即返回200 OK
+                ↓ (异步)
            查找项目配置
-                鈫?           骞傜瓑鎬ф<E98EAC>鏌?                鈫?           鎷夊彇瀹屾暣鏁版嵁
-                鈫?           鎺ㄩ€佽川鎺ч槦鍒?                鈫?           璁板綍瀹¤<E780B9>鏃ュ織
+                ↓
+           幂等性检查
+                ↓
+           拉取完整数据
+                ↓
+           推送质控队列
+                ↓
+           记录审计日志
 ```
 
 ---
@@ -61,17 +80,21 @@ REDCap DET
 **文件**: `backend/src/modules/iit-manager/services/SyncManager.ts`
 
 **功能**:
-- 鉁?瀹氭椂杞<E6A482><E69D9E>锛堟瘡5鍒嗛挓锛?- 鉁?**澧為噺鍚屾<E98D9A>**锛氫娇鐢?`lastSyncAt`
-- 鉁?**骞跺彂澶勭悊澶氶」鐩?*
-- 鉁?鎵嬪姩鍚屾<E98D9A>鎺ュ彛锛坄manualSync`锛?- 鉁?鍏ㄩ噺鍚屾<E98D9A>鎺ュ彛锛坄fullSync`锛?- 鉁?瀹屾暣鐨勯敊璇<E6958A><E79287>鐞嗗拰鎭㈠<E98EAD>鏈哄埗
+- ✅ 定时轮询（每5分钟）
+- ✅ **增量同步**：使用 `lastSyncAt`
+- ✅ **并发处理多项目**
+- ✅ 手动同步接口（`manualSync`）
+- ✅ 全量同步接口（`fullSync`）
+- ✅ 完整的错误处理和恢复机制
 
 **使用场景**:
 - 内网环境无法接收Webhook
 - Webhook丢失时的兜底方案
 - 定期全量扫描
 
-**鎶€鏈<EFBFBD>寒鐐?*:
-- pg-boss 瀹氭椂浠诲姟锛圕ron: */5 * * * *锛?- 鎸夎<E98EB8>褰旾D鍘婚噸
+**技术亮点**:
+- pg-boss 定时任务（Cron: */5 * * * *）
+- 按记录ID去重
 - 失败自动重试
 - 审计日志记录
 
@@ -83,13 +106,13 @@ REDCap DET
 
 **路由列表**:
 
-| 鏂规硶 | 璺<>緞 | 鍔熻兘 | 鐘舵€?|
+| 方法 | 路径 | 功能 | 状态 |
 |-----|------|------|------|
-| GET | `/api/v1/iit/health` | 鍋ュ悍妫€鏌?| 鉁?|
-| POST | `/api/v1/iit/webhooks/redcap` | DET Webhook鎺ユ敹鍣?| 鉁?|
-| POST | `/api/v1/iit/projects/:id/sync` | 鎵嬪姩瑙﹀彂鍚屾<EFBFBD> | 鉁?|
-| POST | `/api/v1/iit/projects/:id/full-sync` | 鍏ㄩ噺鍚屾<EFBFBD> | 鉁?|
-| GET | `/api/v1/iit/webhooks/health` | Webhook鍋ュ悍妫€鏌?| 鉁?|
+| GET | `/api/v1/iit/health` | 健康检查 | ✅ |
+| POST | `/api/v1/iit/webhooks/redcap` | DET Webhook接收器 | ✅ |
+| POST | `/api/v1/iit/projects/:id/sync` | 手动触发同步 | ✅ |
+| POST | `/api/v1/iit/projects/:id/full-sync` | 全量同步 | ✅ |
+| GET | `/api/v1/iit/webhooks/health` | Webhook健康检查 | ✅ |
 
 ---
 
@@ -98,7 +121,9 @@ REDCap DET
 **文件**: `backend/src/modules/iit-manager/index.ts`
 
 **Worker列表**:
-- 鉁?`iit:redcap:poll` - 瀹氭椂杞<EFBFBD><EFBFBD>浠诲姟锛堟瘡5鍒嗛挓锛?- 馃敎 `iit:quality-check` - 璐ㄦ帶浠诲姟锛圥hase 1.5锛?
+- ✅ `iit:redcap:poll` - 定时轮询任务（每5分钟）
+- 🔜 `iit:quality-check` - 质控任务（Phase 1.5）
+
 ---
 
 ### 6. 测试脚本
@@ -108,10 +133,13 @@ REDCap DET
 **文件**: `backend/src/modules/iit-manager/test-redcap-api.ts`
 
 **测试内容**:
-- 鉁?鍒涘缓 Adapter 瀹炰緥
-- 鉁?娴嬭瘯API杩炴帴
-- 鉁?瀵煎嚭鍏冩暟鎹?- 鉁?瀵煎嚭鎵€鏈夎<E98F88>褰?- 鉁?瀵煎嚭鎸囧畾璁板綍
-- 鉁?澧為噺鍚屾<E98D9A>娴嬭瘯锛堟渶杩?灏忔椂锛?
+- ✅ 创建 Adapter 实例
+- ✅ 测试API连接
+- ✅ 导出元数据
+- ✅ 导出所有记录
+- ✅ 导出指定记录
+- ✅ 增量同步测试（最近1小时）
+
 **运行方式**:
 ```bash
 cd backend
@@ -123,8 +151,14 @@ npm run tsx src/modules/iit-manager/test-redcap-api.ts
 **文件**: `backend/src/modules/iit-manager/test-redcap-webhook.ts`
 
 **测试内容**:
-- 鉁?Webhook鍋ュ悍妫€鏌?- 鉁?妫€鏌ラ」鐩<E3808D>厤缃?- 鉁?鍙戦€佹祴璇昗ebhook
-- 鉁?楠岃瘉鍝嶅簲鏃堕棿锛?100ms锛?- 鉁?妫€鏌ュ<E98F8C>璁℃棩蹇?- 鉁?娴嬭瘯骞傜瓑鎬?- 鉁?娴嬭瘯鏃犳晥Webhook锛?00閿欒<E996BF>锛?
+- ✅ Webhook健康检查
+- ✅ 检查项目配置
+- ✅ 发送测试Webhook
+- ✅ 验证响应时间（<100ms）
+- ✅ 检查审计日志
+- ✅ 测试幂等性
+- ✅ 测试无效Webhook（400错误）
+
 **运行方式**:
 ```bash
 cd backend
@@ -136,12 +170,19 @@ npm run tsx src/modules/iit-manager/test-redcap-webhook.ts
 **文件**: `backend/src/modules/iit-manager/test-redcap-integration.ts`
 
 **测试内容**:
-- 鉁?鍚庣<E98D9A>鏈嶅姟妫€鏌?- 鉁?鏁版嵁搴撻厤缃<E58EA4><E7BC83>鏌?- 鉁?REDCap API杩炴帴
-- 鉁?鍏冩暟鎹<E69A9F>幏鍙?- 鉁?璁板綍鑾峰彇
-- 鉁?Webhook鎺ユ敹鍣ㄦ祴璇?- 鉁?寮傛<E5AFAE>澶勭悊楠岃瘉
-- 鉁?瀹¤<E780B9>鏃ュ織妫€鏌?- 鉁?澧為噺鍚屾<E98D9A>娴嬭瘯
-- 鉁?鎵嬪姩鍚屾<E98D9A>鎺ュ彛娴嬭瘯
-- 鉁?Webhook鍋ュ悍妫€鏌?- 鉁?骞傜瓑鎬ф祴璇?
+- ✅ 后端服务检查
+- ✅ 数据库配置检查
+- ✅ REDCap API连接
+- ✅ 元数据获取
+- ✅ 记录获取
+- ✅ Webhook接收器测试
+- ✅ 异步处理验证
+- ✅ 审计日志检查
+- ✅ 增量同步测试
+- ✅ 手动同步接口测试
+- ✅ Webhook健康检查
+- ✅ 幂等性测试
+
 **运行方式**:
 ```bash
 cd backend
@@ -152,7 +193,8 @@ npm run tsx src/modules/iit-manager/test-redcap-integration.ts
 
 ## 🔧 环境配置
 
-### REDCap 閰嶇疆锛堝凡瀹屾垚锛?
+### REDCap 配置（已完成）
+
 **项目信息**:
 - 项目名称: test0102
 - 项目ID (PID): 16
@@ -200,38 +242,48 @@ INSERT INTO iit_schema.projects (
 
 ## 📊 与文档的对比
 
-### 鉁?瀹屽叏绗﹀悎鐨勫湴鏂?
-1. **鎶€鏈<E282AC>柟妗?*: DET + REST API锛堜笉浣跨敤External Modules锛?2. **娣峰悎妯″紡**: Webhook瀹炴椂瑙﹀彂 + 杞<><E69D9E>鍏滃簳
-3. **鏍稿績閫昏緫**: 骞傜瓑鎬с€佸紓姝ュ<EFBFBD>鐞嗐€佸<EFBFBD>閲忓悓姝?4. **浠ｇ爜缁撴瀯**: Adapter銆丆ontroller銆丼ervice鍒嗗眰娓呮櫚
-5. **鎬ц兘鐩<EFBFBD>爣**: <100ms鍝嶅簲銆?s绔<73>埌绔?
-### 馃殌 瓒呰秺鏂囨。鐨勫湴鏂?
-1. **鏇村己澶х殑閿欒<EFBFBD>澶勭悊**: 杩炴帴娴嬭瘯銆佸弸濂介敊璇<E6958A>俊鎭?2. **鏇村畬鍠勭殑鏃ュ織**: 鎬ц兘鐩戞帶銆佽<E98A86>缁嗕笂涓嬫枃
+### ✅ 完全符合的地方
+
+1. **技术方案**: DET + REST API（不使用External Modules）
+2. **混合模式**: Webhook实时触发 + 轮询兜底
+3. **核心逻辑**: 幂等性、异步处理、增量同步
+4. **代码结构**: Adapter、Controller、Service分层清晰
+5. **性能目标**: <100ms响应、5s端到端
+
+### 🚀 超越文档的地方
+
+1. **更强大的错误处理**: 连接测试、友好错误信息
+2. **更完善的日志**: 性能监控、详细上下文
 3. **更灵活的同步**: 手动同步、全量同步、并发处理多项目
 4. **更完善的测试**: API测试、Webhook测试、集成测试（12项测试）
-5. **鏇村ソ鐨勪唬鐮佽川閲?*: 璇︾粏娉ㄩ噴銆佺被鍨嬪畾涔夈€丼chema楠岃瘉
+5. **更好的代码质量**: 详细注释、类型定义、Schema验证
 
-### 鈿狅笍 淇<><E6B787>鐨勫湴鏂?
-1. **鏁版嵁搴撳瓧娈靛悕**: 鏂囨。鐢?`snake_case`锛屽疄闄匰chema鐢?`camelCase`
-   - `redcap_api_token` 鈫?`redcapApiToken`
-   - `redcap_api_base_url` 鈫?`redcapUrl`
-   - `sync_enabled` 鈫?锛堟殏鏈<E6AE8F>湪Schema涓<61>畾涔夛級
+### ⚠️ 修正的地方
 
-2. **琛ㄥ悕**: 鏂囨。鐢?`projects`锛屽疄闄呯敤 `IitProject`
+1. **数据库字段名**: 文档用 `snake_case`，实际Schema用 `camelCase`
+   - `redcap_api_token` → `redcapApiToken`
+   - `redcap_api_base_url` → `redcapUrl`
+   - `sync_enabled` → （暂未在Schema中定义）
 
-3. **瀹¤<EFBFBD>鏃ュ織瀛楁<EFBFBD>**: 鏂囨。鐢?`operation_type`锛屽疄闄呯敤 `actionType`
+2. **表名**: 文档用 `projects`，实际用 `IitProject`
+
+3. **审计日志字段**: 文档用 `operation_type`，实际用 `actionType`
 
 ---
 
 ## 🔍 Linter 错误修复
 
-淇<EFBFBD><EFBFBD>浜嗕互涓嬬被鍨嬬殑閿欒<EFBFBD>锛?
-1. 鉁?**妯″潡瀵煎叆璺<E58F86>緞**: 绉婚櫎 `.js` 鎵╁睍鍚嶏紙TypeScript瀵煎叆瑙勮寖锛?2. 鉁?**鏁版嵁搴撳瓧娈靛悕**: 缁熶竴涓?camelCase
-3. 鉁?**绫诲瀷閿欒<E996BF>**: 娣诲姞鏄惧紡绫诲瀷娉ㄨВ
-4. 鉁?**JSON绫诲瀷**: 浣跨敤 `JSON.parse(JSON.stringify())` 杞<>崲
+修复了以下类型的错误：
+
+1. ✅ **模块导入路径**: 移除 `.js` 扩展名（TypeScript导入规范）
+2. ✅ **数据库字段名**: 统一为 camelCase
+3. ✅ **类型错误**: 添加显式类型注解
+4. ✅ **JSON类型**: 使用 `JSON.parse(JSON.stringify())` 转换
 
 ---
 
-## 馃摑 涓嬩竴姝ュ伐浣滐紙Day 3锛?
+## 📝 下一步工作（Day 3）
+
 ### Phase 1.5: 数据质控Agent
 
 1. **质控Worker注册**:
@@ -240,37 +292,45 @@ INSERT INTO iit_schema.projects (
 
 2. **Dify RAG集成**:
    - 集成 Dify Client
-   - 鏌ヨ<EFBFBD>鐮旂┒鏂规<EFBFBD>鐭ヨ瘑搴?
+   - 查询研究方案知识库
+
 3. **质控规则引擎**:
    - 实现基础质控规则
    - 生成质控意见
 
 4. **企业微信通知**:
-   - 鍙戦€佽川鎺у崱鐗?   - 鍖呭惈锛氳<E9949B>褰曚俊鎭<E4BF8A>€佽川鎺ч棶棰樸€佸缓璁<E7BC93>搷浣?
-5. **褰卞瓙鐘舵€佺<E282AC>鐞?*:
+   - 发送质控卡片
+   - 包含：记录信息、质控问题、建议操作
+
+5. **影子状态管理**:
    - 创建 PendingAction
-   - 鐘舵€侊細PROPOSED 鈫?APPROVED 鈫?EXECUTED
+   - 状态：PROPOSED → APPROVED → EXECUTED
 
 ---
 
 ## 🎉 总结
 
-Day 2 鐨勫紑鍙戜换鍔?*鍏ㄩ儴瀹屾垚**锛佹垜浠<E59E9C>垚鍔熷疄鐜颁簡锛?
-鉁?**瀹屾暣鐨凴EDCap瀵规帴鑳藉姏**  
-鉁?**娣峰悎鍚屾<E98D9A>妯″紡锛圵ebhook + 杞<><E69D9E>锛?*  
-鉁?**鏋侀€熷搷搴旂殑Webhook鎺ユ敹鍣<E695B9>紙<100ms锛?*  
-鉁?**瀹屽杽鐨勬祴璇曡剼鏈?*  
-鉁?**绗﹀悎涓旇秴瓒婃妧鏈<E5A6A7>枃妗ｇ殑瀹炵幇**  
+Day 2 的开发任务**全部完成**！我们成功实现了：
+
+✅ **完整的REDCap对接能力**  
+✅ **混合同步模式（Webhook + 轮询）**  
+✅ **极速响应的Webhook接收器（<100ms）**  
+✅ **完善的测试脚本**  
+✅ **符合且超越技术文档的实现**  
 
 **代码质量**:
 - 详细的注释和文档
-- 瀹屾暣鐨勯敊璇<EFBFBD><EFBFBD>鐞?- 鎬ц兘鐩戞帶鍜屾棩蹇?- 绫诲瀷瀹夊叏
-- 鍙<EFBFBD>祴璇曟€?
-**涓嬩竴姝?*: 鍑嗗<E98D91>娴嬭瘯鐜<E798AF><E9909C>锛岃繍琛屾祴璇曡剼鏈<E589BC>紝楠岃瘉绔<E79889>埌绔<E59F8C>姛鑳斤紒
+- 完整的错误处理
+- 性能监控和日志
+- 类型安全
+- 可测试性
+
+**下一步**: 准备测试环境，运行测试脚本，验证端到端功能！
 
 ---
 
-**寮€鍙戞椂闂?*: ~2灏忔椂  
-**浠ｇ爜琛屾暟**: ~1,500琛? 
-**娴嬭瘯瑕嗙洊**: 12椤归泦鎴愭祴璇? 
-**鏂囨。璐ㄩ噺**: 猸愨瓙猸愨瓙猸?
+**开发时间**: ~2小时  
+**代码行数**: ~1,500行  
+**测试覆盖**: 12项集成测试  
+**文档质量**: ⭐⭐⭐⭐⭐
+

docs/03-业务模块/IIT Manager 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的技术基石文档，请妥善保管！** ⭐⭐⭐⭐⭐
 
 
 

docs/03-业务模块/IIT Manager Agent/04-开发计划/企业微信注册指南.md

@@ -1,11 +1,11 @@
-# 隡<EFBFBD><EFBFBD>敺桐縑瘜典<EFBFBD>銝𡡞<EFBFBD>蝵格<EFBFBD><EFBFBD>?
+# 企业微信注册与配置指南
 
-> **<EFBFBD>格<EFBFBD>**嚗朞繮<E69C9E>碶<EFBFBD>銝𡁜凝靽，PI<50>剛<EFBFBD>嚗𣬚鍂鈭穉IT Manager Agent<EFBFBD>煾<EFBFBD><EFBFBD>捶<EFBFBD>折<EFBFBD>霅血㨃<EFBFBD>? 
-> **憸<EFBFBD>恣<EFBFBD>園𡢿**嚗?0<><30><EFBFBD>
+> **目标**：获取企业微信API凭证，用于IIT Manager Agent发送质控预警卡片  
+> **预计时间**：20分钟
 
 ---
 
-## <EFBFBD><EFBFBD> 甇仿炊1嚗𡁏釣<F0A1818F>䔶<EFBFBD>銝𡁜凝靽∟揭<E2889F>?
+## 📋 步骤1：注册企业微信账号
 
 ### 1.1 访问企业微信官网
 
@@ -15,28 +15,28 @@
 
 1. 点击"**立即注册**"
 2. 选择"**企业**"类型
-3. 憛怠<EFBFBD>隡<EFBFBD><EFBFBD>靽⊥<EFBFBD>嚗?
-   - 隡<EFBFBD><EFBFBD><EFBFBD>滨妍嚗䫤瘚贝<EFBFBD><EFBFBD>駁堺`嚗<><E59A97><EFBFBD>函<EFBFBD>摰鮋<E691B0><E9AE8B>箸<EFBFBD><E7AEB8>滨妍嚗?
+3. 填写企业信息：
+   - 企业名称：`测试医院`（或您的实际机构名称）
    - 行业类型：`医疗健康`
    - 企业人数：`100人以下`
    - 管理员姓名：您的姓名
    - 管理员手机：您的手机号（接收验证码）
-4. 摰峕<EFBFBD>撉諹<EFBFBD>嚗峕釣<EFBFBD>峕<EFBFBD><EFBFBD>?
+4. 完成验证，注册成功
 
 ---
 
-## <EFBFBD><EFBFBD> 甇仿炊2嚗𡁜<E59A97>撱箄䌊撱箏<E692B1><E7AE8F>?
+## 📋 步骤2：创建自建应用
 
 ### 2.1 登录管理后台
 
 1. 访问：https://work.weixin.qq.com/wework_admin/loginpage_wx
-2. 雿輻鍂隡<EFBFBD><EFBFBD>敺桐縑APP<EFBFBD>怎<EFBFBD><EFBFBD>餃<EFBFBD>嚗<EFBFBD><EFBFBD><EFBFBD><EFBFBD>銁<EFBFBD>𧢲㦤銝𠹺<EFBFBD>頧賭<EFBFBD>銝𡁜凝靽，PP嚗?
+2. 使用企业微信APP扫码登录（需先在手机上下载企业微信APP）
 
 ### 2.2 创建应用
 
-1. 餈𥕦<EFBFBD>**<2A>𣂼<EFBFBD><F0A382BC>函恣<E587BD><E681A3><EFBFBD>?* <20>?**<2A>鞱䌊撱箝<E692B1>?* <20>?**<2A>𣂼<EFBFBD>撱箏<E692B1><E7AE8F>具<EFBFBD>?*
+1. 进入**【应用管理】** → **【自建】** → **【创建应用】**
 
-2. 憛怠<EFBFBD>摨𠉛鍂靽⊥<EFBFBD>嚗?
+2. 填写应用信息：
    - **应用名称**：`IIT Manager Agent（测试）`
    - **应用Logo**：上传一个图标（可暂时使用默认）
    - **应用介绍**：`IIT研究智能质控助手 - 数据质量实时监控`
@@ -44,19 +44,19 @@
 
 3. 点击"**创建应用**"
 
-### 2.3 <EFBFBD>瑕<EFBFBD>API<EFBFBD>剛<EFBFBD>嚗<EFBFBD><EFBFBD>閬<EFBFBD><EFBFBD>嚗?
+### 2.3 获取API凭证（重要！）
 
-<EFBFBD>𥕦遣<EFBFBD>𣂼<EFBFBD><EFBFBD>𠬍<EFBFBD><EFBFBD>典<EFBFBD><EFBFBD>刻祕<EFBFBD><EFBFBD>△<EFBFBD>臭誑<EFBFBD>见<EFBFBD>嚗?
+创建成功后，在应用详情页可以看到：
 
 ```
 企业ID（CorpID）：  ww1234567890abcdef
-AgentID嚗?          1000002
-Secret嚗?           <EFBFBD>孵稬"<22>亦<EFBFBD>"<22>厰僼<E58EB0>亦<EFBFBD>
+AgentID：           1000002
+Secret：            点击"查看"按钮查看
 ```
 
-**<EFBFBD>𩤃<EFBFBD> <20>滩<EFBFBD><E6BBA9>鞟內**嚗?
+**⚠️ 重要提示**：
 - **Secret** 只显示一次，请立即复制保存！
-- 憒<EFBFBD><EFBFBD>敹䁅扇Secret嚗屸<EFBFBD>閬<EFBFBD><EFBFBD>蝵殷<EFBFBD>隡𡁜紡<EFBFBD>湔唂Secret憭望<EFBFBD>嚗?
+- 如果忘记Secret，需要重置（会导致旧Secret失效）
 
 ---
 
@@ -64,10 +64,10 @@ Secret
 
 ### 3.1 设置网页授权及JS-SDK
 
-1. <EFBFBD>典<EFBFBD><EFBFBD>刻祕<EFBFBD><EFBFBD>△嚗峕𪄳<EFBFBD>?**蝵煾△<E785BE><E296B3><EFBFBD><EFBFBD>蹆S-SDK**"
-2. 霈曄蔭**<2A>臭縑<E887AD>笔<EFBFBD>**嚗?
+1. 在应用详情页，找到"**网页授权及JS-SDK**"
+2. 设置**可信域名**：
    - 开发环境：`localhost`（如果支持）
-   - <EFBFBD>煺漣<EFBFBD>臬<EFBFBD>嚗𡁏<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>㵪<EFBFBD>憒?`iit.example.com`嚗?
+   - 生产环境：您的实际域名（如 `iit.example.com`）
 
 ### 3.2 设置接收消息
 
@@ -77,13 +77,13 @@ Secret
 ### 3.3 设置权限范围
 
 确保应用有以下权限：
-- <EFBFBD>?**<2A>煾<EFBFBD><E785BE><EFBFBD><EFBFBD>臬<EFBFBD>敺桐縑** - <EFBFBD>詨<EFBFBD><EFBFBD>蠘<EFBFBD>
-- <EFBFBD>?**<2A>𣂼<EFBFBD>靽⊥<E99DBD>霂餃<E99C82>** - <EFBFBD>其<EFBFBD><EFBFBD>瑕<EFBFBD><EFBFBD>冽<EFBFBD>OpenID
-- <EFBFBD>?**<2A>朞悖敶閧恣<E996A7>?* - <20>其<EFBFBD><E585B6>冽<EFBFBD><E586BD>惩<EFBFBD>
+- ✅ **发送消息到微信** - 核心功能
+- ✅ **成员信息读取** - 用于获取用户OpenID
+- ✅ **通讯录管理** - 用于用户映射
 
 ---
 
-## <EFBFBD><EFBFBD> 甇仿炊4嚗𡁻<E59A97>蝵桀<E89DB5>憿寧𤌍銝?
+## 📋 步骤4：配置到项目中
 
 ### 4.1 复制凭证
 
@@ -95,7 +95,7 @@ AgentID:    1000002
 Secret:     abc123xyz789_your_secret_here
 ```
 
-### 4.2 瘛餃<EFBFBD><EFBFBD>?.env <EFBFBD><EFBFBD>辣
+### 4.2 添加到 .env 文件
 
 编辑 `AIclinicalresearch/backend/.env`，添加：
 
@@ -106,9 +106,9 @@ WECHAT_CORP_SECRET=abc123xyz789_your_secret_here
 WECHAT_AGENT_ID=1000002
 ```
 
-**<EFBFBD>𩤃<EFBFBD> 瘜冽<E7989C>**嚗?
-- 銝滩<EFBFBD><EFBFBD>𣂷漱 `.env` <EFBFBD><EFBFBD>辣<EFBFBD>蚣it嚗<EFBFBD>歇<EFBFBD>?`.gitignore` 銝哨<EFBFBD>
-- <EFBFBD>煺漣<EFBFBD>臬<EFBFBD>雿輻鍂<EFBFBD>祉<EFBFBD><EFBFBD><EFBFBD><EFBFBD>銝𡁜凝靽∪<EFBFBD><EFBFBD>?
+**⚠️ 注意**：
+- 不要提交 `.env` 文件到Git（已在 `.gitignore` 中）
+- 生产环境使用独立的企业微信应用
 
 ---
 
@@ -116,18 +116,18 @@ WECHAT_AGENT_ID=1000002
 
 ### 5.1 重启后端服务
 
-靽嘥<EFBFBD> `.env` <EFBFBD>𠬍<EFBFBD><EFBFBD>滚鍳<EFBFBD>𡒊垢嚗?
+保存 `.env` 后，重启后端：
 
 ```bash
-# <EFBFBD>𨀣迫敶枏<EFBFBD><EFBFBD>滚𦛚嚗㇃trl+C嚗?
+# 停止当前服务（Ctrl+C）
 # 重新启动
 cd D:\MyCursor\AIclinicalresearch\backend
 npm run dev
 ```
 
-### 5.2 <EFBFBD>见𢆡瘚贝<EFBFBD>嚗<EFBFBD>蝙<EFBFBD>沌ostman<EFBFBD>鈪url嚗?
+### 5.2 手动测试（使用Postman或curl）
 
-**瘚贝<EFBFBD>蝡舐<EFBFBD>**嚗<><E59A97>蝏胖ay 5隡𡁜<E99AA1>撱綽<E692B1>嚗?
+**测试端点**（后续Day 5会创建）：
 
 ```bash
 POST http://localhost:3001/api/v1/iit/test/wechat-push
@@ -136,73 +136,73 @@ Content-Type: application/json
 {
   "toUser": "YourUserID",
   "title": "测试通知",
-  "description": "餈蹱糓銝<EFBFBD><EFBFBD>⊥䔉<EFBFBD>杷IT Manager<EFBFBD><EFBFBD><EFBFBD>霂閙<EFBFBD><EFBFBD>?,
+  "description": "这是一条来自IIT Manager的测试消息",
   "url": "http://localhost:5173"
 }
 ```
 
-**憸<EFBFBD><EFBFBD>蝏𤘪<EFBFBD>**嚗?
-- <EFBFBD>?餈𥪜<E9A488>200<30>嗆<EFBFBD><E59786><EFBFBD>
-- <EFBFBD>?隡<><E99AA1>敺桐縑APP<50>嗅<EFBFBD><E59785>∠<EFBFBD>瘨<EFBFBD><E798A8>
+**预期结果**：
+- ✅ 返回200状态码
+- ✅ 企业微信APP收到卡片消息
 
 ---
 
-## <EFBFBD><EFBFBD> 撣貉<E692A3><E8B289>桅<EFBFBD>嚗㇅AQ嚗?
+## 📋 常见问题（FAQ）
 
-### Q1嚗𡁏<EFBFBD>瘝⊥<EFBFBD>隡<EFBFBD><EFBFBD>嚗<EFBFBD>虾隞交釣<EFBFBD><EFBFBD><EFBFBD>嚗?
+### Q1：我没有企业，可以注册吗？
 
-**A**嚗𡁜虾隞伐<E99A9E><E4BC90>㗇𥋘"**銝芯犖**"<22>?**銝芯<E98A9D>撌亙<E6928C><E4BA99>?*"蝐餃<E89D90>瘜典<E7989C>嚗<EFBFBD><E59A97><EFBFBD>賢<EFBFBD><E8B3A2>函㮾<E587BD>䎚<EFBFBD>?
+**A**：可以！选择"**个人**"或"**个体工商户**"类型注册，功能完全相同。
 
 ### Q2：Secret忘记了怎么办？
 
-**A**嚗𡁜銁摨𠉛鍂霂行<E99C82>憿萇<E686BF><E89087>?**<EFBFBD>滨蔭Secret**"嚗䔶<E59A97>隡𡁜紡<F0A1819C>湔唂Secret憭望<EFBFBD><EFBFBD>?
+**A**：在应用详情页点击"**重置Secret**"，但会导致旧Secret失效。
 
-### Q3嚗𡁏<EFBFBD>霂閧㴓憓<EFBFBD><EFBFBD>閬<EFBFBD><EFBFBD><EFBFBD>滩恕霂<EFBFBD><EFBFBD>嚗?
+### Q3：测试环境需要实名认证吗？
 
-**A**嚗帋<E59A97><E5B88B><EFBFBD>閬<EFBFBD><E996AC><EFBFBD>𧊋霈方<E99C88>隡<EFBFBD><E99AA1>銋笔虾隞乩蝙<E4B9A9>刻䌊撱箏<E692B1><E7AE8F>函<EFBFBD><E587BD>券<EFBFBD><E588B8>蠘<EFBFBD>嚗<EFBFBD>蘨<EFBFBD>臭犖<E887AD>唳<EFBFBD><E594B3>𣂼<EFBFBD>嚗?00鈭綽<E988AD><E7B6BD>?
+**A**：不需要。未认证企业也可以使用自建应用的全部功能，只是人数有限制（100人）。
 
-### Q4嚗𡁜<EFBFBD>雿閙𪄳<EFBFBD>啁鍂<EFBFBD>瑞<EFBFBD> UserID嚗?
+### Q4：如何找到用户的 UserID？
 
-**A**嚗?
-1. <EFBFBD>寞<EFBFBD>1嚗𡁶蒈敶閧恣<EFBFBD><EFBFBD><EFBFBD><EFBFBD>?<3F>?<3F>朞悖敶?<3F>?<3F>孵稬<E5ADB5>𣂼<EFBFBD> <20>?<3F>亦<EFBFBD>"韐血噡"
+**A**：
+1. 方法1：登录管理后台 → 通讯录 → 点击成员 → 查看"账号"
 2. 方法2：调用企业微信API获取：`GET /cgi-bin/user/getuserinfo`
 
-### Q5嚗𡁏<EFBFBD><EFBFBD>臬<EFBFBD><EFBFBD><EFBFBD>仃韐伐<EFBFBD>餈𥪜<EFBFBD>40014<EFBFBD>躰秤嚗?
+### Q5：消息发送失败，返回40014错误？
 
 **A**：`invalid access_token`，可能原因：
 - Secret配置错误
-- Access Token餈<EFBFBD><EFBFBD>嚗<EFBFBD><EFBFBD><EFBFBD>齿鰵<EFBFBD>瑕<EFBFBD>嚗?
+- Access Token过期（需重新获取）
 - CorpID或AgentID配置错误
 
 ---
 
-## <EFBFBD>?撉峕𤣰<E5B395><F0A4A3B0><EFBFBD>
+## ✅ 验收标准
 
-摰峕<EFBFBD>隞乩<EFBFBD>隞餃𦛚<EFBFBD>𠬍<EFBFBD>Day 1撠勗<E692A0>蝢擧𤣰摰䀝<E691B0>嚗?
+完成以下任务后，Day 1就完美收官了：
 
 - [ ] 企业微信账号注册成功
 - [ ] 自建应用创建成功
 - [ ] 获取到CorpID、AgentID、Secret
-- [ ] <20>滨蔭<E6BBA8>?`.env` <20><>辣
+- [ ] 配置到 `.env` 文件
 - [ ] 后端服务能正常启动（无报错）
 
 ---
 
-## <EFBFBD>㴓 銝衤<E98A9D>甇?
+## 🎯 下一步
 
 完成企业微信配置后，Day 2我们将开始：
 
-1. **REDCap API Adapter撘<EFBFBD><EFBFBD>?*嚗<>瓲敹<E793B2><E695B9><EFBFBD>踝<EFBFBD>
-2. **SyncManager撘<EFBFBD><EFBFBD>?*嚗<>毽<EFBFBD><E6AFBD><EFBFBD>甇交芋撘𧶏<E69298>
-3. 摰䂿緵REDCap<EFBFBD>唳旿<EFBFBD>匧<EFBFBD><EFBFBD>諹蔭霂?
+1. **REDCap API Adapter开发**（核心功能）
+2. **SyncManager开发**（混合同步模式）
+3. 实现REDCap数据拉取和轮询
 
-憸<EFBFBD>恣摰峕<EFBFBD><EFBFBD>園𡢿嚗?撠𤩺𧒄
+预计完成时间：8小时
 
 ---
 
-**<EFBFBD>𥕦遣<EFBFBD>交<EFBFBD>**嚗?025-12-31  
-**蝏湔擪<EFBFBD>?*嚗𡁜<E59A97><F0A1819C>穃𣪧<E7A983>? 
-**<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>獢?*嚗?
+**创建日期**：2025-12-31  
+**维护者**：开发团队  
+**参考文档**：
 - 企业微信官方文档：https://developer.work.weixin.qq.com/document/
 - 发送应用消息：https://developer.work.weixin.qq.com/document/path/90236
 
@@ -225,6 +225,5 @@ Content-Type: application/json
 
 
 
-