Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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
This commit is contained in:
HaHafeng
2026-01-16 13:42:10 +08:00
parent 98d862dbd4
commit 66255368b7
560 changed files with 70424 additions and 52353 deletions
Download Patch File Download Diff File Expand all files Collapse all files

156
docs/03-业务模块/Redcap/00-模块概览/00-REDCap模块文档导航.md
View File

@@ -1,75 +1,75 @@
# REDCap模块文档导航
**最后更新：** 2026-01-02
**妯″潡绫诲瀷锛?* 绗<>笁鏂圭郴缁熼泦鎴愪笌浜屾<E6B59C>寮€鍙?
**模块类型：** 第三方系统集成与二次开发
**当前状态：** 本地Docker环境已部署，API Adapter开发中
---
## 📚 文档体系说明
REDCap鏄<EFBFBD>竴涓<EFBFBD>垚鐔熺殑绗<EFBFBD>笁鏂笶DC锛堢數瀛愭暟鎹<EFBFBD>噰闆嗭級绯荤粺锛屾湰妯″潡鐨勫伐浣滈噸鐐规槸锛?
1. **閮ㄧ讲涓庨厤缃?*锛氬湪涓嶅悓鐜<E68293><E9909C>锛堝紑鍙?鐢熶骇/鍖婚櫌锛夐儴缃睷EDCap
REDCap是一个成熟的第三方EDC（电子数据采集）系统，本模块的工作重点是：
1. **部署与配置**：在不同环境（开发/生产/医院）部署REDCap
2. **API对接**：通过REDCap API与IIT Manager Agent集成
3. **杩愮淮绠＄悊**锛氭棩甯哥淮鎶ゃ€佸<E282AC>浠姐€佸崌绾?
3. **运维管理**：日常维护、备份、升级
鍥犳<EFBFBD>锛屾枃妗ｆ灦鏋勪笌鑷<EFBFBD>爺妯″潡锛圓SL銆丏C锛変笉鍚岋紝鏇翠晶閲嶉儴缃蹭笌闆嗘垚銆?
因此，文档架构与自研模块（ASL、DC）不同，更侧重部署与集成。
---
## 📖 文档目录
### 1锔忊儯 **绯荤粺姒傝<E5A792>涓庡喅绛?*
### 1️⃣ **系统概览与决策**
#### [01-REDCap系统介绍与选型说明.md](./01-REDCap系统介绍与选型说明.md)
- REDCap是什么？
- 涓轰粈涔堥€夋嫨REDCap锛?
- REDCap鐨勬牳蹇冨姛鑳?
- 为什么选择REDCap？
- REDCap的核心功能
- REDCap在IIT Manager中的角色
#### [02-REDCap瀵规帴鎬讳綋鏂规<EFBFBD>.md](./02-REDCap瀵规帴鎬讳綋鏂规<EFBFBD>.md) 鉁?
- 鎶€鏈<EFBFBD>灦鏋勮<EFBFBD>璁?
#### [02-REDCap对接总体方案.md](./02-REDCap对接总体方案.md) ✅
- 技术架构设计
- API对接方案
- 数据流转方案
- 瀹夊叏鎬ц<EFBFBD>璁?
- 安全性设计
#### [03-REDCap瀵规帴椋庨櫓璇勪及涓庢妧鏈<EFBFBD>寫鎴樺垎鏋?md](./03-REDCap瀵规帴椋庨櫓璇勪及涓庢妧鏈<E5A6A7>寫鎴樺垎鏋?md) 鉁?
- 鎶€鏈<EFBFBD><EFBFBD>闄╄瘎浼?
#### [03-REDCap对接风险评估与技术挑战分析.md](./03-REDCap对接风险评估与技术挑战分析.md) ✅
- 技术风险评估
- 实施难度分析
- 替代方案对比
- 鏈€缁堝喅绛栧缓璁?
- 最终决策建议
#### [04-鐢熶骇鐜<EFBFBD><EFBFBD>閮ㄧ讲鍐崇瓥鎶ュ憡_ECS_vs_SAE.md](./04-鐢熶骇鐜<EFBFBD><EFBFBD>閮ㄧ讲鍐崇瓥鎶ュ憡_ECS_vs_SAE.md) 鉁?
#### [04-生产环境部署决策报告_ECS_vs_SAE.md](./04-生产环境部署决策报告_ECS_vs_SAE.md) ✅
- ECS vs SAE深度对比
- 成本分析
- 鎶€鏈<EFBFBD>彲琛屾€?
- 技术可行性
- 最终选型：ECS
---
### 2锔忊儯 **閮ㄧ讲涓庨厤缃?*
### 2️⃣ **部署与配置**
#### [10-鏈<EFBFBD>湴寮€鍙戠幆澧冮儴缃插畬鍏ㄦ寚鍗?md](./10-鏈<>湴寮€鍙戠幆澧冮儴缃插畬鍏ㄦ寚鍗?md) 猸?
- **蹇<EFBFBD>€熷紑濮?*锛堥€傚悎棣栨<E6A3A3>閮ㄧ讲锛?
#### [10-本地开发环境部署完全指南.md](./10-本地开发环境部署完全指南.md) ⭐
- **快速开始**（适合首次部署）
- Docker环境准备
- 涓€閿<EFBFBD>儴缃茶剼鏈<EFBFBD>娇鐢?
- 鍒濆<EFBFBD>鍖栭厤缃?
- 一键部署脚本使用
- 初始化配置
- 验证测试
- **关键参考文档！**
#### [11-鐢熶骇鐜<EFBFBD><EFBFBD>閮ㄧ讲瀹屽叏鎸囧崡_闃块噷浜慐CS.md](./11-鐢熶骇鐜<E9AA87><E9909C>閮ㄧ讲瀹屽叏鎸囧崡_闃块噷浜慐CS.md) 猸?
- **ECS鏈嶅姟鍣ㄩ厤缃?*
- Docker闀滃儚鏋勫缓涓庢帹閫?
#### [11-生产环境部署完全指南_阿里云ECS.md](./11-生产环境部署完全指南_阿里云ECS.md) ⭐
- **ECS服务器配置**
- Docker镜像构建与推送
- RDS MySQL配置
- 域名与SSL证书
- 瀹夊叏缁勪笌闃茬伀澧?
- 鐢熶骇鐜<EFBFBD><EFBFBD>妫€鏌ユ竻鍗?
- **鐢熶骇閮ㄧ讲蹇呰<EFBFBD>锛?*
- 安全组与防火墙
- 生产环境检查清单
- **生产部署必读！**
#### [12-鍖婚櫌绉佹湁鍖栭儴缃叉寚鍗?md](./12-鍖婚櫌绉佹湁鍖栭儴缃叉寚鍗?md) 馃彞
- 鍖婚櫌鏈嶅姟鍣ㄧ幆澧冭<EFBFBD>姹?
#### [12-医院私有化部署指南.md](./12-医院私有化部署指南.md) 🏥
- 医院服务器环境要求
- 内网部署方案
- 鏁版嵁瀹夊叏涓庡悎瑙?
- 数据安全与合规
- 技术支持与培训
#### [13-部署问题排查手册.md](./13-部署问题排查手册.md) 🔧
@@ -80,31 +80,31 @@ REDCap是一个成熟的第三方EDC（电子数据采集）系统，本模块
---
### 3锔忊儯 **閰嶇疆涓庣<E6B693>鐞?*
### 3️⃣ **配置与管理**
#### [20-REDCap系统配置手册.md](./20-REDCap系统配置手册.md)
- 鍩虹<EFBFBD>閰嶇疆锛圔ase URL銆侀偖浠舵湇鍔＄瓑锛?
- 鐢ㄦ埛涓庢潈闄愮<EFBFBD>鐞?
- 椤圭洰鍒涘缓涓庨厤缃?
- 基础配置（Base URL、邮件服务等）
- 用户与权限管理
- 项目创建与配置
- 数据字典设计
- 表单设计
#### [21-REDCap日常运维手册.md](./21-REDCap日常运维手册.md)
- 日常维护任务
- 澶囦唤涓庢仮澶?
- 备份与恢复
- 性能监控
- 日志管理
- 故障处理流程
#### [22-REDCap升级指南.md](./22-REDCap升级指南.md)
- 版本升级流程
- 鏁版嵁搴撹縼绉?
- 鍏煎<EFBFBD>鎬ф祴璇?
- 数据库迁移
- 兼容性测试
- 回滚方案
---
### 4锔忊儯 **API瀵规帴涓庡紑鍙?*
### 4️⃣ **API对接与开发**
#### [30-REDCap_API使用指南.md](./30-REDCap_API使用指南.md)
- REDCap API概述
@@ -118,21 +118,21 @@ REDCap是一个成熟的第三方EDC（电子数据采集）系统，本模块
- 接口设计
- 错误处理
#### [32-REDCap_API_Adapter寮€鍙戞寚鍗?md](./32-REDCap_API_Adapter寮€鍙戞寚鍗?md)
#### [32-REDCap_API_Adapter开发指南.md](./32-REDCap_API_Adapter开发指南.md)
- Adapter架构设计
- 代码结构
- 寮€鍙戣<EFBFBD>鑼?
- 开发规范
- 测试方案
#### [33-REDCap浜屾<EFBFBD>寮€鍙戞繁搴︽寚鍗?md](./33-REDCap浜屾<EFBFBD>寮€鍙戞繁搴︽寚鍗?md) 鉁?
- External Modules寮€鍙?
#### [33-REDCap二次开发深度指南.md](./33-REDCap二次开发深度指南.md) ✅
- External Modules开发
- Hooks机制
- 鎻掍欢寮€鍙?
- 鏈€浣冲疄璺?
- 插件开发
- 最佳实践
---
### 5锔忊儯 **鍙傝€冭祫鏂?*
### 5️⃣ **参考资料**
#### [40-REDCap官方资源索引.md](./40-REDCap官方资源索引.md)
- 官方文档链接
@@ -148,46 +148,46 @@ REDCap是一个成熟的第三方EDC（电子数据采集）系统，本模块
---
## 馃幆 蹇<>€熷叆鍙?
## 🎯 快速入口
### 我想部署REDCap
- **鏈<EFBFBD>湴寮€鍙戞祴璇?* 鈫?[10-鏈<>湴寮€鍙戠幆澧冮儴缃插畬鍏ㄦ寚鍗?md](./10-鏈<>湴寮€鍙戠幆澧冮儴缃插畬鍏ㄦ寚鍗?md)
- **闃块噷浜戠敓浜х幆澧?* 鈫?[11-鐢熶骇鐜<E9AA87><E9909C>閮ㄧ讲瀹屽叏鎸囧崡_闃块噷浜慐CS.md](./11-鐢熶骇鐜<E9AA87><E9909C>閮ㄧ讲瀹屽叏鎸囧崡_闃块噷浜慐CS.md)
- **鍖婚櫌绉佹湁鍖?* 鈫?[12-鍖婚櫌绉佹湁鍖栭儴缃叉寚鍗?md](./12-鍖婚櫌绉佹湁鍖栭儴缃叉寚鍗?md)
- **本地开发测试** → [10-本地开发环境部署完全指南.md](./10-本地开发环境部署完全指南.md)
- **阿里云生产环境** → [11-生产环境部署完全指南_阿里云ECS.md](./11-生产环境部署完全指南_阿里云ECS.md)
- **医院私有化** → [12-医院私有化部署指南.md](./12-医院私有化部署指南.md)
### 鎴戦亣鍒伴儴缃查棶棰?
- **闂<EFBFBD><EFBFBD>鎺掓煡** 鈫?[13-閮ㄧ讲闂<EFBFBD><EFBFBD>鎺掓煡鎵嬪唽.md](./13-閮ㄧ讲闂<E8AEB2><E99782>鎺掓煡鎵嬪唽.md)
- **鍘嗗彶闂<EFBFBD><EFBFBD>璁板綍** 鈫?[13-閮ㄧ讲闂<EFBFBD><EFBFBD>鎺掓煡鎵嬪唽.md](./13-閮ㄧ讲闂<E8AEB2><E99782>鎺掓煡鎵嬪唽.md)
### 我遇到部署问题
- **问题排查** → [13-部署问题排查手册.md](./13-部署问题排查手册.md)
- **历史问题记录** → [13-部署问题排查手册.md](./13-部署问题排查手册.md)
### 鎴戣<EFBFBD>杩涜<EFBFBD>API寮€鍙?
- **浜嗚ВAPI** 鈫?[30-REDCap_API浣跨敤鎸囧崡.md](./30-REDCap_API浣跨敤鎸囧崡.md)
- **瀵规帴璁捐<EFBFBD>** 鈫?[31-IIT_Manager涓嶳EDCap瀵规帴璁捐<EFBFBD>.md](./31-IIT_Manager涓嶳EDCap瀵规帴璁捐<EFBFBD>.md)
- **寮€鍙慉dapter** 鈫?[32-REDCap_API_Adapter寮€鍙戞寚鍗?md](./32-REDCap_API_Adapter寮€鍙戞寚鍗?md)
### 我要进行API开发
- **了解API** → [30-REDCap_API使用指南.md](./30-REDCap_API使用指南.md)
- **对接设计** → [31-IIT_Manager与REDCap对接设计.md](./31-IIT_Manager与REDCap对接设计.md)
- **开发Adapter** → [32-REDCap_API_Adapter开发指南.md](./32-REDCap_API_Adapter开发指南.md)
### 我要日常运维
- **绯荤粺閰嶇疆** 鈫?[20-REDCap绯荤粺閰嶇疆鎵嬪唽.md](./20-REDCap绯荤粺閰嶇疆鎵嬪唽.md)
- **鏃ュ父缁存姢** 鈫?[21-REDCap鏃ュ父杩愮淮鎵嬪唽.md](./21-REDCap鏃ュ父杩愮淮鎵嬪唽.md)
- **鐗堟湰鍗囩骇** 鈫?[22-REDCap鍗囩骇鎸囧崡.md](./22-REDCap鍗囩骇鎸囧崡.md)
- **系统配置** → [20-REDCap系统配置手册.md](./20-REDCap系统配置手册.md)
- **日常维护** → [21-REDCap日常运维手册.md](./21-REDCap日常运维手册.md)
- **版本升级** → [22-REDCap升级指南.md](./22-REDCap升级指南.md)
---
## 馃搳 妯″潡褰撳墠鐘舵€?
## 📊 模块当前状态
| 闃舵<EFBFBD> | 鐘舵€?| 瀹屾垚鏃堕棿 | 澶囨敞 |
| 阶段 | 状态 | 完成时间 | 备注 |
|------|------|----------|------|
| 鎶€鏈<EFBFBD>皟鐮?| 鉁?瀹屾垚 | 2025-12 | 瀹屾垚椋庨櫓璇勪及涓庢柟妗堣<E5A697>璁?|
| 閮ㄧ讲鏂规<EFBFBD>璁捐<EFBFBD> | 鉁?瀹屾垚 | 2026-01-01 | 纭<EFBFBD>畾Docker+ECS鏂规<EFBFBD> |
| 鏈<EFBFBD>湴鐜<EFBFBD><EFBFBD>閮ㄧ讲 | 鉁?瀹屾垚 | 2026-01-02 | REDCap 15.8.0杩愯<EFBFBD>姝ｅ父 |
| API Adapter寮€鍙?| 鈴?杩涜<E69DA9>涓?| 棰勮<E6A3B0>2026-01-03 | Day 2浠诲姟 |
| 鐢熶骇鐜<EFBFBD><EFBFBD>閮ㄧ讲 | 馃搮 璁″垝涓?| 寰呭畾 | 绛夊緟API Adapter瀹屾垚 |
| 技术调研 | ✅ 完成 | 2025-12 | 完成风险评估与方案设计 |
| 部署方案设计 | ✅ 完成 | 2026-01-01 | 确定Docker+ECS方案 |
| 本地环境部署 | ✅ 完成 | 2026-01-02 | REDCap 15.8.0运行正常 |
| API Adapter开发 | ⏳ 进行中 | 预计2026-01-03 | Day 2任务 |
| 生产环境部署 | 📅 计划中 | 待定 | 等待API Adapter完成 |
---
## 🔄 文档更新记录
| 鏃ユ湡 | 鏇存柊鍐呭<E98D90> | 鏇存柊浜?|
| 日期 | 更新内容 | 更新人 |
|------|----------|--------|
| 2026-01-02 | 鍒涘缓鏂囨。浣撶郴锛屽畬鎴愭湰鍦伴儴缃?| AI Assistant |
| 2026-01-02 | 创建文档体系，完成本地部署 | AI Assistant |
| 2025-12-XX | 完成技术方案与风险评估文档 | AI Assistant |
---
@@ -195,25 +195,25 @@ REDCap是一个成熟的第三方EDC（电子数据采集）系统，本模块
## 📝 文档编写规范
### 图标使用规范
- 猸?鏍稿績蹇呰<E8B987>鏂囨。
- 鉁?宸插畬鎴?
- 鈴?杩涜<E69DA9>涓?
- 馃搮 璁″垝涓?
- ⭐ 核心必读文档
- ✅ 已完成
- ⏳ 进行中
- 📅 计划中
- 🔧 故障排查
- 🏥 医院专用
- 馃挕 鎶€宸ф彁绀?
- 💡 技巧提示
- ⚠️ 重要警告
### 文档命名规范
- 鎸夋暟瀛楀垎绫伙細01-09绯荤粺姒傝<E5A792>锛?0-19閮ㄧ讲锛?0-29閰嶇疆锛?0-39寮€鍙戯紝40-49鍙傝€?
- 浣跨敤涓嬪垝绾垮垎闅斿<EFBFBD>涓<EFBFBD>崟璇嶏紙鑰岄潪绌烘牸锛?
- 閲嶈<EFBFBD>鏂囨。鍔?瀹屽叏鎸囧崡"/"鎵嬪唽"/"鎸囧崡"鍚庣紑
- 按数字分类：01-09系统概览，10-19部署，20-29配置，30-39开发，40-49参考
- 使用下划线分隔多个单词（而非空格）
- 重要文档加"完全指南"/"手册"/"指南"后缀
---
## 🆘 获取帮助
- **鎶€鏈<EFBFBD>棶棰?*锛氭煡鐪?[13-閮ㄧ讲闂<E8AEB2><E99782>鎺掓煡鎵嬪唽.md](./13-閮ㄧ讲闂<E8AEB2><E99782>鎺掓煡鎵嬪唽.md)
- **技术问题**：查看 [13-部署问题排查手册.md](./13-部署问题排查手册.md)
- **REDCap官方**：https://projectredcap.org/
- **Docker闂<EFBFBD><EFBFBD>**锛氭煡鐪?`redcap-docker-dev/README.md`
- **Docker问题**：查看 `redcap-docker-dev/README.md`

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

@@ -1,153 +1,153 @@
# REDCap与AIclinicalresearch平台对接总体方案
> **譁<EFBFBD>｡｣迚域悽<EFBFBD>?* v1.0
> **蛻帛ｻｺ譌･譛滂ｼ?* 2025-12-30
> **文档版本：** v1.0
> **创建日期：** 2025-12-30
> **最后更新：** 2025-12-30
> **譁<EFBFBD>｡｣迥ｶ諤<EFBFBD>ｼ<EFBFBD>** 隗<><E99A97>荳?
> **文档状态：** 规划中
> **作者：** 技术架构师
---
## 📋 文档说明
譛ｬ譁<EFBFBD>｡｣螳壻ｹ嘘EDCap<EFBFBD>?5.8.0<EFBFBD>我ｸ主｣ｹ隸∝ｾｪAI遘醍<EFBFBD>泌ｹｳ蜿ｰ逧?*螳梧紛蟇ｹ謗･譁ｹ譯<EFBDB9>**<2A>悟桁諡ｬ<E8ABA1><EFBDAC>
本文档定义REDCap（15.8.0）与壹证循AI科研平台的**完整对接方案**，包括：
1. 对接架构设计
2. External Module蠑€蜿第婿譯?
2. External Module开发方案
3. API集成方案
4. 謨ｰ謐ｮ豬∬ｮｾ隶?
4. 数据流设计
5. 开发计划与实施步骤
**蜑咲ｽｮ譚｡莉ｶ<EFBFBD>?*
- 笨?蟾ｲ闔ｷ蠕由EDCap螳俶婿謗域揀
- 笨?諡･譛嘘EDCap 15.8.0貅蝉ｻ｣遐?
- 笨?諡･譛右xternal Module Framework譁<EFBFBD>｡｣
**前置条件：**
- ✅ 已获得REDCap官方授权
- ✅ 拥有REDCap 15.8.0源代码
- ✅ 拥有External Module Framework文档
**逶ｸ蜈ｳ譁<EFBFBD>｡｣<EFBFBD>?*
- [REDCap 莠梧ｬ｡蠑€蜿第ｷｱ蠎ｦ謖<EFBFBD>漉](./REDCap%20莠梧ｬ｡蠑€蜿第ｷｱ蠎ｦ謖<EFBDA6><E8AC96>?md)
**相关文档：**
- [REDCap 二次开发深度指南](./REDCap%20二次开发深度指南.md)
- [系统架构分层设计](../../00-系统总体设计/01-系统架构分层设计.md)
---
## <EFBFBD>識 蟇ｹ謗･逶ｮ譬<EFBDAE>ｸ惹ｻｷ蛟?
## 🎯 对接目标与价值
### 核心目标
**蟆<EFBFBD>EDCap逧<EFBFBD>ｼｺ螟ｧEDC閭ｽ蜉帑ｸ拶I遘醍<EFBFBD>泌ｹｳ蜿ｰ逧БI蠅槫€ｼ蜉溯<EFBFBD>豺ｱ蠎ｦ陞榊<EFBFBD>?*
**将REDCap的强大EDC能力与AI科研平台的AI增值功能深度融合**
```
REDCap (数据采集) + AIclinicalresearch (AI能力)
竊? 竊?
荳ｴ蠎頑焚謐ｮ蠖募<EFBFBD> AI譎ｺ閭ｽ螟<EFBFBD>炊縲∝<EFBFBD>譫舌€∵ｴ槫ｯ?
竊? 竊?
↓ ↓
临床数据录入 AI智能处理、分析、洞察
↓ ↓
完整的AI驱动临床研究闭环
```
### 荳壼苅莉ｷ蛟?
### 业务价值
| 蜉溯<EFBFBD>讓｡蝮<EFBFBD> | REDCap蝓ｺ遑€閭ｽ蜉<EFBFBD> | AI蟷ｳ蜿ｰ蠅槫€ｼ閭ｽ蜉?| 蜊丞酔莉ｷ蛟?|
| 功能模块 | REDCap基础能力 | AI平台增值能力 | 协同价值 |
|---------|--------------|--------------|---------|
| **謨ｰ謐ｮ驥<EFBFBD>寔** | 笨?陦ｨ蜊戊ｮｾ隶｡縲∵焚謐ｮ蠖募<E8A096>縲<EFBFBD>ｪ瑚ｯ?| <20>氏 AI霎<49>勧蠖募<E8A096>縲∵匱閭ｽ雍ｨ謗?| 謠仙合蠖募<E8A096>謨育紫50% |
| **数据采集** | ✅ 表单设计、数据录入、验证 | 🎁 AI辅助录入、智能质控 | 提升录入效率50% |
| **数据清洗** | ⚠️ 手动查询、导出Excel | 🎁 DC模块自动清洗、NER提取 | 减少数据处理时间80% |
| **扈溯ｮ｡蛻<EFBFBD>梵** | 笞<EFBFBD><EFBFBD><EFBFBD> 髴€蟇ｼ蜃ｺ蛻ｰR/SPSS | <EFBFBD>氏 SSA讓｡蝮嶺ｸ€髞ｮ蛻<EFBFBD>梵縲∝庄隗<EFBFBD>喧 | 髯堺ｽ守ｻ溯ｮ｡髣ｨ讒幢ｼ悟<EFBDBC>譫宣€溷ｺｦ謠仙合10蛟?|
| **譁<EFBFBD>鍵謾ｯ謖<EFBFBD>** | 笶?譌?| <20>氏 ASL讓｡蝮玲匱閭ｽ譁<EFBDBD>鍵遲幃€?| 邉ｻ扈溯ｯ<E6BAAF>ｻｷ謨育紫謠仙合5蛟?|
| **AI髣ｮ遲<EFBFBD>** | 笶?譌?| <20>氏 AIA讓｡蝮<EFBDA1>10+譎ｺ閭ｽ菴楢ｾ<E6A5A2><EFBDBE>?| 蜈ｨ豬∫ｨ帰I霎<49>勧 |
| **遏･隸<EFBFBD>ｺ?* | 笶?譌?| <20>氏 PKB讓｡蝮由AG髣ｮ遲<EFBDAE> | 鬘ｹ逶ｮ遏･隸<EFBDA5>ｲ画ｷ€ |
| **统计分析** | ⚠️ 需导出到R/SPSS | 🎁 SSA模块一键分析、可视化 | 降低统计门槛，分析速度提升10倍 |
| **文献支持** | ❌ 无 | 🎁 ASL模块智能文献筛选 | 系统评价效率提升5倍 |
| **AI问答** | ❌ 无 | 🎁 AIA模块10+智能体辅助 | 全流程AI辅助 |
| **知识库** | ❌ 无 | 🎁 PKB模块RAG问答 | 项目知识沉淀 |
---
## <EFBFBD>女<EFBFBD>?蟇ｹ謗･譫ｶ譫<EFBDB6>ｮｾ隶｡
## 🏗️ 对接架构设计
### 整体架构
```
笏娯楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏?
笏? 逕ｨ謌ｷ螻ゑｼ育<EFBFBD>皮ｩｶ莠ｺ蜻<EFBFBD>/蛹ｻ逕滂ｼ? 笏?
笏披楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏?
竊?
笏娯楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏?
笏? 蜑咲ｫｯ螻慕､ｺ螻? 笏?
笏? 笏娯楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏? 笏娯楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏? 笏?
笏? 笏? REDCap Web UI 笏? 笏?AIclinicalresearch 笏? 笏?
笏? 笏? (蜴溽函逡碁擇) 笏や淀笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笆ｺ笏<EFBDBA> Frontend (React) 笏? 笏?
笏? 笏披楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏? 笏披楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏? 笏?
笏披楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏?
竊?
笏娯楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏?
笏? 髮<EFBFBD><EFBFBD>螻ゑｼ域<EFBFBD>ｸ蠢<EFBFBD>ｼ? 笏?
笏? 笏娯楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏? 笏?
笏? 笏? REDCap External Module: "AI Research Assistant" 笏? 笏?
笏? 笏? 笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€ 笏? 笏?
笏? 笏? 笏懌楳笏€ 謨ｰ謐ｮ蜷梧ｭ･譛榊苅 (Data Sync Service) 笏? 笏?
笏? 笏? 笏懌楳笏€ AI蜉溯<E89C89>闖懷黒 (AI Menu Links) 笏? 笏?
笏? 笏? 笏懌楳笏€ Hooks螟<EFBFBD>炊蝎?(Hook Handlers) 笏? 笏?
笏? 笏? 笏披楳笏€ API莉｣逅<EFBDA3>ｱ?(API Proxy) 笏? 笏?
笏? 笏披楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏? 笏?
笏? 竊? 笏?
笏? 笏娯楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏? 笏?
笏? 笏? AIclinicalresearch Backend RESTful API 笏? 笏?
笏? 笏? /api/v1/redcap/* 笏? 笏?
笏? 笏披楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏? 笏?
笏披楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏?
竊?
笏娯楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏?
笏? 荳壼苅螟<EFBFBD>炊螻ゑｼ<EFBFBD>I閭ｽ蜉幢ｼ? 笏?
笏? 笏娯楳笏€笏€笏€笏€笏€笏? 笏娯楳笏€笏€笏€笏€笏€笏? 笏娯楳笏€笏€笏€笏€笏€笏? 笏娯楳笏€笏€笏€笏€笏€笏? 笏娯楳笏€笏€笏€笏€笏€笏? 笏?
笏? 笏?DC 笏? 笏?SSA 笏? 笏?ASL 笏? 笏?AIA 笏? 笏?PKB 笏? ... 笏?
笏? 笏よ焚謐? 笏? 笏らｻ溯ｮ? 笏? 笏よ枚迪? 笏? 笏る琉遲? 笏? 笏ら衍隸<E8A18D>ｺ凪<EFBDBA>? 笏?
笏? 笏よｸ<E38288>ｴ? 笏? 笏ょ<E7AC8F>譫? 笏? 笏らｭ幃€? 笏? 笏? 笏? 笏? 笏? 笏?
笏? 笏披楳笏€笏€笏€笏€笏€笏? 笏披楳笏€笏€笏€笏€笏€笏? 笏披楳笏€笏€笏€笏€笏€笏? 笏披楳笏€笏€笏€笏€笏€笏? 笏披楳笏€笏€笏€笏€笏€笏? 笏?
笏披楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏?
竊?
笏娯楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏?
笏? 謨ｰ謐ｮ蟄伜お螻? 笏?
笏? 笏娯楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏? 笏娯楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏? 笏?
笏? 笏? REDCap MySQL 笏? 笏? AI Platform 笏? 笏?
笏? 笏? (荳ｴ蠎頑焚謐ｮ) 笏や淀笏€笏€笏€笏€笏€笏€笏€笆ｺ笏<EFBDBA> PostgreSQL 笏? 笏?
笏? 笏? - 謔｣閠<EFBDA3>焚謐? 笏? 蜷梧ｭ･ 笏? (蛻<>梵扈捺棡) 笏? 笏?
笏? 笏? - 陦ｨ蜊募<E89C8A>謨ｰ謐? 笏? 笏? - 貂<EFBFBD>ｴ怜錘謨ｰ謐? 笏? 笏?
笏? 笏披楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏? 笏披楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏? 笏?
笏披楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏?
┌─────────────────────────────────────────────────────────────────┐
│ 用户层（研究人员/医生） │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 前端展示层 │
│ ┌────────────────┐ ┌─────────────────────────┐ │
│ │ REDCap Web UI │ │ AIclinicalresearch │ │
│ │ (原生界面) │◄────────────►│ Frontend (React) │ │
│ └────────────────┘ └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 集成层（核心） │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ REDCap External Module: "AI Research Assistant" │ │
│ │ ───────────────────────────────────────────────────── │ │
│ │ ├── 数据同步服务 (Data Sync Service) │ │
│ │ ├── AI功能菜单 (AI Menu Links) │ │
│ │ ├── Hooks处理器 (Hook Handlers) │ │
│ │ └── API代理层 (API Proxy) │ │
│ └────────────────────────────────────────────────────────┘ │
│ ↕ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ AIclinicalresearch Backend RESTful API │ │
│ │ /api/v1/redcap/* │ │
│ └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 业务处理层（AI能力） │
│ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │
│ │ DC │ │ SSA │ │ ASL │ │ AIA │ │ PKB │ ... │
│ │数据 │ │统计 │ │文献 │ │问答 │ │知识库│ │
│ │清洗 │ │分析 │ │筛选 │ │ │ │ │ │
│ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 数据存储层 │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ REDCap MySQL │ │ AI Platform │ │
│ │ (临床数据) │◄───────►│ PostgreSQL │ │
│ │ - 患者数据 │ 同步 │ (分析结果) │ │
│ │ - 表单元数据 │ │ - 清洗后数据 │ │
│ └──────────────────┘ └──────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
### 核心对接模式
謌台ｻｬ驥<EFBFBD>畑**蜿悟髄蟇ｹ謗･**遲也払<E4B99F>?
我们采用**双向对接**策略：
#### 讓｡蠑就<EFBFBD>啌EDCap 竊?AI蟷ｳ蜿ｰ<E89CBF>域焚謐ｮ謗ｨ騾<EFBDA8>ｼ<EFBFBD>
#### 模式A：REDCap → AI平台（数据推送）
```
用户在REDCap录入数据
竊?
↓
redcap_save_record Hook触发
竊?
↓
External Module推送数据到AI平台API
竊?
AI蟷ｳ蜿ｰ螟<EFBFBD>炊<EFBFBD>域ｸ<EFBFBD>ｴ?蛻<>梵/AI螟<49>炊<EFBFBD>?
竊?
↓
AI平台处理（清洗/分析/AI处理）
↓
结果返回REDCap存储
```
#### 讓｡蠑州<EFBFBD>哂I蟷ｳ蜿ｰ 竊?REDCap<61>域焚謐ｮ諡牙叙<E78999><E58F99>
#### 模式B：AI平台 → REDCap（数据拉取）
```
用户在AI平台发起分析
竊?
↓
AI平台调用REDCap API获取数据
竊?
↓
AI平台执行分析（DC/SSA/AIA等）
竊?
↓
结果展示在AI平台前端
竊?
↓
（可选）结果回写REDCap
```
---
## <EFBFBD>肌 謚€譛ｯ譁ｹ譯郁ｯｦ隗?
## 🔧 技术方案详解
### 譁ｹ譯<EFBFBD>1<EFBFBD>啌EDCap External Module蠑€蜿?
### 方案1：REDCap External Module开发
#### 讓｡蝮怜多蜷堺ｸ守ｻ捺<EFBFBD>?
#### 模块命名与结构
```
模块名称: ai_research_assistant
@@ -157,21 +157,21 @@ AI平台执行分析（DC/SSA/AIA等）
目录结构:
ai_research_assistant_v1.0.0/
├── config.json # 模块配置
笏懌楳笏€ AiResearchAssistantModule.php # 荳ｻ騾ｻ霎醍ｱ?
├── AiResearchAssistantModule.php # 主逻辑类
├── README.md # 说明文档
├── LICENSE # MIT许可
笏懌楳笏€ pages/ # 閾ｪ螳壻ｹ蛾｡ｵ髱?
笏? 笏懌楳笏€ dashboard.php # AI蜉溯<EFBFBD>莉ｪ陦ｨ逶?
笏? 笏懌楳笏€ data_sync.php # 謨ｰ謐ｮ蜷梧ｭ･邂｡逅<EFBFBD>
笏? 笏懌楳笏€ analysis_center.php # 蛻<EFBFBD>梵荳ｭ蠢<EFBFBD>
笏? 笏披楳笏€ settings.php # 讓｡蝮苓ｮｾ鄂ｮ
├── pages/ # 自定义页面
│ ├── dashboard.php # AI功能仪表盘
│ ├── data_sync.php # 数据同步管理
│ ├── analysis_center.php # 分析中心
│ └── settings.php # 模块设置
├── js/ # JavaScript文件
笏? 笏懌楳笏€ dashboard.js
笏? 笏披楳笏€ data_sync.js
│ ├── dashboard.js
│ └── data_sync.js
├── css/ # 样式文件
笏? 笏披楳笏€ style.css
笏披楳笏€ services/ # 譛榊苅邀?
笏懌楳笏€ ApiClient.php # AI蟷ｳ蜿ｰAPI螳｢謌ｷ遶?
│ └── style.css
└── services/ # 服务类
├── ApiClient.php # AI平台API客户端
├── DataMapper.php # 数据映射转换
└── SyncService.php # 同步服务
```
@@ -181,7 +181,7 @@ ai_research_assistant_v1.0.0/
```json
{
"name": "AI Research Assistant",
"description": "螢ｹ隸∝ｾｪAI遘醍<EFBFBD>泌ｹｳ蜿ｰ髮<EFBFBD><EFBFBD>讓｡蝮<EFBFBD> - 謠蝉ｾ帶焚謐ｮ譎ｺ閭ｽ貂<EFBDBD>ｴ励€∫ｻ溯ｮ｡蛻<EFBDA1>梵縲∵枚迪ｮ謾ｯ謖∫ｭ陰I蠅槫€ｼ蜉溯<E89C89>?,
"description": "壹证循AI科研平台集成模块 - 提供数据智能清洗、统计分析、文献支持等AI增值功能",
"authors": [
{
"name": "壹证循科技",
@@ -284,7 +284,7 @@ ai_research_assistant_v1.0.0/
}
```
#### 荳ｻ騾ｻ霎醍ｱｻ<EFBFBD><EFBFBD>iResearchAssistantModule.php<EFBFBD>?
#### 主逻辑类（AiResearchAssistantModule.php）
```php
<?php
@@ -295,11 +295,11 @@ use REDCap;
class AiResearchAssistantModule extends AbstractExternalModule {
// API螳｢謌ｷ遶ｯ螳樔ｾ?
// API客户端实例
private $apiClient;
/**
* 譫<EFBFBD>€<EFBFBD>蜃ｽ謨?- 蛻晏ｧ句喧API螳｢謌ｷ遶?
* 构造函数 - 初始化API客户端
*/
public function __construct() {
parent::__construct();
@@ -311,7 +311,7 @@ class AiResearchAssistantModule extends AbstractExternalModule {
}
/**
* Hook: 謨ｰ謐ｮ菫晏ｭ俶慮隗ｦ蜿?
* Hook: 数据保存时触发
* 核心功能：实时推送数据到AI平台
*/
public function redcap_save_record(
@@ -324,7 +324,7 @@ class AiResearchAssistantModule extends AbstractExternalModule {
$response_id,
$repeat_instance
) {
// 譽€譟･譏ｯ蜷ｦ蜷ｯ逕ｨ螳樊慮蜷梧ｭ?
// 检查是否启用实时同步
$syncMode = $this->getProjectSetting('sync_mode');
if ($syncMode !== 'realtime') {
return;
@@ -355,7 +355,7 @@ class AiResearchAssistantModule extends AbstractExternalModule {
'ai_platform_response' => $result
]);
// 螯よ棡蜷ｯ逕ｨ莠<EFBFBD>I謨ｰ謐ｮ貂<EFBFBD>ｴ暦ｼ瑚ｧｦ蜿第ｸ<EFBFBD>ｴ嶺ｻｻ蜉?
// 如果启用了AI数据清洗，触发清洗任务
if ($this->getProjectSetting('enable_dc_module')) {
$this->triggerDataCleaning($project_id, $record);
}
@@ -384,8 +384,8 @@ class AiResearchAssistantModule extends AbstractExternalModule {
}
/**
* Hook: 謨ｰ謐ｮ蟇ｼ蜃ｺ蜑?
* 蜉溯<EFBFBD><EFBFBD>壼庄莉･豺ｻ蜉<EFBFBD>AI蛻<EFBFBD>梵扈捺棡蟄玲ｮｵ蛻ｰ蟇ｼ蜃?
* Hook: 数据导出前
* 功能：可以添加AI分析结果字段到导出
*/
public function redcap_custom_verify_username($username) {
// 验证逻辑
@@ -399,10 +399,10 @@ class AiResearchAssistantModule extends AbstractExternalModule {
foreach ($projects as $project_id) {
try {
// 闔ｷ蜿夜｡ｹ逶ｮ謇€譛画焚謐?
// 获取项目所有数据
$data = REDCap::getData($project_id, 'array');
// 謇ｹ驥乗耳騾?
// 批量推送
$result = $this->apiClient->post('/api/v1/redcap/batch-sync', [
'project_id' => $project_id,
'data' => $data,
@@ -457,7 +457,7 @@ class AiResearchAssistantModule extends AbstractExternalModule {
}
/**
* 闔ｷ蜿門星逕ｨ讓｡蝮礼噪鬘ｹ逶ｮ蛻苓｡?
* 获取启用模块的项目列表
*/
private function getEnabledProjects() {
$sql = "SELECT project_id FROM redcap_external_modules
@@ -480,7 +480,7 @@ class AiResearchAssistantModule extends AbstractExternalModule {
---
### 譁ｹ譯<EFBFBD>2<EFBFBD>哂I蟷ｳ蜿ｰBackend API蠑€蜿?
### 方案2：AI平台Backend API开发
#### 新增REDCap专用模块
@@ -488,18 +488,18 @@ class AiResearchAssistantModule extends AbstractExternalModule {
// backend/src/modules/redcap/ 目录结构
backend/src/modules/redcap/
├── controllers/
笏? 笏懌楳笏€ RedcapController.ts // 荳ｻ謗ｧ蛻ｶ蝎ｨ
笏? 笏懌楳笏€ SyncController.ts // 謨ｰ謐ｮ蜷梧ｭ･謗ｧ蛻ｶ蝎?
笏? 笏披楳笏€ WebhookController.ts // Webhook謗ｧ蛻ｶ蝎?
│ ├── RedcapController.ts // 主控制器
│ ├── SyncController.ts // 数据同步控制器
│ └── WebhookController.ts // Webhook控制器
├── services/
笏? 笏懌楳笏€ RedcapApiClient.ts // REDCap API螳｢謌ｷ遶?
笏? 笏懌楳笏€ DataTransformService.ts // 謨ｰ謐ｮ霓ｬ謐｢譛榊苅
笏? 笏懌楳笏€ SyncService.ts // 蜷梧ｭ･譛榊苅
笏? 笏披楳笏€ ProjectMappingService.ts // 鬘ｹ逶ｮ譏<EFBFBD>蟆<EFBFBD>恪蜉｡
│ ├── RedcapApiClient.ts // REDCap API客户端
│ ├── DataTransformService.ts // 数据转换服务
│ ├── SyncService.ts // 同步服务
│ └── ProjectMappingService.ts // 项目映射服务
├── models/
笏? 笏披楳笏€ redcap.prisma // Prisma Schema
│ └── redcap.prisma // Prisma Schema
├── routes/
笏? 笏披楳笏€ redcap.routes.ts // 霍ｯ逕ｱ螳壻ｹ<EFBFBD>
│ └── redcap.routes.ts // 路由定义
└── types/
└── redcap.types.ts // TypeScript类型定义
```
@@ -516,7 +516,7 @@ datasource redcap_schema {
schemas = ["redcap_schema"]
}
// REDCap鬘ｹ逶ｮ譏<EFBFBD>蟆<EFBFBD>｡?
// REDCap项目映射表
model RedcapProject {
id String @id @default(cuid())
redcapProjectId Int @unique // REDCap项目ID
@@ -533,7 +533,7 @@ model RedcapProject {
syncMode String @default("realtime") // realtime, scheduled, manual
lastSyncAt DateTime?
// 蜈<EFBFBD>焚謐?
// 元数据
projectName String
projectDescription String? @db.Text
@@ -548,7 +548,7 @@ model RedcapProject {
@@schema("redcap_schema")
}
// REDCap蜷梧ｭ･隶ｰ蠖戊｡?
// REDCap同步记录表
model RedcapSyncRecord {
id String @id @default(cuid())
projectId String
@@ -558,13 +558,13 @@ model RedcapSyncRecord {
eventId String? // REDCap事件ID
instrument String? // 表单名称
// 蜷梧ｭ･迥ｶ諤?
// 同步状态
status String // pending, syncing, success, failed
direction String // redcap_to_ai, ai_to_redcap
// 数据快照
redcapData Json // REDCap原始数据
aiPlatformData Json? // AI蟷ｳ蜿ｰ螟<EFBFBD>炊蜷取焚謐?
aiPlatformData Json? // AI平台处理后数据
// 错误信息
errorMessage String? @db.Text
@@ -578,7 +578,7 @@ model RedcapSyncRecord {
@@index([status])
}
// REDCap蟄玲ｮｵ譏<EFBFBD>蟆<EFBFBD>｡?
// REDCap字段映射表
model RedcapFieldMapping {
id String @id @default(cuid())
projectId String
@@ -591,11 +591,11 @@ model RedcapFieldMapping {
// AI平台字段映射
aiPlatformField String? // 映射到AI平台的字段名
transformRule Json? // 霓ｬ謐｢隗<EFBFBD><EFBFBD><EFBFBD><EFBFBD>SON<EFBFBD>?
transformRule Json? // 转换规则（JSON）
// 映射配置
isRequired Boolean @default(false)
isIdentifier Boolean @default(false) // 譏ｯ蜷ｦ荳ｺ荳ｻ髞ｮ蟄玲ｮ?
isIdentifier Boolean @default(false) // 是否为主键字段
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
@@ -650,17 +650,17 @@ export async function redcapRoutes(fastify: FastifyInstance) {
// ========== 数据同步 ==========
// 謇句勘隗ｦ蜿大酔豁･<EFBFBD><EFBFBD>EDCap 竊?AI蟷ｳ蜿ｰ<E89CBF>?
// 手动触发同步（REDCap → AI平台）
fastify.post('/api/v1/redcap/sync/import/:projectId',
syncController.importFromRedcap
);
// 謗ｨ騾∵焚謐ｮ蛻ｰREDCap<EFBFBD><EFBFBD>I蟷ｳ蜿ｰ 竊?REDCap<EFBFBD>?
// 推送数据到REDCap（AI平台 → REDCap）
fastify.post('/api/v1/redcap/sync/export/:projectId',
syncController.exportToRedcap
);
// 譟･隸｢蜷梧ｭ･迥ｶ諤?
// 查询同步状态
fastify.get('/api/v1/redcap/sync/status/:projectId',
syncController.getSyncStatus
);
@@ -672,7 +672,7 @@ export async function redcapRoutes(fastify: FastifyInstance) {
// ========== Webhook接收 ==========
// REDCap External Module謗ｨ騾∵焚謐ｮ<EFBFBD>亥ｮ樊慮蜷梧ｭ･<EFBFBD>?
// REDCap External Module推送数据（实时同步）
fastify.post('/api/v1/redcap/webhook/records',
webhookController.receiveRecordUpdate
);
@@ -684,7 +684,7 @@ export async function redcapRoutes(fastify: FastifyInstance) {
// ========== 字段映射管理 ==========
// 闔ｷ蜿乏EDCap鬘ｹ逶ｮ蜈<EFBFBD>焚謐ｮ<EFBFBD>亥ｭ玲ｮｵ蛻苓｡ｨ<EFBFBD>?
// 获取REDCap项目元数据（字段列表）
fastify.get('/api/v1/redcap/projects/:id/metadata',
redcapController.getProjectMetadata
);
@@ -701,12 +701,12 @@ export async function redcapRoutes(fastify: FastifyInstance) {
// ========== AI功能集成 ==========
// 隗ｦ蜿第焚謐ｮ貂<EFBFBD>ｴ暦ｼ<EFBFBD>C讓｡蝮暦ｼ?
// 触发数据清洗（DC模块）
fastify.post('/api/v1/redcap/dc/clean',
redcapController.triggerDataCleaning
);
// 隗ｦ蜿醍ｻ溯ｮ｡蛻<EFBFBD>梵<EFBFBD><EFBFBD>SA讓｡蝮暦ｼ?
// 触发统计分析（SSA模块）
fastify.post('/api/v1/redcap/ssa/analyze',
redcapController.triggerStatisticalAnalysis
);
@@ -750,7 +750,7 @@ export class SyncController {
if (!project) {
return res.status(404).send({
success: false,
error: '鬘ｹ逶ｮ荳榊ｭ伜<EFBFBD>?
error: '项目不存在'
});
}
@@ -777,8 +777,8 @@ export class SyncController {
project.fieldMappings
);
// 4. 蟄伜お蛻ｰAI蟷ｳ蜿ｰ謨ｰ謐ｮ蠎?
// 譬ｹ謐ｮ鬘ｹ逶ｮ驟咲ｽｮ<EFBFBD>梧耳騾∝芦DC/SSA/ASL遲画ｨ｡蝮?
// 4. 存储到AI平台数据库
// 根据项目配置，推送到DC/SSA/ASL等模块
if (project.dcProjectId) {
await this.importToDCModule(project.dcProjectId, transformedData);
}
@@ -848,74 +848,74 @@ export class SyncController {
---
## <EFBFBD>投 謨ｰ謐ｮ豬∬ｮｾ隶?
## 📊 数据流设计
### 謨ｰ謐ｮ豬?<3F>啌EDCap 竊?AI蟷ｳ蜿ｰ<E89CBF>亥ｮ樊慮蜷梧ｭ･<EFBDAD><EFBDA5>
### 数据流1：REDCap → AI平台（实时同步）
```
笏娯楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏?
笏? Step 1: 逕ｨ謌ｷ蝨ｨREDCap蠖募<EFBFBD>謨ｰ謐ｮ 笏?
笏? 笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€ 笏?
笏? 遐皮ｩｶ莠ｺ蜻伜惠REDCap陦ｨ蜊穂ｸｭ蠖募<E8A096>謔｣閠<EFBDA3>焚謐? 笏?
笏? 萓句ｦゑｼ壽ぅ閠<E38185>D縲∝ｹｴ鮴<EFBDB4>€∵€ｧ蛻ｫ縲∬ｯ頑妙縲∵｣€鬪檎ｻ捺棡遲<E6A3A1> 笏?
笏披楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏?
竊?
笏娯楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏?
笏? Step 2: REDCap隗ｦ蜿喪edcap_save_record Hook 笏?
笏? 笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€ 笏?
笏? External Module謐戊執菫晏ｭ倅ｺ倶ｻｶ 笏?
笏? 闔ｷ蜿厄ｼ嗔roject_id, record, instrument, event_id 笏?
笏披楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏?
竊?
笏娯楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏?
笏? Step 3: 謨ｰ謐ｮ闔ｷ蜿紋ｸ取丐蟆? 笏?
笏? 笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€ 笏?
笏? 1. 隹<EFBFBD>畑REDCap::getData()闔ｷ蜿門ｮ梧紛隶ｰ蠖<EFBFBD> 笏?
笏? 2. DataMapper霓ｬ謐｢REDCap EAV譬ｼ蠑鞘<EFBFBD>AI蟷ｳ蜿ｰ譬<EFBFBD>㊥譬ｼ蠑<EFBFBD> 笏?
笏? 3. 蠎皮畑蟄玲ｮｵ譏<EFBFBD>蟆<EFBFBD>ｧ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>edcap_field_mappings陦ｨ<EFBFBD><EFBFBD> 笏?
笏披楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏?
竊?
笏娯楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏?
笏? Step 4: HTTP POST謗ｨ騾∝芦AI蟷ｳ蜿ｰAPI 笏?
笏? 笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€ 笏?
笏? URL: https://ai.yizx.com/api/v1/redcap/webhook/records 笏?
笏? Payload: { 笏?
笏? project_id: 123, 笏?
笏? record_id: "PAT001", 笏?
笏? data: {...}, 笏?
笏? timestamp: 1735542000 笏?
笏? } 笏?
笏披楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏?
竊?
笏娯楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏?
笏? Step 5: AI蟷ｳ蜿ｰ謗･謾ｶ蟷ｶ螟<EFBFBD><EFBFBD>? 笏?
笏? 笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€ 笏?
笏? 1. WebhookController鬪瑚ｯ∬ｯｷ豎らｭｾ蜷<EFBFBD> 笏?
笏? 2. 蟄伜お蜴溷ｧ区焚謐ｮ蛻ｰredcap_sync_records陦? 笏?
笏? 3. 蠑よｭ･隗ｦ蜿羨I螟<EFBFBD>炊莉ｻ蜉｡<EFBFBD><EFBFBD>C/SSA讓｡蝮暦ｼ? 笏?
笏披楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏?
竊?
笏娯楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏?
笏? Step 6: AI螟<EFBFBD>炊荳守ｻ捺棡霑泌<EFBFBD>? 笏?
笏? 笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€ 笏?
笏? 1. DC讓｡蝮暦ｼ壽焚謐ｮ貂<EFBFBD>ｴ励€¨ER謠仙叙縲∫ｼｺ螟ｱ蛟ｼ螟<EFBFBD><EFBFBD>? 笏?
笏? 2. SSA讓｡蝮暦ｼ夊<EFBFBD>蜉ｨ扈溯ｮ｡蛻<EFBFBD>梵縲∫函謌仙庄隗<EFBFBD>喧蝗ｾ陦ｨ 笏?
笏? 3. 扈捺棡蟄伜お蛻ｰAI蟷ｳ蜿ｰ謨ｰ謐ｮ蠎? 笏?
笏? 4. <EFBFBD>亥庄騾会ｼ牙屓蜀咏ｻ捺棡蛻ｰREDCap<EFBFBD>磯€夊ｿ②PI<EFBFBD>? 笏?
笏披楳笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏€笏?
┌─────────────────────────────────────────────────────────┐
│ Step 1: 用户在REDCap录入数据 │
│ ───────────────────────────────────────────────────── │
│ 研究人员在REDCap表单中录入患者数据 │
│ 例如：患者ID、年龄、性别、诊断、检验结果等 │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ Step 2: REDCap触发redcap_save_record Hook │
│ ───────────────────────────────────────────────────── │
│ External Module捕获保存事件 │
│ 获取：project_id, record, instrument, event_id │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ Step 3: 数据获取与映射 │
│ ───────────────────────────────────────────────────── │
│ 1. 调用REDCap::getData()获取完整记录 │
│ 2. DataMapper转换REDCap EAV格式→AI平台标准格式 │
│ 3. 应用字段映射规则（redcap_field_mappings表） │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ Step 4: HTTP POST推送到AI平台API │
│ ───────────────────────────────────────────────────── │
│ URL: https://ai.yizx.com/api/v1/redcap/webhook/records │
│ Payload: { │
│ project_id: 123, │
│ record_id: "PAT001", │
│ data: {...}, │
│ timestamp: 1735542000 │
│ } │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ Step 5: AI平台接收并处理 │
│ ───────────────────────────────────────────────────── │
│ 1. WebhookController验证请求签名 │
│ 2. 存储原始数据到redcap_sync_records表 │
│ 3. 异步触发AI处理任务（DC/SSA模块） │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ Step 6: AI处理与结果返回 │
│ ───────────────────────────────────────────────────── │
│ 1. DC模块：数据清洗、NER提取、缺失值处理 │
│ 2. SSA模块：自动统计分析、生成可视化图表 │
│ 3. 结果存储到AI平台数据库 │
│ 4. （可选）回写结果到REDCap（通过API） │
└─────────────────────────────────────────────────────────┘
```
### 謨ｰ謐ｮ豬?<3F>哂I蟷ｳ蜿ｰ 竊?REDCap<61>亥<EFBFBD>譫千ｻ捺棡蝗槫<E89D97><E6A7AB><EFBFBD>
### 数据流2：AI平台 → REDCap（分析结果回写）
```
AI平台完成分析
竊?
逕滓<EFBFBD>蛻<EFBFBD>梵扈捺棡<EFBFBD><EFBFBD>SON<EFBFBD>?
竊?
↓
生成分析结果（JSON）
↓
调用REDCap API: importRecords
竊?
REDCap蟄伜お扈捺棡蛻ｰ迚ｹ螳壼ｭ玲ｮ?
竊?
↓
REDCap存储结果到特定字段
↓
研究人员在REDCap中查看AI分析结果
```
@@ -925,34 +925,34 @@ REDCap存储结果到特定字
### Phase 1: 基础对接（Week 1-2）✅ 优先级P0
**逶ｮ譬<EFBFBD>**<EFBFBD>壼ｻｺ遶騎EDCap荳拶I蟷ｳ蜿ｰ逧<EFBFBD>渕譛ｬ霑樊<EFBFBD>?
**目标**：建立REDCap与AI平台的基本连接
#### Week 1: External Module骨架
**莉ｻ蜉｡貂<EFBFBD>黒**<EFBFBD>?
**任务清单**：
- [ ] 创建External Module目录结构
- [ ] 编写config.json配置文件
- [ ] 螳樒鴫AiResearchAssistantModule.php蝓ｺ遑€邀?
- [ ] 实现AiResearchAssistantModule.php基础类
- [ ] 实现redcap_save_record Hook（基础版）
- [ ] 开发ApiClient.php（HTTP客户端）
- [ ] 豬玖ｯ包ｼ啌EDCap菫晏ｭ俶焚謐ｮ竊呈遠蜊ｰ譌･蠢?
- [ ] 测试：REDCap保存数据→打印日志
**莠､莉倡<EFBFBD>?*<2A>?
**交付物**：
- `ai_research_assistant_v1.0.0/` 完整目录
- 可在REDCap中启用的External Module
- 基础日志记录功能
#### Week 2: AI平台API端点
**莉ｻ蜉｡貂<EFBFBD>黒**<EFBFBD>?
**任务清单**：
- [ ] 创建redcap_schema数据库Schema
- [ ] 螳樒鴫Prisma讓｡蝙具ｼ<EFBFBD>edcapProject遲?荳ｪ陦ｨ<E999A6>?
- [ ] 实现Prisma模型（RedcapProject等3个表）
- [ ] 开发WebhookController接收数据
- [ ] 实现数据转换服务DataTransformService
- [ ] 蠑€蜿鷹｡ｹ逶ｮ邂｡逅<EFBFBD>PI<EFBFBD><EFBFBD>RUD<EFBFBD>?
- [ ] 豬玖ｯ包ｼ啌EDCap謗ｨ騾≫<EFBFBD>AI蟷ｳ蜿ｰ謗･謾ｶ竊貞ｭ伜<EFBFBD>?
- [ ] 开发项目管理API（CRUD）
- [ ] 测试：REDCap推送→AI平台接收→存储
**莠､莉倡<EFBFBD>?*<2A>?
**交付物**：
- `/api/v1/redcap/*` API端点
- PostgreSQL redcap_schema创建
- Postman测试集合
@@ -965,102 +965,102 @@ REDCap存储结果到特定字
#### Week 3: 字段映射系统
**莉ｻ蜉｡貂<EFBFBD>黒**<EFBFBD>?
- [ ] 蠑€蜿大ｭ玲ｮｵ譏<EFBFBD>蟆<EFBFBD>ｮ｡逅<EFBFBD>I<EFBFBD>亥燕遶ｯReact<EFBFBD>?
**任务清单**：
- [ ] 开发字段映射管理UI（前端React）
- [ ] 实现REDCap元数据获取API
- [ ] 蠑€蜿大ｭ玲ｮｵ譏<EFBFBD>蟆<EFBFBD><EFBFBD>鄂ｮ逡碁<EFBFBD>?
- [ ] 螳樒鴫譏<EFBFBD>蟆<EFBFBD>ｧ<EFBFBD><EFBFBD>蠑墓梼<EFBFBD><EFBFBD>ataMapper<EFBFBD>?
- [ ] 开发字段映射配置界面
- [ ] 实现映射规则引擎（DataMapper）
- [ ] 支持复杂转换（如：单位转换、编码映射）
- [ ] 测试：映射配置→数据转换验证
**莠､莉倡<EFBFBD>?*<2A>?
**交付物**：
- 字段映射UI页面
- 映射规则引擎
- 配置文档
#### Week 4: 双向同步
**莉ｻ蜉｡貂<EFBFBD>黒**<EFBFBD>?
- [ ] 螳樒鴫謇ｹ驥乗焚謐ｮ蟇ｼ蜈･<EFBFBD><EFBFBD>EDCap 竊?AI<41>?
- [ ] 螳樒鴫蛻<EFBFBD>梵扈捺棡蝗槫<EFBFBD><EFBFBD><EFBFBD>I 竊?REDCap<EFBFBD>?
**任务清单**：
- [ ] 实现批量数据导入（REDCap → AI）
- [ ] 实现分析结果回写（AI → REDCap）
- [ ] 开发Cron定时同步任务
- [ ] 螳樒鴫蜷梧ｭ･迥ｶ諤∫尅謗ｧ逡碁<EFBFBD>?
- [ ] 髞呵ｯｯ螟<EFBFBD>炊荳朱㍾隸墓惻蛻?
- [ ] 豬玖ｯ包ｼ壼ｮ梧紛蜷梧ｭ･豬∫ｨ?
- [ ] 实现同步状态监控界面
- [ ] 错误处理与重试机制
- [ ] 测试：完整同步流程
**莠､莉倡<EFBFBD>?*<2A>?
**交付物**：
- 双向同步功能
- 同步监控Dashboard
- 错误处理机制
---
### Phase 3: AI蜉溯<EFBFBD>髮<EFBFBD><EFBFBD><EFBFBD><EFBFBD>eek 5-6<>解沁?莨伜<E88EA8>郤ｧP1
### Phase 3: AI功能集成（Week 5-6）🎁 优先级P1
**目标**：集成DC、SSA、AIA等AI模块
#### Week 5: DC模块集成
**莉ｻ蜉｡貂<EFBFBD>黒**<EFBFBD>?
**任务清单**：
- [ ] REDCap数据→DC模块自动清洗
- [ ] 清洗结果→REDCap回写
- [ ] 蝨ｨREDCap荳ｭ螻慕､ｺ貂<EFBFBD>ｴ玲冠蜻?
- [ ] 在REDCap中展示清洗报告
- [ ] 支持手动触发清洗
- [ ] 豬玖ｯ包ｼ壼ｽ募<EFBFBD>竊呈ｸ<EFBFBD>ｴ冷<EFBFBD>譟･逵狗ｻ捺<EFBFBD>?
- [ ] 测试：录入→清洗→查看结果
**莠､莉倡<EFBFBD>?*<2A>?
**交付物**：
- DC集成API
- REDCap清洗报告页面
#### Week 6: SSA模块集成
**莉ｻ蜉｡貂<EFBFBD>黒**<EFBFBD>?
**任务清单**：
- [ ] REDCap数据→SSA模块自动分析
- [ ] 謾ｯ謖∽ｸ牙､ｧ蛻<EFBFBD>梵霍ｯ蠕<EFBFBD>ｼ磯弌蛻?鬚<>ｵ<EFBFBD>/RCT<EFBFBD>?
- [ ] 蝨ｨREDCap荳ｭ蠏悟<EFBFBD>扈溯ｮ｡謚･蜻?
- [ ] 蜿ｯ隗<EFBFBD>喧蝗ｾ陦ｨ螻慕､?
- [ ] 豬玖ｯ包ｼ壽焚謐ｮ蠖募<EFBFBD>竊定<EFBFBD>蜉ｨ蛻<EFBFBD>梵竊呈冠蜻顔函謌?
- [ ] 支持三大分析路径（队列/预测/RCT）
- [ ] 在REDCap中嵌入统计报告
- [ ] 可视化图表展示
- [ ] 测试：数据录入→自动分析→报告生成
**莠､莉倡<EFBFBD>?*<2A>?
**交付物**：
- SSA集成API
- 统计报告嵌入页面
---
### Phase 4: 鬮倡ｺｧ蜉溯<EFBFBD><EFBFBD><EFBFBD>eek 7-8<>解沍?莨伜<E88EA8>郤ｧP2
### Phase 4: 高级功能（Week 7-8）🌟 优先级P2
**逶ｮ譬<EFBFBD>**<EFBFBD>哂I霎<EFBFBD>勧蠖募<EFBFBD>縲∵匱閭ｽ雍ｨ謗ｧ遲牙｢槫€ｼ蜉溯<EFBFBD>?
**目标**：AI辅助录入、智能质控等增值功能
#### Week 7: AI辅助录入
**莉ｻ蜉｡貂<EFBFBD>黒**<EFBFBD>?
- [ ] 蠑€蜿第匱閭ｽ閾ｪ蜉ｨ螳梧<EFBFBD><EFBFBD>亥渕莠主紙蜿ｲ謨ｰ謐ｮ<EFBFBD>?
- [ ] 蠑ょｸｸ蛟ｼ鬚<EFBFBD>ｭｦ<EFBFBD>亥ｮ樊慮AI蛻､譁ｭ<EFBFBD>?
- [ ] 蟄玲ｮｵ蜈ｳ閨疲耳闕撰ｼ<EFBFBD>I鬚<EFBFBD>ｵ具ｼ?
**任务清单**：
- [ ] 开发智能自动完成（基于历史数据）
- [ ] 异常值预警（实时AI判断）
- [ ] 字段关联推荐（AI预测）
- [ ] 录入效率提升统计
- [ ] 豬玖ｯ包ｼ壼ｽ募<EFBFBD>菴馴ｪ御ｼ伜喧鬪瑚ｯ?
- [ ] 测试：录入体验优化验证
**莠､莉倡<EFBFBD>?*<2A>?
**交付物**：
- AI辅助录入JS插件
- 智能质控规则引擎
#### Week 8: 扈ｼ蜷域ｵ玖ｯ穂ｸ惹ｼ伜<EFBFBD>?
#### Week 8: 综合测试与优化
**莉ｻ蜉｡貂<EFBFBD>黒**<EFBFBD>?
- [ ] 諤ｧ閭ｽ豬玖ｯ包ｼ?00荳<30>擅隶ｰ蠖募酔豁･<E8B181>?
**任务清单**：
- [ ] 性能测试（100万条记录同步）
- [ ] 安全测试（API认证、数据加密）
- [ ] 逕ｨ謌ｷ鬪梧噺豬玖ｯ包ｼ<EFBFBD>AT<EFBFBD>?
- [ ] 譁<EFBFBD>｡｣郛門<EFBFBD><EFBFBD>育畑謌ｷ謇句<EFBFBD>?蠑€蜿第枚譯｣<E8ADAF><EFBDA3>
- [ ] 驛ｨ鄂ｲ蛻ｰ逕滉ｺｧ邇ｯ蠅?
- [ ] 用户验收测试（UAT）
- [ ] 文档编写（用户手册+开发文档）
- [ ] 部署到生产环境
**莠､莉倡<EFBFBD>?*<2A>?
**交付物**：
- 性能测试报告
- 完整文档
- 生产环境部署
---
## <EFBFBD>白 螳牙<E89EB3>諤ｧ隶ｾ隶?
## 🔒 安全性设计
### API认证机制
@@ -1097,7 +1097,7 @@ function verifySignature(req) {
- REDCap API Token：使用AES-256加密存储
- 传输加密：强制HTTPS
- 謨乗─蟄玲ｮｵ<EFBFBD>壽髪謖∝ｭ玲ｮｵ郤ｧ蜉<EFBFBD>蟇<EFBFBD>ｼ<EFBFBD>HI謨ｰ謐ｮ<EFBFBD>?
- 敏感字段：支持字段级加密（PHI数据）
### 权限控制
@@ -1122,73 +1122,73 @@ interface UserPermission {
## 📚 技术栈总结
| 螻らｺｧ | REDCap萓?| AI蟷ｳ蜿ｰ萓?|
| 层级 | REDCap侧 | AI平台侧 |
|------|---------|---------|
| **编程语言** | PHP 7.4+ | TypeScript/Node.js 22 |
| **框架** | REDCap EM Framework v16 | Fastify v4 |
| **謨ｰ謐ｮ蠎?* | MySQL 5.7+ | PostgreSQL 15 |
| **謨ｰ謐ｮ讓｡蝙<EFBFBD>** | EAV讓｡蝙<EFBFBD> | 蜈ｳ邉ｻ蝙?JSONB |
| **数据库** | MySQL 5.7+ | PostgreSQL 15 |
| **数据模型** | EAV模型 | 关系型+JSONB |
| **前端** | jQuery + Bootstrap 5 | React 19 + Ant Design 6 |
| **API** | REDCap RESTful API | Fastify RESTful API |
| **认证** | API Token | HMAC-SHA256签名 |
| **譌･蠢<EFBFBD>** | REDCap譌･蠢苓｡?| Winston + SLS |
| **日志** | REDCap日志表 | Winston + SLS |
| **任务队列** | REDCap Cron | pg-boss (Postgres-Only) |
---
## <EFBFBD>統 荳倶ｸ€豁･陦悟<E999A6>?
## 📝 下一步行动
### 立即行动（本周）
1. **遑ｮ隶､髴€豎?*<2A>?
1. **确认需求**：
- [ ] 确认优先级（DC优先？还是SSA优先？）
- [ ] 确认部署形态（云端SaaS？还是私有化部署？）
- [ ] 确认REDCap服务器信息（URL、版本、访问权限）
2. **邇ｯ蠅<EFBFBD>㊥螟<EFBFBD>**<EFBFBD>?
- [ ] 謳ｭ蟒ｺREDCap豬玖ｯ慕識蠅<EFBFBD>ｼ井ｽｿ逕ｨDocker<EFBFBD>?
- [ ] 蛻帛ｻｺ豬玖ｯ暮｡ｹ逶ｮ蜥梧ｵ玖ｯ墓焚謐?
2. **环境准备**：
- [ ] 搭建REDCap测试环境（使用Docker）
- [ ] 创建测试项目和测试数据
- [ ] 配置AI平台测试API
3. **蜷ｯ蜉ｨ蠑€蜿?*<2A>?
3. **启动开发**：
- [ ] 创建External Module目录
- [ ] 初始化Git仓库
- [ ] 编写config.json
### 謚€譛ｯ鬚<EFBFBD><EFBFBD>?
### 技术预研
1. **REDCap API深入测试**
2. **External Module Hook机制验证**
3. **大数据量同步性能测试**
4. **遘ｻ蜉ｨ遶ｯ<EFBFBD><EFBFBD>EDCap Mobile App<EFBFBD>蛾寔謌仙庄陦梧€?*
4. **移动端（REDCap Mobile App）集成可行性**
---
## 🎯 成功标准
**MVP迚域悽<EFBFBD><EFBFBD>hase 1-2螳梧<EFBFBD><EFBFBD>?*<2A>?
- 笨?REDCap謨ｰ謐ｮ閭ｽ謗ｨ騾∝芦AI蟷ｳ蜿ｰ
- 笨?AI蟷ｳ蜿ｰ閭ｽ謗･謾ｶ蟷ｶ蟄伜お謨ｰ謐ｮ
- 笨?蟄玲ｮｵ譏<EFBDB5>蟆<EFBFBD><E89F86>鄂ｮ蜉溯<E89C89>蜿ｯ逕ｨ
- 笨?蝓ｺ遑€蜷梧ｭ･逶第而蜿ｯ逕ｨ
**MVP版本（Phase 1-2完成）**：
- ✅ REDCap数据能推送到AI平台
- ✅ AI平台能接收并存储数据
- ✅ 字段映射配置功能可用
- ✅ 基础同步监控可用
**譬<EFBFBD>㊥迚域悽<EFBFBD><EFBFBD>hase 3螳梧<E89EB3><E6A2A7>?*<2A>?
- 笨?DC讓｡蝮鈴寔謌仙ｮ梧<EFBDAE><E6A2A7>郁<EFBFBD>蜉ｨ貂<EFBDA8>ｴ暦ｼ<E69AA6>
- 笨?SSA讓｡蝮鈴寔謌仙ｮ梧<EFBFBD><EFBFBD>郁<EFBFBD>蜉ｨ蛻<EFBFBD>梵<EFBFBD><EFBFBD>
- 笨?蛻<>梵扈捺棡蜿ｯ蝨ｨREDCap荳ｭ譟･逵?
- 笨?逕ｨ謌ｷ菴馴ｪ梧ｵ∫腐
**标准版本（Phase 3完成）**：
- ✅ DC模块集成完成（自动清洗）
- ✅ SSA模块集成完成（自动分析）
- ✅ 分析结果可在REDCap中查看
- ✅ 用户体验流畅
**莨∽ｸ夂沿譛ｬ<EFBFBD><EFBFBD>hase 4螳梧<E89EB3><E6A2A7>?*<2A>?
- 笨?AI霎<49>勧蠖募<E8A096>謠仙合謨育紫50%+
- 笨?譎ｺ閭ｽ雍ｨ謗ｧ蜃丞ｰ鷹漠隸ｯ邇?0%+
- 笨?謾ｯ謖<EFBDAF>100荳?隶ｰ蠖募酔豁･
- 笨?螳牙<E89EB3>蜷郁ｧ<E98381>ｼ育ｬｦ蜷<EFBDA6>DA 21 CFR Part 11<EFBFBD>?
**企业版本（Phase 4完成）**：
- ✅ AI辅助录入提升效率50%+
- ✅ 智能质控减少错误率80%+
- ✅ 支持100万+记录同步
- ✅ 安全合规（符合FDA 21 CFR Part 11）
---
**文档版本**：v1.0
**譛€蜷取峩譁?*<2A>?025-12-30
**荳区ｬ｡譖ｴ譁ｰ**<EFBFBD>啀hase 1蜷ｯ蜉ｨ蜷取峩譁ｰ蠑€蜿題ｿ帛ｺ?
**最后更新**：2025-12-30
**下次更新**：Phase 1启动后更新开发进度
---

706
docs/03-业务模块/Redcap/00-模块概览/03-REDCap对接风险评估与技术挑战分析.md
View File

File diff suppressed because it is too large Load Diff

67
docs/03-业务模块/Redcap/00-模块概览/04-生产环境部署决策报告_ECS_vs_SAE.md
View File

@@ -1,44 +1,53 @@
# **REDCap 生产环境部署：ECS vs SAE 深度决议报告**
## **1\. 譬ｸ蠢<EFBFBD>ｻ楢ｮｺ<EFBFBD>夊ｮ､蜿?ECS 莨伜<E88EA8>遲也払**
## **1\. 核心结论：认可 ECS 优先策略**
髓亥ｯｹ IIT Manager Agent 鬘ｹ逶ｮ<EFBFBD>梧<EFBFBD>莉ｬ蜀ｳ螳壼ｰ<EFBFBD> REDCap 逕滉ｺｧ邇ｯ蠅<EFBDAF>Κ鄂ｲ蝨?**ECS (Docker 讓｡蠑<EFBDA1>)** 霑占｡鯉ｼ瑚€御ｸ肴<EFBDB8>?SAE縲?
### **荳ｺ莉€荵域<E88DB5>莉ｬ窶懆ｮ､髞吮€晏ｹｶ霓ｬ蜷<EFBDAC> ECS<43>?*
针对 IIT Manager Agent 项目，我们决定将 REDCap 生产环境部署在 **ECS (Docker 模式)** 运行，而不是 SAE。
蝨ｨ隶ｨ隶?AI 蜷守ｫｯ譌ｶ<E8AD8C>郡AE 逧<><E980A7>霑千ｻｴ迚ｹ諤ｧ蠕亥精蠑穂ｺｺ<EFBDBA>御ｽ?REDCap 逧<>ｸ我ｸｪ窶懆<E7AAB6>蜻ｽ迚ｹ諤ｧ窶晏<E7AAB6>螳壻ｺ<E5A3BB>ｮ<EFBFBD>惠 SAE 荳贋ｼ壽栫蜈ｶ逞幄協<E5B984>?
1. **Cron 萓晁ｵ厄ｼ亥ｿ<E4BAA5>ｷｳ荳｢螟ｱ<E89E9F><EFBDB1>**<EFBFBD>啌EDCap 豈丞<E8B188>髓滄<E9AB93>髴€隕∬ｿ占｡御ｸ€谺?cron.php縲ょ惠 SAE 荳ｭ<E88DB3>御ｽ<E5BEA1>蠕鈴｢晏､紋ｹ?SchedulerX 譛榊苅<E6A68A>帛惠 ECS<43>悟宵髴€荳€陦?crontab 蟆ｱ閭ｽ謳槫ｮ壻ｸ?100% 蜿ｯ髱<EFBDAF>縲?
2. **Session 邊俶ｻ橸ｼ域脂郤ｿ蝎ｩ譴ｦ<E8ADB4><EFBDA6>**<EFBFBD>啌EDCap 鮟倩ｮ､蟆<EFBDA4>ｼ夊ｯ晏ｭ俶悽蝨ｰ縲４AE 譏ｯ螟壼ｮ樔ｾ狗噪<E78B97>悟ｦよ棡豐｡蛛<EFBDA1> Redis 蜈ｱ莠ｫ<E88EA0>檎畑謌ｷ逋ｻ蠖募錘莨壼渚螟肴脂郤ｿ<E983A4><EFBDBF>2 莠ｺ蝗｢髦溷悉菫ｮ霑吩ｸ?Bug 莨夊€苓ｴｹ螟ｧ驥乗慮髣ｴ縲?
3. **譁<>ｻｶ邉ｻ扈<EFBDBB> POSIX 萓晁ｵ<E69981>**<EFBFBD>啌EDCap 蜒?10 蟷ｴ蜑咲噪霓ｯ莉ｶ荳€譬ｷ譫∝<E8ADAB>萓晁ｵ匁悽蝨ｰ譁<EFBDB0>ｻｶ螟ｹ隸ｻ蜀吶€４AE 蠢<>｡ｻ謖りｽｽ NAS<41>檎ｽ醍ｻ懷ｻｶ霑滉ｼ壽許諷｢謨ｴ荳ｪ邉ｻ扈溽噪蜩榊ｺ斐€?
## **2\. 豺ｱ蠎ｦ蟇ｹ豈費ｼ壼苅螳樊ｴｾ逧<EFBDBE><E980A7>遲紋ｾ晄<EFBDBE>?*
### **为什么我们“认错”并转向 ECS？**
在讨论 AI 后端时，SAE 的免运维特性很吸引人，但 REDCap 的三个“致命特性”决定了它在 SAE 上会极其痛苦：
1. **Cron 依赖（心跳丢失）**：REDCap 每分钟都需要运行一次 cron.php。在 SAE 中，你得额外买 SchedulerX 服务；在 ECS，只需一行 crontab 就能搞定且 100% 可靠。
2. **Session 粘滞（掉线噩梦）**：REDCap 默认将会话存本地。SAE 是多实例的，如果没做 Redis 共享，用户登录后会反复掉线，2 人团队去修这个 Bug 会耗费大量时间。
3. **文件系统 POSIX 依赖**：REDCap 像 10 年前的软件一样极其依赖本地文件夹读写。SAE 必须挂载 NAS，网络延迟会拖慢整个系统的响应。
## **2\. 深度对比：务实派的决策依据**
| 维度 | ECS \+ Docker (我们的选择) | SAE (Serverless) | 结论 |
| :---- | :---- | :---- | :---- |
| **驛ｨ鄂ｲ謌先悽** | **菴?*縲ょ<E7B8B2>髣ｨ郤ｧ ECS (2譬?G) 郤?1500蜈?蟷ｴ縲?| **鬮?*縲４AE \+ NAS \+ 髣ｲ鄂ｮ雍ｹ逕ｨ蜿ｯ閭ｽ譖ｴ雍ｵ縲?| **ECS 閭?* |
| **驟咲ｽｮ螟肴揩蠎?* | **譫∫ｮ€**縲ょ宵髴€霑占｡<E58DA0> docker-compose.yml縲?| **螟肴揩**縲る怙隗｣蜀ｳ蜈ｱ莠ｫ蟄伜お縲ヾession蜷梧ｭ･縲∝ｮ壽慮莉ｻ蜉｡縲?| **ECS 閭?* |
| **邉ｻ扈滄€乗<EFBFBD>蠎?* | **騾乗<EFBFBD>**縲ら峩謗?docker logs 譟･逵<EFBFBD> PHP 譌･蠢励€?| **鮟醍將**縲ゆｺ大次逕滄得霍ｯ髟ｿ<E9AB9F>梧冠髞呎慮謗呈衍髫ｾ蠎ｦ螟ｧ縲?| **ECS 閭?* |
| **蜿ｯ遘ｻ讀肴€?* | **譛€蠑?*縲りｿ吩ｻ?Docker 驟咲ｽｮ蜿ｯ莉･蜴溷ｰ∽ｸ榊勘謖ｪ蛻ｰ蛹ｻ髯｢蜀<EFBDA2>ｽ代€?| **蟾?*縲ょ現髯｢蜀<EFBDA2>ｽ鷹€壼ｸｸ豐｡譛<EFBDA1> SAE 霑咏ｧ咲識蠅<E8AD98>€?| **ECS 閭?* |
| **部署成本** | **低**。入门级 ECS (2核4G) 约 1500元/年。 | **高**。SAE \+ NAS \+ 闲置费用可能更贵。 | **ECS 胜** |
| **配置复杂度** | **极简**。只需运行 docker-compose.yml。 | **复杂**。需解决共享存储、Session同步、定时任务。 | **ECS 胜** |
| **系统透明度** | **透明**。直接 docker logs 查看 PHP 日志。 | **黑盒**。云原生链路长，报错时排查难度大。 | **ECS 胜** |
| **可移植性** | **最强**。这份 Docker 配置可以原封不动挪到医院内网。 | **差**。医院内网通常没有 SAE 这种环境。 | **ECS 胜** |
## **3\. 2 莠ｺ蝗｢髦溽噪窶懃函蟄倅ｹ矩％窶?*
## **3\. 2 人团队的“生存之道”**
作为一个只有 2 人的团队，我们的时间应该花在 **Agent 的 Prompt 调优** 和 **业务逻辑** 上，而不是花在“调试云产品之间的连接”上。
* **ECS 方案**：你就像拥有了一台真正的电脑。文件在哪、日志在哪、数据库连没连上，你一眼就能看清。
* **SAE 方案**：你会陷入“为什么挂载了 NAS 还是没写权限？”、“为什么 Cron 没触发？”这种与业务无关的琐事中。
菴應ｸｺ荳€荳ｪ蜿ｪ譛?2 莠ｺ逧<EFBDBA>屬髦滂ｼ梧<EFBDBC>莉ｬ逧<EFBDAC>慮髣ｴ蠎碑ｯ･闃ｱ蝨ｨ **Agent 逧?Prompt 隹<>ｼ<EFBFBD>** 蜥?**荳壼苅騾ｻ霎<EFBDBB>** 荳奇ｼ瑚€御ｸ肴弍闃ｱ蝨ｨ窶懆ｰ<E68786>ｯ穂ｺ台ｺｧ蜩∽ｹ矩龍逧<E9BE8D>ｿ樊磁窶昜ｸ翫€?
* **ECS 譁ｹ譯<EFBDB9>**<2A>壻ｽ<E5A3BB>蟆ｱ蜒乗凶譛我ｺ<E68891>ｸ€蜿ｰ逵滓ｭ｣逧<EFBDA3>鳩閼代€よ枚莉ｶ蝨ｨ蜩ｪ縲∵律蠢怜惠蜩ｪ縲∵焚謐ｮ蠎楢ｿ樊ｲ｡霑樔ｸ奇ｼ御ｽ<E5BEA1>荳€逵ｼ蟆ｱ閭ｽ逵区ｸ<E58CBA>€?
* **SAE 譁ｹ譯<EFBDB9>**<2A>壻ｽ<E5A3BB>莨夐匚蜈･窶應ｸｺ莉€荵域撃霓ｽ莠<EFBDBD> NAS 霑俶弍豐｡蜀呎揀髯撰ｼ溪€昴€≫€應ｸｺ莉€荵?Cron 豐｡隗ｦ蜿托ｼ溪€晁ｿ咏ｧ堺ｸ惹ｸ壼苅譌<E88B85>蜈ｳ逧<EFBDB3>瑞莠倶ｸｭ縲?
## **4\. 最终定稿：混合架构蓝图**
謌台ｻｬ蟆<EFBFBD>㊦蜿暴*\*窶懈ｷｷ蜷井ｺ鯛€拿*\*逧<>€晁ｷｯ<EFBDB7>悟書謖･蜷<EFBDA5><E89CB7>逧<EFBFBD>柄螟<E69F84>ｼ?
### **4.1 謨ｰ謐ｮ蟷ｳ髱｢ (Data Layer) \-\> 驛ｨ鄂ｲ蝨?ECS**
我们将采取\*\*“混合云”\*\*的思路，发挥各自的长处：
* **扈<>ｻｶ**<2A>啌EDCap (Apache \+ PHP 8.1)縲?
* **譁ｹ蠑<EFBDB9>**<2A>壻ｽｿ逕?Docker-Compose 霑占｡後€?
* **蟄伜お**<2A>夐刋莉ｶ蟄伜お蝨ｨ ECS 謖りｽｽ逧<EFBDBD>ｺ醍尨<E9868D>帶焚謐ｮ蠎楢ｿ樊<EFBDBF>?**RDS MySQL**縲?
* **莨伜漢**<2A>壻ｿ晁ｯ∽ｺ<E288BD> EDC 邉ｻ扈溽噪扈晏ｯｹ遞ｳ螳壼柱莨<E69FB1>扈溯ｿ千ｻｴ逧<EFBDB4>ｮ€萓ｿ縲?
### **4.2 謗ｧ蛻ｶ蟷ｳ髱｢ (AI Agent Layer) \-\> 驛ｨ鄂ｲ蝨?SAE**
### **4.1 数据平面 (Data Layer) \-\> 部署在 ECS**
* **组件**：REDCap (Apache \+ PHP 8.1)。
* **方式**：使用 Docker-Compose 运行。
* **存储**：附件存储在 ECS 挂载的云盘；数据库连接 **RDS MySQL**。
* **优势**：保证了 EDC 系统的绝对稳定和传统运维的简便。
### **4.2 控制平面 (AI Agent Layer) \-\> 部署在 SAE**
* **组件**：Node.js 后端、Python 算法、AI 前端。
* **方式**：Serverless 部署。
* **优势**：利用 SAE 处理 AI 这种流量波动大、需要弹性伸缩的模块。
* **扈<>ｻｶ**<2A>哢ode.js 蜷守ｫｯ縲￣ython 邂玲ｳ輔€、I 蜑咲ｫｯ縲?
* **譁ｹ蠑<EFBDB9>**<2A>售erverless 驛ｨ鄂ｲ縲?
* **莨伜漢**<2A>壼茜逕?SAE 螟<>炊 AI 霑咏ｧ肴ｵ<E882B4>㍼豕｢蜉ｨ螟ｧ縲<EFBDA7>怙隕∝ｼｹ諤ｧ莨ｸ郛ｩ逧<EFBDA9>ｨ｡蝮励€?
## **5\. 对后续开发的意义**
1. **譛ｬ蝨ｰ邇ｯ蠅<EFBFBD>叉逕滉ｺｧ邇ｯ蠅?*<2A>夂罰莠?ECS 霍醍噪譏?Docker<65>御ｽ<E5BEA1>蝨ｨ譛ｬ蝨?03-REDCap譛ｬ蝨ｰ驛ｨ鄂ｲ譁ｹ譯<EFBDB9>.md 驥悟<E9A9A5>逧<EFBFBD>ｻ｣遐<EFBDA3>ｼ檎峩謗･蟆ｱ閭ｽ荳顔ｺｿ<EFBDBA>梧ｲ｡譛我ｻｻ菴補€懃識蠅<E8AD98>ｼらｧｻ窶昴€?
2. **遖ｻ郤ｿ莠､莉倬｢<EFBFBD>ｼ<EFBFBD>**<EFBFBD>壼ｦよ棡譛ｪ譚･蛹ｻ髯｢隕∵ｱょ<EFBFBD>鄂鷹Κ鄂ｲ<EFBFBD>梧<EFBFBD>莉ｬ蟾ｲ扈乗怏莠<EFBFBD>ｸ€螂怜ｮ梧紛逧<EFBFBD>€∝渕莠?ECS/Docker 逧<>ｺ､莉伜桁<E4BC9C>瑚ｿ呎ｯ?SAE 譁ｹ譯域峩螳ｹ譏楢｢ｫ蛹ｻ髯｢ IT 謗･蜿励€?
**蠖灘燕迥ｶ諤?*<2A>咼eployment Strategy Locked | **蟒ｺ隶ｮ**<EFBFBD>夂ｫ句叉謇ｧ陦悟渕莠?ECS 逧<>函莠ｧ邇ｯ蠅<EFBDAF>政蟒ｺ縲
1. **本地环境即生产环境**：由于 ECS 跑的是 Docker，你在本地 03-REDCap本地部署方案.md 里写的代码，直接就能上线，没有任何“环境漂移”。
2. **离线交付预演**：如果未来医院要求内网部署，我们已经有了一套完整的、基于 ECS/Docker 的交付包，这比 SAE 方案更容易被医院 IT 接受。
**当前状态**：Deployment Strategy Locked | **建议**：立即执行基于 ECS 的生产环境搭建。

421
docs/03-业务模块/Redcap/01-部署与配置/10-REDCap_Docker部署操作手册.md
View File

@@ -1,97 +1,97 @@
# REDCap Docker部署操作手册
**<EFBFBD><EFBFBD>𧋦嚗?* v1.0
**版本：** v1.0
**最后更新：** 2026-01-02
**<EFBFBD><EFBFBD>鍂<EFBFBD>臬<EFBFBD>嚗?* Windows/Linux/Mac + Docker
**REDCap<EFBFBD><EFBFBD>𧋦嚗?* 15.8.0
**撉諹<EFBFBD><EFBFBD>嗆<EFBFBD><EFBFBD><EFBFBD>** <20>?撌脣銁<E884A3>砍𧑐Windows<77>臬<EFBFBD>撉諹<E69289><E8ABB9>朞<EFBFBD>
**适用环境：** Windows/Linux/Mac + Docker
**REDCap版本：** 15.8.0
**验证状态：** ✅ 已在本地Windows环境验证通过
---
## 📋 文档目标
<EFBFBD>祆<EFBFBD><EFBFBD>峕<EFBFBD>靘𢡱EDCap<EFBFBD>箔<EFBFBD>Docker<EFBFBD>?*<2A><><EFBFBD><EFBFBD>㚚<EFBFBD>蝵脫<E89DB5>蝔?*嚗屸<E59A97><E5B1B8>鍂鈭𠬍<E988AD>
- <EFBFBD>?<3F>砍𧑐撘<F0A79190><E69298>𤑳㴓憓?
- <EFBFBD>?<3F>輸<EFBFBD>鈭䫿CS<43>煺漣<E785BA>臬<EFBFBD>
- <EFBFBD>?<3F>駁堺蝘<E5A0BA><E89D98><EFBFBD>𡝗<EFBFBD><F0A19D97>∪膥
本手册提供REDCap基于Docker的**标准化部署流程**，适用于：
- ✅ 本地开发环境
- ✅ 阿里云ECS生产环境
- ✅ 医院私有化服务器
**<EFBFBD>詨<EFBFBD>隡睃飵嚗?*
- <EFBFBD><EFBFBD> **<EFBFBD>臬<EFBFBD><EFBFBD>?*嚗鋽ocker<65>滨蔭<E6BBA8><E894AD>辣<EFBFBD>臬銁銝滚<E98A9D><E6BB9A>臬<EFBFBD><E887AC>湔𦻖雿輻鍂
- <EFBFBD>𣑐 **銝<><E98A9D>湔<EFBFBD>?*嚗𡁜<E59A97><F0A1819C>𤑳㴓憓?<3F>煺漣<E785BA>臬<EFBFBD>嚗屸<E59A97><E5B1B8>滨㴓憓<E3B493>榆撘?
- <EFBFBD><EFBFBD> **敹恍<E695B9>罸<EFBFBD>蝵?*嚗?0<><30><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>鞾<EFBFBD>蝵?
- <EFBFBD>椘儭?**<2A>桅<EFBFBD>閫<EFBFBD><E996AB>**嚗𡁜抅鈭𤾸<E988AD><F0A4BEB8><EFBFBD>萱<EFBFBD>𤑳<EFBFBD>撉䕘<E69289>憸<EFBFBD>俈撣貉<E692A3><E8B289>桅<EFBFBD>
**核心优势：**
- 🔄 **可复用**：Docker配置文件可在不同环境直接使用
- 📦 **一致性**：开发环境=生产环境，避免环境差异
- 🚀 **快速部署**：30分钟内完成部署
- 🛡️ **问题规避**：基于实际踩坑经验，预防常见问题
---
## 🎯 部署架构
### <EFBFBD><EFBFBD><EFBFBD><EFBFBD>嗆<EFBFBD>嚗?銝枋ocker摰孵膥嚗?
### 标准架构（3个Docker容器）
```
<EFBFBD>𢞖<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>?
<EFBFBD>? REDCap Docker <EFBFBD>函蔡<EFBFBD>嗆<EFBFBD> <EFBFBD>?
<EFBFBD>鎿<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>?
<EFBFBD>? <EFBFBD>?
<EFBFBD>? <20>𢞖<EFBFBD><F0A29E96><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>? <20>?
<EFBFBD>? <20>? redcap-apache (Web摰孵膥) <EFBFBD>? <20>?
<EFBFBD>? <20>? - PHP 8.1 + Apache 2.4 <EFBFBD>? <20>?
<EFBFBD>? <20>? - REDCap 15.8.0 皞鞟<EFBFBD> <EFBFBD>? <20>?
<EFBFBD>? <20>? - Cron摰𡁏𧒄隞餃𦛚 <EFBFBD>? <20>?
<EFBFBD>? <20>? Port: 8080 <EFBFBD>?80 <EFBFBD>? <20>?
<EFBFBD>? <20>婙<EFBFBD><E5A999><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>? <20>?
<EFBFBD>? <EFBFBD>? <EFBFBD>?
<EFBFBD>? <20>𢞖<EFBFBD><F0A29E96><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>? <20>?
<EFBFBD>? <20>? redcap-mysql (<EFBFBD>唳旿摨枏捆<EFBFBD>? <EFBFBD>? <20>?
<EFBFBD>? <20>? - MySQL 8.0 <EFBFBD>? <20>?
<EFBFBD>? <20>? - <20>唳旿<E594B3><E697BF><EFBFBD><EFBFBD>?Volume) <EFBFBD>? <20>?
<EFBFBD>? <20>? Port: 3306 (<EFBFBD><EFBFBD><EFBFBD>) <EFBFBD>? <20>?
<EFBFBD>? <20>婙<EFBFBD><E5A999><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>? <20>?
<EFBFBD>? <EFBFBD>? <EFBFBD>?
<EFBFBD>? <20>𢞖<EFBFBD><F0A29E96><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>? <20>?
<EFBFBD>? <20>? redcap-phpmyadmin (蝞∠<EFBFBD>撌亙<EFBFBD>) <20>? <20>?
<EFBFBD>? <20>? - phpMyAdmin 5 <EFBFBD>? <20>?
<EFBFBD>? <20>? Port: 8081 <EFBFBD>?80 <EFBFBD>? <20>?
<EFBFBD>? <20>? (<28>舫<EFBFBD>㚁<EFBFBD>隞<EFBFBD><E99A9E><EFBFBD>𤑳㴓憓? <EFBFBD>? <20>?
<EFBFBD>? <20>婙<EFBFBD><E5A999><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>? <20>?
<EFBFBD>婙<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>?
┌─────────────────────────────────────────┐
│ REDCap Docker 部署架构 │
├─────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────┐ │
│ │ redcap-apache (Web容器) │ │
│ │ - PHP 8.1 + Apache 2.4 │ │
│ │ - REDCap 15.8.0 源码 │ │
│ │ - Cron定时任务 │ │
│ │ Port: 8080 → 80 │ │
│ └──────────────────────────────────┘ │
│ ↓ │
│ ┌──────────────────────────────────┐ │
│ │ redcap-mysql (数据库容器) │ │
│ │ - MySQL 8.0 │ │
│ │ - 数据持久化(Volume) │ │
│ │ Port: 3306 (内部) │ │
│ └──────────────────────────────────┘ │
│ ↓ │
│ ┌──────────────────────────────────┐ │
│ │ redcap-phpmyadmin (管理工具) │ │
│ │ - phpMyAdmin 5 │ │
│ │ Port: 8081 → 80 │ │
│ │ (可选，仅开发环境) │ │
│ └──────────────────────────────────┘ │
└─────────────────────────────────────────┘
```
---
## 📦 可复用的Docker文件清单
### <EFBFBD>詨<EFBFBD><EFBFBD><EFBFBD>辣嚗<EFBFBD><EFBFBD><EFBFBD><EFBFBD>嚗<EFBFBD>虾<EFBFBD>湔𦻖憭滨鍂嚗?
### 核心文件（必需，可直接复用）
| <EFBFBD><EFBFBD>辣頝臬<EFBFBD> | 霂湔<E99C82> | <20>臬<EFBFBD>撌桀<E6928C> | 憭滨鍂<E6BBA8>?|
| 文件路径 | 说明 | 环境差异 | 复用性 |
|---------|------|---------|--------|
| `Dockerfile.redcap` | REDCap<EFBFBD>𨅯<EFBFBD><EFBFBD><EFBFBD>遣<EFBFBD><EFBFBD>辣 | <20>惩榆撘?| <20>?100%<25>臬<EFBFBD><E887AC>?|
| `docker-compose.yml` | 撘<EFBFBD><EFBFBD>𤑳㴓憓<EFBFBD><EFBFBD><EFBFBD>埝<EFBFBD>隞?| <20><>靚<EFBFBD>㟲蝡臬藁/<2F>瑁楝敺?| <20>𩤃<EFBFBD> <20><>敺株<E695BA> |
| `docker-compose.prod.yml` | <EFBFBD>煺漣<EFBFBD>臬<EFBFBD>蝻𡝗<EFBFBD><EFBFBD><EFBFBD>辣 | <20><><EFBFBD>滨蔭RDS | <20>𩤃<EFBFBD> <20><>靽格㺿<E6A0BC>唳旿摨㯄<E691A8>蝵?|
| `docker-entrypoint.sh` | 摰孵膥<EFBFBD>臬𢆡<EFBFBD>𡁏𧋦 | <20>惩榆撘?| <20>?100%<25>臬<EFBFBD><E887AC>?|
| `Dockerfile.redcap` | REDCap镜像构建文件 | 无差异 | ✅ 100%可复用 |
| `docker-compose.yml` | 开发环境编排文件 | 需调整端口/卷路径 | ⚠️ 需微调 |
| `docker-compose.prod.yml` | 生产环境编排文件 | 需配置RDS | ⚠️ 需修改数据库配置 |
| `docker-entrypoint.sh` | 容器启动脚本 | 无差异 | ✅ 100%可复用 |
| `config/apache/redcap.conf` | Apache虚拟主机配置 | 需调整域名 | ⚠️ 需修改域名 |
| `config/php/php.ini` | PHP餈鞱<EFBFBD><EFBFBD>園<EFBFBD>蝵?| <20>惩榆撘?| <20>?100%<25>臬<EFBFBD><E887AC>?|
| `config/database.php` | REDCap<EFBFBD>唳旿摨栞<EFBFBD><EFBFBD>仿<EFBFBD>蝵?| **敹<>◆靽格㺿** | <20>?<3F><><EFBFBD><EFBFBD>笆<EFBFBD>臬<EFBFBD>摰𡁜<E691B0> |
| `.gitattributes` | Git<EFBFBD>Ｚ<EFBFBD>蝚西<EFBFBD><EFBFBD>?| <20>惩榆撘?| <20>?100%<25>臬<EFBFBD><E887AC>?|
| `config/php/php.ini` | PHP运行时配置 | 无差异 | ✅ 100%可复用 |
| `config/database.php` | REDCap数据库连接配置 | **必须修改** | ❌ 需针对环境定制 |
| `.gitattributes` | Git换行符规范 | 无差异 | ✅ 100%可复用 |
### 辅助脚本（可选）
| 文件路径 | 说明 | 适用场景 |
|---------|------|---------|
| `scripts/setup-redcap.ps1` | 銝<EFBFBD><EFBFBD>桅<EFBFBD>蝵脰<EFBFBD><EFBFBD>穿<EFBFBD>Windows嚗?| <20>砍𧑐撘<F0A79190><E69298>?|
| `scripts/start-redcap.ps1` | <EFBFBD>臬𢆡<EFBFBD>滚𦛚 | <20>砍𧑐撘<F0A79190><E69298>?|
| `scripts/stop-redcap.ps1` | <EFBFBD>𨀣迫<EFBFBD>滚𦛚 | <20>砍𧑐撘<F0A79190><E69298>?|
| `scripts/clean-redcap.ps1` | 皜<EFBFBD><EFBFBD><EFBFBD>臬<EFBFBD> | <20>砍𧑐撘<F0A79190><E69298>?|
| `scripts/create-redcap-password.php` | 撖<EFBFBD><EFBFBD><EFBFBD>滨蔭撌亙<EFBFBD> | 撘<><E69298>?餈鞟輕 |
| `scripts/setup-redcap.ps1` | 一键部署脚本（Windows） | 本地开发 |
| `scripts/start-redcap.ps1` | 启动服务 | 本地开发 |
| `scripts/stop-redcap.ps1` | 停止服务 | 本地开发 |
| `scripts/clean-redcap.ps1` | 清理环境 | 本地开发 |
| `scripts/create-redcap-password.php` | 密码重置工具 | 开发/运维 |
---
## <EFBFBD><EFBFBD> <20>函蔡瘚<E894A1><E7989A>嚗<EFBFBD><E59A97>0<EFBFBD>?嚗?
## 🚀 部署流程（从0到1）
### <EFBFBD>嗆挾1嚗𡁶㴓憓<EFBFBD><EFBFBD>憭?
### 阶段1：环境准备
#### 1.1 安装Docker
**Windows/Mac嚗?*
**Windows/Mac：**
```bash
# 下载并安装Docker Desktop
# https://www.docker.com/products/docker-desktop/
@@ -121,22 +121,22 @@ docker-compose --version
#### 1.2 获取REDCap源码
**<EFBFBD>滩<EFBFBD>霂湔<EFBFBD>嚗?* REDCap<61>臬<EFBFBD>銝朞蔓隞塚<E99A9E><E5A19A><EFBFBD>閬<EFBFBD><E996AC>
**重要说明：** REDCap是商业软件，需要：
1. 访问 https://projectredcap.org/
2. 注册并申请社区版或商业版
3. 銝贝蝸REDCap 15.8.0皞鞟<EFBFBD><EFBFBD><EFBFBD><EFBFBD>redcap15.8.0.zip嚗?
3. 下载REDCap 15.8.0源码包（redcap15.8.0.zip）
**<EFBFBD>桀<EFBFBD>蝏𤘪<EFBFBD>嚗?*
**目录结构：**
```
your-project/
├── redcap-docker-dev/ # Docker配置目录
<EFBFBD>? <20>鎿<EFBFBD><E98EBF><EFBFBD> Dockerfile.redcap
<EFBFBD>? <20>鎿<EFBFBD><E98EBF><EFBFBD> docker-compose.yml
<EFBFBD>? <20>鎿<EFBFBD><E98EBF><EFBFBD> docker-entrypoint.sh
<EFBFBD>? <20>鎿<EFBFBD><E98EBF><EFBFBD> config/
<EFBFBD>? <20>婙<EFBFBD><E5A999><EFBFBD> scripts/
<EFBFBD>?
<EFBFBD>婙<EFBFBD><EFBFBD><EFBFBD> redcap15.8.0/ # REDCap皞鞟<EFBFBD>嚗<EFBFBD>圾<EFBFBD>见<EFBFBD>嚗?
│ ├── Dockerfile.redcap
│ ├── docker-compose.yml
│ ├── docker-entrypoint.sh
│ ├── config/
│ └── scripts/
│
└── redcap15.8.0/ # REDCap源码（解压后）
├── redcap_v15.8.0/
├── install.php
├── index.php
@@ -153,7 +153,7 @@ your-project/
# 创建目录结构
mkdir -p redcap-docker-dev/config/{apache,php}
mkdir -p redcap-docker-dev/scripts
mkdir -p redcap-docker-dev/data/mysql # MySQL<EFBFBD>唳旿<EFBFBD><EFBFBD><EFBFBD><EFBFBD>?
mkdir -p redcap-docker-dev/data/mysql # MySQL数据持久化
mkdir -p redcap-docker-dev/logs # 日志目录
```
@@ -162,7 +162,7 @@ mkdir -p redcap-docker-dev/logs # 日志目录
**从我们的项目中复制以下文件：**
```bash
# <EFBFBD>詨<EFBFBD><EFBFBD><EFBFBD>辣嚗<EFBFBD>虾<EFBFBD>湔𦻖憭滨鍂嚗峕<EFBFBD><EFBFBD><EFBFBD>靽格㺿嚗?
# 核心文件（可直接复用，无需修改）
cp AIclinicalresearch/redcap-docker-dev/Dockerfile.redcap ./
cp AIclinicalresearch/redcap-docker-dev/docker-entrypoint.sh ./
cp AIclinicalresearch/redcap-docker-dev/config/php/php.ini ./config/php/
@@ -195,16 +195,16 @@ MYSQL_PORT=3306
PHPMYADMIN_PORT=8081
```
#### 2.4 靽格㺿database.php嚗<EFBFBD><EFBFBD>閬<EFBFBD><EFBFBD>嚗?
#### 2.4 修改database.php（重要！）
编辑`config/database.php`，根据环境修改：
**开发环境（Docker MySQL）：**
```php
$hostname = 'redcap-mysql'; // Docker Compose<EFBFBD>滚𦛚<EFBFBD>?
$hostname = 'redcap-mysql'; // Docker Compose服务名
$db = 'redcap';
$username = 'redcap_user';
$password = 'your_password'; // 銝?env靽脲<EFBFBD>銝<EFBFBD><EFBFBD>?
$password = 'your_password'; // 与.env保持一致
$salt = 'dev_salt_2026'; // 开发环境固定salt
```
@@ -214,13 +214,13 @@ $hostname = 'rm-xxx.mysql.rds.aliyuncs.com'; // RDS内网地址
$db = 'redcap_prod';
$username = 'redcap_admin';
$password = 'your_strong_prod_password'; // 强密码！
$salt = 'your_random_32_chars_salt'; // <EFBFBD>𩤃<EFBFBD> 瘞訾<E7989E><E8A8BE>臬<EFBFBD>嚗?
$salt = 'your_random_32_chars_salt'; // ⚠️ 永不可变！
```
**<2A>𩤃<EFBFBD> <20>喲睸瘜冽<E7989C>鈭钅★嚗?*
1. <20>?**<2A>𣳇膄<F0A3B387><E88684>辣<EFBFBD>怠偏<E680A0><E5818F>?>`<EFBFBD>𣬚征銵?*嚗<>俈甇＄RLF瘙⊥<E79899>嚗?
2. <EFBFBD>?**Salt<EFBFBD>潔<EFBFBD><EFBFBD>西挽蝵格偶銝滚虾<EFBFBD>?*嚗<>蔣<EFBFBD>齿㺭<E9BDBF>桀縧<E6A180><E7B8A7><EFBFBD><EFBFBD>吔<EFBFBD>
3. <EFBFBD>?**<2A>煺漣<E785BA>臬<EFBFBD>雿輻鍂撘箏<E69298><E7AE8F>?*嚗?2+摮㛖泵嚗?
**⚠️ 关键注意事项：**
1. ✅ **删除文件末尾的`?>`和空行**（防止CRLF污染）
2. ✅ **Salt值一旦设置永不可改**（影响数据去标识化）
3. ✅ **生产环境使用强密码**（32+字符）
---
@@ -234,37 +234,37 @@ $salt = 'your_random_32_chars_salt'; // ⚠️ 永不可变
services:
redcap-web:
volumes:
# 撠<EFBFBD>EDCap皞鞟<EFBFBD><EFBFBD><EFBFBD>蝸<EFBFBD>啣捆<EFBFBD>?
# 将REDCap源码挂载到容器
- ../redcap15.8.0:/var/www/html/redcap:ro # 只读挂载
# 撠<EFBFBD>atabase.php憭滚<EFBFBD><EFBFBD>啣捆<EFBFBD>剁<EFBFBD>霂餃<EFBFBD>嚗?
# 将database.php复制到容器（读写）
- ./config/database.php:/var/www/html/redcap/database.php
```
**頝臬<EFBFBD>霂湔<EFBFBD>嚗?*
**路径说明：**
- `../redcap15.8.0`：相对于`redcap-docker-dev`目录
- 如果源码在其他位置，修改为绝对路径：`D:/path/to/redcap15.8.0`
#### 3.2 <EFBFBD><EFBFBD>遣撟嗅鍳<EFBFBD>典捆<EFBFBD>?
#### 3.2 构建并启动容器
```bash
# 进入Docker配置目录
cd redcap-docker-dev
# <EFBFBD><EFBFBD>遣REDCap<EFBFBD>𨅯<EFBFBD>嚗<EFBFBD><EFBFBD>甈⊿<EFBFBD>蝵脤<EFBFBD>閬<EFBFBD><EFBFBD>蝥?-10<31><30><EFBFBD>嚗?
# 构建REDCap镜像（首次部署需要，约5-10分钟）
docker-compose build
# <EFBFBD>臬𢆡<EFBFBD><EFBFBD><EFBFBD>㗇<EFBFBD><EFBFBD>?
# 启动所有服务
docker-compose up -d
# <EFBFBD>亦<EFBFBD>摰孵膥<EFBFBD>嗆<EFBFBD>?
# 查看容器状态
docker-compose ps
# 查看日志（排查问题）
docker-compose logs -f redcap-web
```
**憸<EFBFBD><EFBFBD>颲枏枂嚗?*
**预期输出：**
```
NAME IMAGE STATUS PORTS
redcap-apache redcap-custom:15.8.0 Up 10 seconds 0.0.0.0:8080->80/tcp
@@ -278,7 +278,7 @@ redcap-phpmyadmin phpmyadmin/phpmyadmin Up 10 seconds 0.0.0.0:8081->80/tcp
1. 访问 `http://localhost:8080/install.php`
2. 按照向导完成安装
3. <EFBFBD>𥕦遣蝞∠<EFBFBD><EFBFBD>䁅揭<EFBFBD>?
3. 创建管理员账户
**方法2：导入SQL文件**
@@ -286,72 +286,72 @@ redcap-phpmyadmin phpmyadmin/phpmyadmin Up 10 seconds 0.0.0.0:8081->80/tcp
# 如果有现成的redcap_install.sql
docker exec -i redcap-mysql mysql -uredcap_user -p'your_password' redcap < redcap_install.sql
# <EFBFBD>滨蔭蝞∠<EFBFBD><EFBFBD>睃<EFBFBD><EFBFBD>?
# 重置管理员密码
docker cp scripts/create-redcap-password.php redcap-apache:/tmp/
docker exec redcap-apache php /tmp/create-redcap-password.php
```
---
### <EFBFBD>嗆挾4嚗𡁻<EFBFBD>霂<EFBFBD><EFBFBD>蝵?
### 阶段4：验证部署
#### 4.1 访问REDCap
**銝駁△嚗?* http://localhost:8080/
**主页：** http://localhost:8080/
**憸<EFBFBD><EFBFBD>蝏𤘪<EFBFBD>嚗?*
- <EFBFBD>?憿菟𢒰甇<F0A292B0>虜<EFBFBD>曄內嚗峕<E59A97>REDCap Logo
- <EFBFBD>?CSS/JS<EFBFBD>㰘蝸甇<EFBFBD>虜嚗峕<EFBFBD>404<EFBFBD>躰秤
- <EFBFBD>?<3F>餃<EFBFBD>獢<EFBFBD>虾閫?
**预期结果：**
- ✅ 页面正常显示，有REDCap Logo
- ✅ CSS/JS加载正常，无404错误
- ✅ 登录框可见
**憒<EFBFBD><EFBFBD>憿菟𢒰<EFBFBD>瑕<EFBFBD><EFBFBD>嗘僚嚗?* <20><><EFBFBD>銝𧢲䲮"<22>桅<EFBFBD><E6A185>埝䰻"蝡㰘<E89DA1>
**如果页面样式错乱：** 参见下方"问题排查"章节
#### 4.2 测试登录
**暺䁅恕韐行<EFBFBD>嚗?*
**默认账户：**
- Username: `Admin`
- Password: `Admin123!`嚗<EFBFBD><EFBFBD>雿㰘挽蝵桃<EFBFBD>撖<EFBFBD><EFBFBD>嚗?
- Password: `Admin123!`（或你设置的密码）
**憸<EFBFBD><EFBFBD>蝏𤘪<EFBFBD>嚗?*
- <EFBFBD>?<3F>餃<EFBFBD><E9A483>𣂼<EFBFBD>嚗諹歲頧砍<E9A0A7>銝駁△
- <EFBFBD>?<3F>臭誑<E887AD>见<EFBFBD>"Control Center"<EFBFBD>?My Projects"蝑㕑<EFBFBD><EFBFBD>?
**预期结果：**
- ✅ 登录成功，跳转到主页
- ✅ 可以看到"Control Center"、"My Projects"等菜单
#### 4.3 访问phpMyAdmin
**<EFBFBD>啣<EFBFBD>嚗?* http://localhost:8081/
**地址：** http://localhost:8081/
**<EFBFBD>餃<EFBFBD>靽⊥<EFBFBD>嚗?*
**登录信息：**
- 服务器：`redcap-mysql`
- 用户名：`redcap_user`
- 密码：（与database.php中的密码一致）
**验证数据库：**
- <EFBFBD>?<3F>臭誑<E887AD>见<EFBFBD>`redcap`<EFBFBD>唳旿摨?
- <EFBFBD>?<3F>?00+撘㰘”嚗<E2809D><E59A97>`redcap_config`, `redcap_user_information`蝑㚁<EFBFBD>
- ✅ 可以看到`redcap`数据库
- ✅ 有100+张表（如`redcap_config`, `redcap_user_information`等）
---
## <EFBFBD>𩤃<EFBFBD> 撣貉<E692A3><E8B289>桅<EFBFBD>銝舘圾<E88898>單䲮獢?
## ⚠️ 常见问题与解决方案
### 问题1：ERR_CONTENT_DECODING_FAILED
**<EFBFBD>啗情嚗?*
**现象：**
- 浏览器访问REDCap时报错：`net::ERR_CONTENT_DECODING_FAILED 200 (OK)`
- CSS/JS文件加载失败
**<EFBFBD>寞𧋦<EFBFBD>笔<EFBFBD>嚗?*
Apache<EFBFBD><EFBFBD>mod_deflate`璅∪<E79285>銝窰HP<48><50>zlib.output_compression`<EFBFBD>脩<EFBFBD>嚗<EFBFBD>紡<EFBFBD>湔㺭<EFBFBD>株◤<EFBFBD>滚<EFBFBD><EFBFBD>讠憬<EFBFBD>?
**根本原因：**
Apache的`mod_deflate`模块与PHP的`zlib.output_compression`冲突，导致数据被重复压缩。
**閫<EFBFBD><EFBFBD><EFBFBD>寞<EFBFBD>嚗?*
**解决方案：**
<EFBFBD>?**<2A>睲賑<E79DB2><E8B391>ocker<65>滨蔭撌脰䌊<E884B0>其耨憭齿迨<E9BDBF>桅<EFBFBD>嚗?*
✅ **我们的Docker配置已自动修复此问题：**
1. `docker-entrypoint.sh`<EFBFBD>芸𢆡蝳<EFBFBD>鍂`deflate`璅∪<EFBFBD>嚗?
1. `docker-entrypoint.sh`自动禁用`deflate`模块：
```bash
a2dismod -f deflate
```
2. `php.ini`銝剖歇<EFBFBD>喲𡡒<EFBFBD>讠憬嚗?
2. `php.ini`中已关闭压缩：
```ini
zlib.output_compression = Off
output_buffering = Off
@@ -359,9 +359,9 @@ Apache的`mod_deflate`模块与PHP的`zlib.output_compression`冲突，导致数
3. `redcap.conf`中注释掉了`mod_deflate`配置
**憒<EFBFBD><EFBFBD>餈䀹<EFBFBD><EFBFBD>桅<EFBFBD>嚗?*
**如果还有问题：**
```bash
# 餈𥕦<E9A488>摰孵膥璉<E886A5><E79289>?
# 进入容器检查
docker exec redcap-apache bash -c "apache2ctl -M | grep deflate"
# 应该没有输出
@@ -371,60 +371,60 @@ docker-compose restart redcap-web
---
### <EFBFBD>桅<EFBFBD>2嚗𡁶蒈敶訫仃韐?- <20>䭾<EFBFBD><E4ADBE>㰘蝸<E3B098>滚<EFBFBD><E6BB9A>唳旿
### 问题2：登录失败 - 无法加载响应数据
**<EFBFBD>啗情嚗?*
**现象：**
- 输入用户名密码后，页面不跳转
- Network面板显示POST请求返回200，但"无法加载响应数据"
**<EFBFBD>寞𧋦<EFBFBD>笔<EFBFBD>嚗?*
`database.php`<EFBFBD><EFBFBD>辣<EFBFBD>怠偏<EFBFBD>头?>`PHP蝏𤘪<E89D8F><F0A498AA><EFBFBD>倌<EFBFBD>𣬚征銵䕘<E98AB5>撖潸稲CRLF<4C>Ｚ<EFBFBD>蝚行情<E8A18C>鐈TTP<54>滚<EFBFBD><E6BB9A>?
**根本原因：**
`database.php`文件末尾有`?>`PHP结束标签和空行，导致CRLF换行符污染HTTP响应。
**閫<EFBFBD><EFBFBD><EFBFBD>寞<EFBFBD>嚗?*
**解决方案：**
<EFBFBD>?**<2A>睲賑<E79DB2>𣂷<EFBFBD><F0A382B7><EFBFBD>database.php`璅⊥踎撌脖耨憭齿迨<EFBFBD>桅<EFBFBD>嚗?*
✅ **我们提供的`database.php`模板已修复此问题：**
1. <20>?<3F><>辣<EFBFBD>怠偏**瘝⊥<E7989D>`?>`**
2. <20>?<3F><>辣<EFBFBD>怠偏**瘝⊥<E7989D>蝛箄<E89D9B>**
3. <20>?`.gitattributes`撘箏<EFBFBD>PHP<EFBFBD><EFBFBD>辣雿輻鍂LF<EFBFBD>Ｚ<EFBFBD>蝚?
1. ✅ 文件末尾**没有`?>`**
2. ✅ 文件末尾**没有空行**
3. ✅ `.gitattributes`强制PHP文件使用LF换行符
**憒<EFBFBD><EFBFBD><EFBFBD>芸楛<EFBFBD>𥕦遣database.php嚗?*
**如果自己创建database.php：**
```php
<?php
// <EFBFBD>唳旿摨㯄<EFBFBD>蝵?..
// 数据库配置...
$hostname = 'redcap-mysql';
$db = 'redcap';
// ...
// <EFBFBD>?<3F>躰秤<E8BAB0>蹱<EFBFBD>嚗?
// ❌ 错误写法：
?>
// <EFBFBD>?甇<>＆<EFBFBD>蹱<EFBFBD>嚗𡁏<E59A97>隞嗆錰撠曉蘨<E69B89>㗇釣<E39787>羓<EFBFBD>蝏𤘪<E89D8F>蝚佗<E89D9A>瘝⊥<E7989D>?>
// ✅ 正确写法：文件末尾只有注释的结束符，没有?>
```
**撉諹<EFBFBD><EFBFBD>寞<EFBFBD>嚗?*
**验证方法：**
```bash
# 璉<><E79289>交<EFBFBD>隞嗆錰撠橘<E692A0><E6A998><EFBFBD><EFBFBD>餈𥕦<E9A488>嚗?
# 检查文件末尾（十六进制）
docker exec redcap-apache bash -c "tail -c 50 /var/www/html/redcap/database.php | xxd"
# 摨磰砲<EFBFBD>见<EFBFBD>嚗?
# 00000030: 2a2f 0a # */ <EFBFBD>峕揢銵𣬚泵嚗峕瓷<EFBFBD>??> <20><><EFBFBD>雿嗵<E99BBF>0d0a
# 应该看到：
# 00000030: 2a2f 0a # */ 和换行符，没有 ?> 和多余的0d0a
```
---
### 问题3：Base URL配置错误
**<EFBFBD>啗情嚗?*
**现象：**
- CSS/JS文件路径错误，例如：`http://localhost:8080/redcap/redcap_v15.8.0/Resources/...`
- 实际路径应该是：`http://localhost:8080/redcap_v15.8.0/Resources/...`
**<EFBFBD>寞𧋦<EFBFBD>笔<EFBFBD>嚗?*
REDCap<EFBFBD>唳旿摨㮖葉<EFBFBD><EFBFBD>redcap_base_url`<EFBFBD>滨蔭銝垾pache<EFBFBD><EFBFBD>DocumentRoot`銝滚龪<EFBFBD>溻<EFBFBD>?
**根本原因：**
REDCap数据库中的`redcap_base_url`配置与Apache的`DocumentRoot`不匹配。
**閫<EFBFBD><EFBFBD><EFBFBD>寞<EFBFBD>嚗?*
**解决方案：**
```sql
-- 连接到MySQL容器
@@ -444,30 +444,30 @@ WHERE field_name = 'redcap_base_url';
-- WHERE field_name = 'redcap_base_url';
```
**憸<EFBFBD>俈<EFBFBD>芣鴌嚗?*
- 摰㕑<E691B0><E39591>嗥＆靽𨈚ase URL銝舘挪<E88898>桀𧑐<E6A180><F0A79190>銝<EFBFBD><E98A9D>?
- 靽格㺿<E6A0BC>𡡞<EFBFBD><F0A1A19E>舀<EFBFBD>閫<EFBFBD>膥<EFBFBD>𡝗<EFBFBD><F0A19D97>斤<EFBFBD>摮?
**预防措施：**
- 安装时确保Base URL与访问地址一致
- 修改后重启浏览器或清除缓存
---
### <EFBFBD>桅<EFBFBD>4嚗𡁜捆<EFBFBD>典鍳<EFBFBD>典仃韐?
### 问题4：容器启动失败
**常见原因与解决方案：**
**4.1 蝡臬藁鋡怠<EFBFBD><EFBFBD>?*
**4.1 端口被占用**
```bash
# 璉<><E79289>亦垢<E4BAA6><E59EA2><EFBFBD><EFBFBD>?
# 检查端口占用
netstat -ano | findstr ":8080" # Windows
lsof -i :8080 # Linux/Mac
# 解决方案1：修改docker-compose.yml端口映射
ports:
- "8090:80" # <EFBFBD>嫣蛹8090<EFBFBD>硋<EFBFBD>隞𣇉垢<EFBFBD>?
- "8090:80" # 改为8090或其他端口
# 解决方案2：停止占用端口的程序
```
**4.2 <EFBFBD>瑟<EFBFBD>頧質楝敺<EFBFBD><EFBFBD>霂?*
**4.2 卷挂载路径错误**
```bash
# 检查REDCap源码路径是否存在
ls -la ../redcap15.8.0
@@ -477,7 +477,7 @@ volumes:
- /absolute/path/to/redcap15.8.0:/var/www/html/redcap:ro
```
**4.3 <EFBFBD><EFBFBD><EFBFBD><EFBFBD>桅<EFBFBD>嚗𡿨inux嚗?*
**4.3 权限问题（Linux）**
```bash
# 给予Docker目录适当权限
sudo chown -R $(whoami):$(whoami) redcap-docker-dev/
@@ -488,14 +488,14 @@ chmod +x docker-entrypoint.sh
### 问题5：MySQL连接失败
**<EFBFBD>啗情嚗?*
**现象：**
- REDCap显示"Database connection failed"
- 日志中有MySQL连接错误
**<EFBFBD>埝䰻甇仿炊嚗?*
**排查步骤：**
```bash
# 1. 璉<EFBFBD><EFBFBD>仗ySQL摰孵膥<EFBFBD>嗆<EFBFBD>?
# 1. 检查MySQL容器状态
docker-compose ps redcap-mysql
# 2. 查看MySQL日志
@@ -508,40 +508,40 @@ docker exec -it redcap-mysql mysql -uredcap_user -p'your_password'
docker exec redcap-apache cat /var/www/html/redcap/database.php | grep hostname
```
**撣貉<EFBFBD><EFBFBD>躰秤嚗?*
- `$hostname`<EFBFBD>蹱<EFBFBD>鈭<EFBFBD>localhost`嚗<EFBFBD><EFBFBD>霂交糓`redcap-mysql`嚗?
**常见错误：**
- `$hostname`写成了`localhost`（应该是`redcap-mysql`）
- 密码不匹配（与`.env`或`docker-compose.yml`不一致）
- MySQL容器未完全启动（等待30秒再试）
---
## <EFBFBD><EFBFBD> 銝滚<E98A9D><E6BB9A>臬<EFBFBD><E887AC><EFBFBD><EFBFBD>蝵桀榆撘?
## 🔄 不同环境的配置差异
### <EFBFBD>砍𧑐撘<EFBFBD><EFBFBD>𤑳㴓憓?
### 本地开发环境
**<EFBFBD>寧<EFBFBD>嚗?*
**特点：**
- 使用Docker MySQL容器
- 包含phpMyAdmin
- 端口映射到localhost
- 撘<><E69298>𤏸<EFBFBD>霂閙芋撘?
- 开发调试模式
**<EFBFBD><EFBFBD>閬<EFBFBD>耨<EFBFBD>寧<EFBFBD><EFBFBD>滨蔭嚗?*
1. `docker-compose.yml`嚗帋蝙<EFBFBD>券<EFBFBD>霈日<EFBFBD>蝵?
**需要修改的配置：**
1. `docker-compose.yml`：使用默认配置
2. `database.php`：`$hostname = 'redcap-mysql'`
---
### 阿里云ECS生产环境
**<EFBFBD>寧<EFBFBD>嚗?*
**特点：**
- 使用阿里云RDS MySQL
- 銝滚<E98A9D><E6BB9A>厚hpMyAdmin嚗<6E><E59A97><EFBFBD>刻<EFBFBD><E588BB><EFBFBD>嚗?
- 不包含phpMyAdmin（安全考虑）
- 使用域名+SSL证书
- 生产优化配置
**<EFBFBD><EFBFBD>閬<EFBFBD>耨<EFBFBD>寧<EFBFBD><EFBFBD>滨蔭嚗?*
**需要修改的配置：**
1. **雿輻鍂`docker-compose.prod.yml`嚗?*
1. **使用`docker-compose.prod.yml`：**
```yaml
services:
redcap-web:
@@ -551,36 +551,36 @@ docker exec redcap-apache cat /var/www/html/redcap/database.php | grep hostname
# 移除redcap-mysql和redcap-phpmyadmin服务
```
2. **靽格㺿`database.php`嚗?*
2. **修改`database.php`：**
```php
$hostname = 'rm-xxx.mysql.rds.aliyuncs.com'; // RDS内网地址
$db = 'redcap_prod';
$username = 'redcap_admin';
$password = 'your_strong_password_32_chars_min'; // 撘箏<EFBFBD><EFBFBD>?
$password = 'your_strong_password_32_chars_min'; // 强密码
$salt = 'your_random_salt_never_change'; // 永不可变
// <EFBFBD>舐鍂SSL餈墧𦻖嚗<EFBFBD>虾<EFBFBD>劐<EFBFBD><EFBFBD>刻<EFBFBD>嚗?
// 启用SSL连接（可选但推荐）
$db_ssl_ca = '/path/to/rds-ca.pem';
$db_ssl_verify_server_cert = true;
```
3. **靽格㺿`redcap.conf`嚗?*
3. **修改`redcap.conf`：**
```apache
ServerName redcap.yourdomain.com
```
4. **<EFBFBD><EFBFBD>遣撟嗆綫<EFBFBD><EFBFBD><EFBFBD><EFBFBD>誩<EFBFBD>ACR嚗?*
4. **构建并推送镜像到ACR：**
```bash
# <EFBFBD>餃<EFBFBD><EFBFBD>輸<EFBFBD>鈭穃捆<EFBFBD>券<EFBFBD><EFBFBD>𤩺<EFBFBD><EFBFBD>?
# 登录阿里云容器镜像服务
docker login --username=your_username registry.cn-hangzhou.aliyuncs.com
# 构建镜像
docker build -f Dockerfile.redcap -t redcap-custom:15.8.0 .
# <EFBFBD>𤘪<EFBFBD>蝑?
# 打标签
docker tag redcap-custom:15.8.0 registry.cn-hangzhou.aliyuncs.com/your-namespace/redcap:15.8.0
# <EFBFBD>券<EFBFBD>?
# 推送
docker push registry.cn-hangzhou.aliyuncs.com/your-namespace/redcap:15.8.0
```
@@ -595,19 +595,19 @@ docker exec redcap-apache cat /var/www/html/redcap/database.php | grep hostname
---
### <EFBFBD>駁堺蝘<EFBFBD><EFBFBD><EFBFBD>㚚<EFBFBD>蝵?
### 医院私有化部署
**<EFBFBD>寧<EFBFBD>嚗?*
**特点：**
- 内网环境，无外网访问
- 可能无法使用Docker Hub
- 需要数据安全与合规
- 可能需要集成医院HIS系统
**<EFBFBD>函蔡甇仿炊嚗?*
**部署步骤：**
1. **蝳餌瑪<EFBFBD><EFBFBD><EFBFBD>Docker<EFBFBD>𨅯<EFBFBD>嚗?*
1. **离线准备Docker镜像：**
```bash
# <EFBFBD>冽<EFBFBD>蝵𤑳<EFBFBD><EFBFBD><EFBFBD>㴓憓<EFBFBD>紡<EFBFBD>粹<EFBFBD><EFBFBD>?
# 在有网络的环境导出镜像
docker save redcap-custom:15.8.0 mysql:8.0 phpmyadmin/phpmyadmin:latest > redcap-images.tar
# 传输到医院服务器
@@ -618,10 +618,10 @@ docker exec redcap-apache cat /var/www/html/redcap/database.php | grep hostname
```
2. **配置内网数据库：**
- 雿輻鍂<EFBFBD>駁堺<EFBFBD>芸楛<EFBFBD><EFBFBD>ySQL<EFBFBD>滚𦛚<EFBFBD>?
- <EFBFBD>㚚<EFBFBD>蝵脩𡠺蝡讠<EFBFBD>MySQL摰孵膥嚗<EFBFBD>㺭<EFBFBD>桃𤌍敶閙<EFBFBD>頧賢<EFBFBD><EFBFBD>駁堺摮睃<EFBFBD>嚗?
- 使用医院自己的MySQL服务器
- 或部署独立的MySQL容器（数据目录挂载到医院存储）
3. **<EFBFBD>唳旿摰匧<EFBFBD><EFBFBD>滨蔭嚗?*
3. **数据安全配置：**
- 启用数据库SSL连接
- 配置定期备份
- 日志审计
@@ -629,45 +629,45 @@ docker exec redcap-apache cat /var/www/html/redcap/database.php | grep hostname
---
## <EFBFBD><EFBFBD> <20>函蔡璉<E894A1><E79289>交<EFBFBD><E4BAA4>?
## 📋 部署检查清单
### <EFBFBD>函蔡<EFBFBD>齿<EFBFBD><EFBFBD>?
### 部署前检查
- [ ] Docker撌脣<EFBFBD>鋆<EFBFBD>僎餈鞱<EFBFBD>嚗Ǒdocker --version`嚗?
- [ ] Docker Compose撌脣<EFBFBD>鋆<EFBFBD><EFBFBD>`docker-compose --version`嚗?
- [ ] Docker已安装并运行（`docker --version`）
- [ ] Docker Compose已安装（`docker-compose --version`）
- [ ] REDCap源码已下载并解压
- [ ] 已复制所有Docker配置文件
- [ ] `database.php`撌脫覔<EFBFBD>桃㴓憓<EFBFBD>耨<EFBFBD>?
- [ ] `database.php`<EFBFBD>怠偏**瘝⊥<E7989D>`?>`<EFBFBD>𣬚征銵?*
- [ ] `database.php`已根据环境修改
- [ ] `database.php`末尾**没有`?>`和空行**
- [ ] `.env`文件已创建（如使用）
- [ ] 蝡臬藁<E887AC>惩<EFBFBD>蝒<EFBFBD><E89D92>8080, 3306, 8081嚗?
- [ ] 端口无冲突（8080, 3306, 8081）
### <EFBFBD>函蔡<EFBFBD>𡡞<EFBFBD>霂?
### 部署后验证
- [ ] 摰孵膥<E5ADB5>券<EFBFBD><E588B8>臬𢆡嚗Ǒdocker-compose ps`嚗?
- [ ] <20>臭誑霈輸䔮REDCap擐㚚△嚗áttp://localhost:8080/嚗?
- [ ] 容器全部启动（`docker-compose ps`）
- [ ] 可以访问REDCap首页（http://localhost:8080/）
- [ ] 页面样式正常，无404错误
- [ ] 可以成功登录
- [ ] phpMyAdmin<EFBFBD>航挪<EFBFBD>殷<EFBFBD>http://localhost:8081/嚗?
- [ ] <20>唳旿摨栞”撌脣<E6928C>撱綽<E692B1>100+撘㰘”嚗?
- [ ] phpMyAdmin可访问（http://localhost:8081/）
- [ ] 数据库表已创建（100+张表）
- [ ] 可以创建项目
- [ ] 可以创建表单
- [ ] 数据可以正常保存
### <EFBFBD>煺漣<EFBFBD>臬<EFBFBD>憸嘥<EFBFBD>璉<EFBFBD><EFBFBD>?
### 生产环境额外检查
- [ ] 雿輻鍂撘箏<E69298><E7AE8F><EFBFBD><EFBFBD>32+摮㛖泵嚗?
- [ ] Salt<EFBFBD>澆歇霈曄蔭銝𥪜<EFBFBD>隞?
- [ ] 使用强密码（32+字符）
- [ ] Salt值已设置且备份
- [ ] 使用HTTPS + SSL证书
- [ ] 防火墙规则已配置
- [ ] 数据库定期备份已配置
- [ ] <20>亙<EFBFBD><E4BA99>烐綉撌脤<E6928C>蝵?
- [ ] <20>笔<EFBFBD>DNS撌脰圾<E884B0>?
- [ ] 日志监控已配置
- [ ] 域名DNS已解析
- [ ] 邮件服务已配置（可选）
---
## <EFBFBD><EFBFBD>儭?<3F>亙虜蝏湔擪<E6B994>賭誘
## 🛠️ 日常维护命令
### 容器管理
@@ -681,10 +681,10 @@ docker-compose stop
# 重启服务
docker-compose restart
# <EFBFBD>𨀣迫撟嗅<EFBFBD><EFBFBD>文捆<EFBFBD>剁<EFBFBD><EFBFBD>唳旿靽萘<EFBFBD>嚗?
# 停止并删除容器（数据保留）
docker-compose down
# <EFBFBD>𨀣迫撟嗅<EFBFBD><EFBFBD>文捆<EFBFBD>?<3F>唳旿嚗<E697BF>暒<EFBFBD>抬<EFBFBD>嚗?
# 停止并删除容器+数据（危险！）
docker-compose down -v
# 查看日志
@@ -696,13 +696,13 @@ docker exec -it redcap-apache bash
docker exec -it redcap-mysql bash
```
### 憭<EFBFBD>遢銝擧<EFBFBD>憭?
### 备份与恢复
```bash
# 憭<>遢<EFBFBD>唳旿摨?
# 备份数据库
docker exec redcap-mysql mysqldump -uredcap_user -p'password' redcap > backup_$(date +%Y%m%d).sql
# <EFBFBD>Ｗ<EFBFBD><EFBFBD>唳旿摨?
# 恢复数据库
docker exec -i redcap-mysql mysql -uredcap_user -p'password' redcap < backup_20260102.sql
# 备份edocs和temp目录
@@ -710,10 +710,10 @@ docker cp redcap-apache:/var/www/html/redcap/edocs ./backup_edocs
docker cp redcap-apache:/var/www/html/redcap/temp ./backup_temp
```
### <EFBFBD>滨蔭蝞∠<EFBFBD><EFBFBD>睃<EFBFBD><EFBFBD>?
### 重置管理员密码
```bash
# 雿輻鍂<E8BCBB>睲賑<E79DB2>𣂷<EFBFBD><F0A382B7><EFBFBD><EFBFBD><EFBFBD>?
# 使用我们提供的脚本
docker cp scripts/create-redcap-password.php redcap-apache:/tmp/
docker exec redcap-apache php /tmp/create-redcap-password.php
@@ -725,25 +725,25 @@ docker exec redcap-apache php /tmp/create-redcap-password.php
## 📚 相关文档
- **问题排查详解**：[13-部署问题排查手册.md](./13-部署问题排查手册.md)
- **API撘<EFBFBD><EFBFBD>?*嚗靀../03-API撖寞𦻖銝𤾸<EFBFBD><EFBFBD>?30-REDCap_API雿輻鍂<EFBFBD><EFBFBD><EFBFBD>.md](../03-API撖寞𦻖銝𤾸<EFBFBD><EFBFBD>?30-REDCap_API雿輻鍂<EFBFBD><EFBFBD><EFBFBD>.md)
- **蝟餌<E89D9F><E9A48C>滨蔭**嚗靀../02-蝟餌<E89D9F><E9A48C>滨蔭銝舘<E98A9D>蝏?20-REDCap蝟餌<E89D9F><E9A48C>滨蔭<E6BBA8>见<EFBFBD>.md](../02-蝟餌<E89D9F><E9A48C>滨蔭銝舘<E98A9D>蝏?20-REDCap蝟餌<E89D9F><E9A48C>滨蔭<E6BBA8>见<EFBFBD>.md)
- **API开发**：[../03-API对接与开发/30-REDCap_API使用指南.md](../03-API对接与开发/30-REDCap_API使用指南.md)
- **系统配置**：[../02-系统配置与运维/20-REDCap系统配置手册.md](../02-系统配置与运维/20-REDCap系统配置手册.md)
- **REDCap官方文档**：https://projectredcap.org/
---
## <EFBFBD>?<3F>餌<EFBFBD>
## ✅ 总结
**我们提供的Docker配置文件经过实战验证，已解决所有常见问题：**
1. <20>?**Gzip<EFBFBD>讠憬<EFBFBD>脩<EFBFBD>** <20>?<3F>芸𢆡蝳<F0A286A1>鍂deflate璅∪<EFBFBD>
2. <20>?**CRLF瘙⊥<EFBFBD>** <EFBFBD>?database.php<EFBFBD>鮏?>`嚗?gitattributes閫<EFBFBD><EFBFBD><EFBFBD>Ｚ<EFBFBD>蝚?
3. <EFBFBD>?**Base URL<EFBFBD>躰秤** <20>?<3F><>﹝<EFBFBD>𡒊＆霂湔<E99C82><E6B994>滨蔭<E6BBA8>寞<EFBFBD>
4. <EFBFBD>?**頝典像<E585B8>啣<EFBFBD>摰?* <20>?Windows/Linux/Mac<EFBFBD><EFBFBD>虾雿輻鍂
1. ✅ **Gzip压缩冲突** → 自动禁用deflate模块
2. ✅ **CRLF污染** → database.php无`?>`，.gitattributes规范换行符
3. ✅ **Base URL错误** → 文档明确说明配置方法
4. ✅ **跨平台兼容** → Windows/Linux/Mac均可使用
**可复用性：**
- <EFBFBD><EFBFBD> **Dockerfile.redcap**嚗?00%<25>臬<EFBFBD><E887AC>剁<EFBFBD><E58981>𣳇<EFBFBD>隞颱<E99A9E>靽格㺿
- <EFBFBD><EFBFBD> **docker-entrypoint.sh**嚗?00%<25>臬<EFBFBD><E887AC>?
- <EFBFBD><EFBFBD> **php.ini**嚗?00%<25>臬<EFBFBD><E887AC>?
- 🔄 **Dockerfile.redcap**：100%可复用，无需任何修改
- 🔄 **docker-entrypoint.sh**：100%可复用
- 🔄 **php.ini**：100%可复用
- ⚠️ **docker-compose.yml**：需根据环境调整端口和卷路径
- ⚠️ **database.php**：必须根据环境定制数据库连接信息
@@ -754,8 +754,7 @@ docker exec redcap-apache php /tmp/create-redcap-password.php
---
**<EFBFBD>厰䔮憸矋<EFBFBD>** <20>亦<EFBFBD> [13-<2D>函蔡<E587BD>桅<EFBFBD><E6A185>埝䰻<E59F9D>见<EFBFBD>.md](./13-<2D>函蔡<E587BD>桅<EFBFBD><E6A185>埝䰻<E59F9D>见<EFBFBD>.md) <EFBFBD>𡝗<EFBFBD>Issue嚗?
**有问题？** 查看 [13-部署问题排查手册.md](./13-部署问题排查手册.md) 或提Issue！

122
docs/03-业务模块/Redcap/01-部署与配置/13-部署问题排查手册.md
View File

@@ -1,19 +1,19 @@
# REDCap Docker 本地部署问题解决记录
**<EFBFBD>交<EFBFBD>嚗?* 2026-01-02
**<EFBFBD><EFBFBD>𧋦嚗?* REDCap 15.8.0
**<EFBFBD>臬<EFBFBD>嚗?* Windows 10 + Docker Desktop + Docker Compose
**日期：** 2026-01-02
**版本：** REDCap 15.8.0
**环境：** Windows 10 + Docker Desktop + Docker Compose
---
## 📋 部署成功确认
<EFBFBD>?**REDCap 15.8.0 撌脫<EFBFBD><EFBFBD>罸<EFBFBD>蝵脣銁<EFBFBD>砍𧑐Docker<EFBFBD>臬<EFBFBD>**
✅ **REDCap 15.8.0 已成功部署在本地Docker环境**
- **霈輸䔮<EFBFBD>啣<EFBFBD>嚗?* http://localhost:8080/
- **访问地址：** http://localhost:8080/
- **管理员账户：** Admin / Admin123!
- **<EFBFBD>唳旿摨橒<EFBFBD>** MySQL 8.0嚗㇄ocker摰孵膥嚗?
- **PHPMyAdmin嚗?* http://localhost:8081/
- **数据库：** MySQL 8.0（Docker容器）
- **PHPMyAdmin：** http://localhost:8081/
---
@@ -21,25 +21,25 @@
### 问题1：ERR_CONTENT_DECODING_FAILED
**<EFBFBD>啗情嚗?*
**现象：**
- 浏览器访问REDCap首页时报错：`net::ERR_CONTENT_DECODING_FAILED 200 (OK)`
- CSS/JS资源加载失败
**<EFBFBD>寞𧋦<EFBFBD>笔<EFBFBD>嚗?*
**根本原因：**
1. Apache的`mod_deflate`模块与PHP的`zlib.output_compression`冲突
2. REDCap皞鞟<EFBFBD>銝剖𢆡<EFBFBD><EFBFBD>鍳<EFBFBD>其<EFBFBD><EFBFBD>讠憬嚗ǑSystem.php`<EFBFBD><EFBFBD>general_settings.php`銝剔<EFBFBD>`ini_set`嚗?
3. 撖潸稲<EFBFBD>唳旿鋡怠<EFBFBD>甈∪<EFBFBD>蝻抬<EFBFBD>瘚讛<EFBFBD><EFBFBD>冽<EFBFBD>瘜閗圾<EFBFBD>?
2. REDCap源码中动态启用了压缩（`System.php`、`general_settings.php`中的`ini_set`）
3. 导致数据被多次压缩，浏览器无法解码
**閫<EFBFBD><EFBFBD><EFBFBD>寞<EFBFBD>嚗?*
1. <EFBFBD>?<3F>灼docker-entrypoint.sh`銝剖撩<E58996>嗥<EFBFBD><E597A5>杗pache<EFBFBD><EFBFBD>eflate璅∪<EFBFBD>嚗䫤a2dismod -f deflate`
2. <EFBFBD>?<3F>灼php.ini`銝剜遬撘誩<EFBFBD><EFBFBD>剖<EFBFBD>蝻抬<EFBFBD>
**解决方案：**
1. ✅ 在`docker-entrypoint.sh`中强制禁用Apache的deflate模块：`a2dismod -f deflate`
2. ✅ 在`php.ini`中显式关闭压缩：
```ini
zlib.output_compression = Off
output_buffering = Off
```
3. <EFBFBD>?<3F>灼docker-entrypoint.sh`銝剛䌊<EFBFBD>冽釣<EFBFBD>䟕EDCap皞鞟<EFBFBD>銝剔<EFBFBD>`ini_set('zlib.output_compression', ...)`
3. ✅ 在`docker-entrypoint.sh`中自动注释REDCap源码中的`ini_set('zlib.output_compression', ...)`
**憸<EFBFBD>俈<EFBFBD>芣鴌嚗?*
**预防措施：**
- 已在`redcap.conf`中注释掉`mod_deflate`配置
- 开发环境不需要Gzip压缩，可提高调试效率
@@ -47,54 +47,54 @@
### 问题2：Base URL配置错误
**<EFBFBD>啗情嚗?*
**现象：**
- CSS/JS文件路径包含多余的`/redcap/`前缀
- 例如：`http://localhost:8080/redcap/redcap_v15.8.0/Resources/...`
- 导致404错误
**<EFBFBD>寞𧋦<EFBFBD>笔<EFBFBD>嚗?*
**根本原因：**
- REDCap数据库配置表`redcap_config`中的`redcap_base_url`设置为`http://localhost:8080/redcap`
- 但Apache的`DocumentRoot`实际指向`/var/www/html/redcap_v15.8.0`
**閫<EFBFBD><EFBFBD><EFBFBD>寞<EFBFBD>嚗?*
**解决方案：**
```sql
UPDATE redcap_config
SET value = 'http://localhost:8080'
WHERE field_name = 'redcap_base_url';
```
**憸<EFBFBD>俈<EFBFBD>芣鴌嚗?*
- <20>典<EFBFBD>鋆<EFBFBD><E98B86>撖潭<E69296>SQL撖澆<E69296><E6BE86>嗥＆靽𨈚ase URL銝𥟠ocumentRoot銝<EFBFBD><EFBFBD>?
**预防措施：**
- 在安装向导或SQL导入时确保Base URL与DocumentRoot一致
---
### <EFBFBD>桅<EFBFBD>3嚗𡁶蒈敶訫仃韐?- <20>滚<EFBFBD><E6BB9A>唳旿<E594B3>䭾<EFBFBD><E4ADBE>㰘蝸
### 问题3：登录失败 - 响应数据无法加载
**<EFBFBD>啗情嚗?*
- 颲枏<E9A2B2>甇<EFBFBD>＆<EFBFBD><EFBC86>鍂<EFBFBD>瑕<EFBFBD>撖<EFBFBD><E69296><EFBFBD>𠬍<EFBFBD>憿菟𢒰銝滩歲頧?
**现象：**
- 输入正确的用户名密码后，页面不跳转
- Network面板显示POST请求返回200，但"无法加载响应数据"
**<EFBFBD>寞𧋦<EFBFBD>笔<EFBFBD>嚗?*
- **`database.php`<EFBFBD><EFBFBD>辣<EFBFBD>怠偏<EFBFBD>头?>`PHP蝏𤘪<EFBFBD><EFBFBD><EFBFBD>倌<EFBFBD>𣬚征銵?*
**根本原因：**
- **`database.php`文件末尾有`?>`PHP结束标签和空行**
- Windows系统的CRLF换行符被输出到HTTP响应
- 撖潸稲<E6BDB8>滚<EFBFBD>雿𤘪情<F0A498AA>橒<EFBFBD>瘚讛<E7989A><E8AE9B>冽<EFBFBD>瘜閗圾<E99697>?
- 导致响应体污染，浏览器无法解析
**霂衣<EFBFBD><EFBFBD><EFBFBD><EFBFBD>嚗?*
**详细分析：**
```bash
# database.php<EFBFBD>怠偏<EFBFBD><EFBFBD><EFBFBD><EFBFBD>剛<EFBFBD><EFBFBD>嗅<EFBFBD>摰?
# database.php末尾的十六进制内容
00000050: e585 a80d 0a20 2a2f 0d0a 0d0a 3f3e 0d0a ..... */....?>..
00000060: 0d0a 0d0a ....
# `*/` CRLF CRLF `?>` CRLF CRLF CRLF
```
**閫<EFBFBD><EFBFBD><EFBFBD>寞<EFBFBD>嚗?*
1. <20>?**<2A>𣳇膄`database.php`<EFBFBD>怠偏<EFBFBD><EFBFBD>?>`<60>峕<EFBFBD><E5B395>厩征銵?*
2. <20>?**<2A>𥕦遣`.gitattributes`撘箏<EFBFBD>PHP<EFBFBD><EFBFBD>辣雿輻鍂LF<EFBFBD>Ｚ<EFBFBD>蝚?*
3. <20>?**<2A>灼docker-entrypoint.sh`銝剜溶<E5899C>䭾<EFBFBD><E4ADBE>仿<EFBFBD>餉<EFBFBD>嚗<EFBFBD>郎<EFBFBD>𦠜<EFBFBD>蝷綽<E89DB7>**
**解决方案：**
1. ✅ **删除`database.php`末尾的`?>`和所有空行**
2. ✅ **创建`.gitattributes`强制PHP文件使用LF换行符**
3. ✅ **在`docker-entrypoint.sh`中添加检查逻辑（警告提示）**
**PHP最佳实践：**
- 📌 **配置文件和库文件末尾不应该写`?>`**
- <20><> 餈蹱糓PHP摰䀹䲮<E480B9>刻<EFBFBD>嚗𣬚鍂鈭𡡞俈甇Ｘ錰撠曄征銵峕情<E5B395>栞<EFBFBD><E6A09E>?
- 📌 这是PHP官方推荐，用于防止末尾空行污染输出
- 📌 REDCap官方源码都遵循此规范
---
@@ -103,7 +103,7 @@ WHERE field_name = 'redcap_base_url';
### 密码重置工具
<EFBFBD>𥕦遣鈭<EFBFBD>scripts/create-redcap-password.php`嚗𣬚鍂鈭𡡞<EFBFBD>蝵娜EDCap<EFBFBD>冽<EFBFBD>撖<EFBFBD><EFBFBD>嚗?
创建了`scripts/create-redcap-password.php`，用于重置REDCap用户密码：
```bash
# 使用方法
@@ -111,54 +111,54 @@ docker cp scripts/create-redcap-password.php redcap-apache:/tmp/
docker exec redcap-apache php /tmp/create-redcap-password.php
```
**瘜冽<EFBFBD>嚗?* 甇方<E79487><E696B9>砌<EFBFBD><E7A08C>其<EFBFBD>撘<EFBFBD><E69298>𤑳㴓憓<E3B493><E68693><EFBFBD>煺漣<E785BA>臬<EFBFBD>摨𠉛<E691A8><F0A0899B>具<EFBFBD>?
**注意：** 此脚本仅用于开发环境！生产环境应禁用。
---
## <EFBFBD>?<3F><>蝏<EFBFBD>＆霈?
## ✅ 最终确认
### REDCap系统是安全的
**<EFBFBD>滩<EFBFBD>蝏栞捏嚗?*
1. <EFBFBD>?**REDCap摰䀹䲮皞鞟<EFBFBD>嚗?5.8.0<EFBFBD><EFBFBD>𧋦嚗峕㺭<EFBFBD><EFBFBD>葵PHP<EFBFBD><EFBFBD>辣嚗厰<EFBFBD><EFBFBD>航<EFBFBD><EFBFBD><EFBFBD><EFBFBD>**
2. <EFBFBD>?**摰䀹䲮<E480B9><E4B2AE>辣<EFBFBD>怠偏<E680A0>賣瓷<E8B3A3>头?>`嚗䔶<EFBFBD>摮睃銁CRLF瘙⊥<EFBFBD><EFBFBD>桅<EFBFBD>**
3. <20>?**<2A>桅<EFBFBD>隞<EFBFBD><E99A9E><EFBFBD>其<EFBFBD><E585B6>睲賑<E79DB2>𥕦遣<F0A595A6><E981A3><EFBFBD>蝵格<E89DB5>隞跆database.php`**
4. <20>?**銝<><E98A9D>虫耨憭㵪<E686AD>銝滢<E98A9D><E6BBA2>匧<EFBFBD>隞𣇉掩隡潮䔮憸?*
**重要结论：**
1. ✅ **REDCap官方源码（15.8.0版本，数千个PHP文件）都是规范的**
2. ✅ **官方文件末尾都没有`?>`，不存在CRLF污染问题**
3. ✅ **问题仅存在于我们创建的配置文件`database.php`**
4. ✅ **一旦修复，不会有其他类似问题**
**撉諹<EFBFBD>霂<EFBFBD>旿嚗?*
**验证证据：**
```bash
# REDCap官方index.php末尾（规范）
tail -c 20 /var/www/html/redcap/redcap_v15.8.0/index.php | xxd
00000000: 656e 6572 616c 2f66 6f6f 7465 722e 7068 eneral/footer.ph
00000010: 7027 3b0a p';.
# <EFBFBD>怠偏<EFBFBD>芣<EFBFBD> '; <20>峕揢銵𣬚泵嚗峕瓷<E5B395>?>
# 末尾只有 '; 和换行符，没有?>
# REDCap官方Authentication.php末尾（规范）
tail -c 30 /var/www/html/redcap/redcap_v15.8.0/Classes/Authentication.php | xxd
00000000: 6c2c 205b 2475 7365 7269 645d 2929 203e l, [$userid])) >
00000010: 2030 3b0a 0909 7d0a 097d 0a0a 7d0a 0;...}..}..}.
# <EFBFBD>怠偏<EFBFBD>芣<EFBFBD> } <20>峕揢銵𣬚泵嚗峕瓷<E5B395>?>
# 末尾只有 } 和换行符，没有?>
```
---
## 📚 经验总结
### 1. Docker頝典像<EFBFBD>唳釣<EFBFBD>譍<EFBFBD>憿?
### 1. Docker跨平台注意事项
**Windows + Docker + Linux容器组合会暴露文件格式问题：**
- Windows默认CRLF (`\r\n`)
- Linux默认LF (`\n`)
- Git的`autocrlf`设置可能自动转换
- 雿輻鍂`.gitattributes`<EFBFBD>曉<EFBFBD><EFBFBD>批<EFBFBD><EFBFBD>Ｚ<EFBFBD>蝚?
- 使用`.gitattributes`显式控制换行符
### 2. PHP<EFBFBD>滨蔭<EFBFBD><EFBFBD>辣<EFBFBD><EFBFBD>雿喳<EFBFBD>頝?
### 2. PHP配置文件最佳实践
```php
<?php
// 配置代码...
// <EFBFBD>?<3F>躰秤嚗𡁏<E59A97>蝏𤘪<E89D8F><F0A498AA><EFBFBD>倌<EFBFBD>𣬚征銵?
// ❌ 错误：有结束标签和空行
?>
@@ -168,12 +168,12 @@ tail -c 30 /var/www/html/redcap/redcap_v15.8.0/Classes/Authentication.php | xxd
<?php
// 配置代码...
// <EFBFBD>?甇<>＆嚗𡁏瓷<F0A1818F>厩<EFBFBD><E58EA9><EFBFBD><EFBFBD>蝑?
// ✅ 正确：没有结束标签
```
### 3. REDCap<EFBFBD>函蔡璉<EFBFBD><EFBFBD>交<EFBFBD><EFBFBD>?
### 3. REDCap部署检查清单
- [ ] Apache DocumentRoot銝𦻓ase URL銝<EFBFBD><EFBFBD>?
- [ ] Apache DocumentRoot与Base URL一致
- [ ] 禁用压缩模块（开发环境）
- [ ] `database.php`末尾无`?>`
- [ ] 文件换行符统一为LF
@@ -182,22 +182,22 @@ tail -c 30 /var/www/html/redcap/redcap_v15.8.0/Classes/Authentication.php | xxd
---
## <EFBFBD><EFBFBD> <20>𡒊賒<F0A1928A>函蔡<E587BD>啁<EFBFBD>鈭抒㴓憓?
## 🚀 后续部署到生产环境
**<EFBFBD>砍𧑐Docker撘<EFBFBD><EFBFBD>𤑳㴓憓<EFBFBD>歇撉諹<EFBFBD><EFBFBD>朞<EFBFBD>嚗<EFBFBD>虾隞亙<EFBFBD><EFBFBD>刻<EFBFBD>蝘餃<EFBFBD><EFBFBD>輸<EFBFBD>鈭䫿CS嚗?*
**本地Docker开发环境已验证通过，可以安全迁移到阿里云ECS：**
1. <20>?雿輻鍂<E8BCBB>詨<EFBFBD><E8A9A8><EFBFBD>Dockerfile.redcap`<60><>遣<EFBFBD>𨅯<EFBFBD>
2. <20>?靽格㺿`database.php`餈墧𦻖<EFBFBD>訌DS
3. <20>?<3F>煺漣<E785BA>臬<EFBFBD><E887AC>臭誑<E887AD>舐鍂Gzip<69>讠憬嚗<E686AC>蝙<EFBFBD>沐ginx<6E>滚<EFBFBD>隞<EFBFBD><E99A9E>嚗?
4. <20>?<3F><><EFBFBD>厰<EFBFBD>蝵格<E89DB5>隞嗅歇蝏讛<E89D8F>撉諹<E69289>嚗䔶<E59A97>隡𡁏<E99AA1>CRLF<4C>桅<EFBFBD>
1. ✅ 使用相同的`Dockerfile.redcap`构建镜像
2. ✅ 修改`database.php`连接到RDS
3. ✅ 生产环境可以启用Gzip压缩（使用Nginx反向代理）
4. ✅ 所有配置文件已经过验证，不会有CRLF问题
**<EFBFBD>芣䔉銝漤<EFBFBD>閬<EFBFBD><EFBFBD>𣂷葵<EFBFBD>埝䰻REDCap<EFBFBD><EFBFBD>辣嚗<EFBFBD><EFBFBD>銝箏<EFBFBD><EFBFBD>嫣誨<EFBFBD><EFBFBD>糓閫<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>** <20>?
**未来不需要逐个排查REDCap文件，因为官方代码是规范的！** ✨
---
## 📞 联系方式
憒<EFBFBD><EFBFBD><EFBFBD>桅<EFBFBD>嚗諹窈<EFBFBD>亦<EFBFBD>嚗?
如有问题，请查看：
- REDCap官方文档：https://projectredcap.org/
- <20>函蔡<E587BD>寞<EFBFBD><E5AF9E><EFBFBD>﹝嚗䫤docs/03-REDCap<EFBFBD>砍𧑐Docker撘<EFBFBD><EFBFBD>𤑳㴓憓<EFBFBD><EFBFBD>蝵脫䲮獢?md`
- 部署方案文档：`docs/03-REDCap本地Docker开发环境部署方案.md`

442
docs/03-业务模块/Redcap/03-API对接与开发/33-REDCap二次开发深度指南.md
View File

@@ -1,52 +1,63 @@
# **REDCap鈭峕活撘<EFBFBD><EFBFBD>烐楛摨衣<EFBFBD>蝛嗆𥁒<EFBFBD>𠺪<EFBFBD><EFBFBD>嗆<EFBFBD>雿梶頂<EFBFBD><EFBFBD>宏<EFBFBD>函垢鈭支<EFBFBD>銝擧<EFBFBD>雿喳<EFBFBD>頝萄<EFBFBD><EFBFBD>航圾<EFBFBD>?*
# **REDCap二次开发深度研究报告：架构体系、移动端交互与最佳实践全景解析**
## **1\. <EFBFBD>扯<EFBFBD><EFBFBD>䁅<EFBFBD>銝擧沲<EFBFBD><EFBFBD><EFBFBD><EFBFBD>?*
## **1\. 执行摘要与架构背景**
Research Electronic Data Capture (REDCap) 撌脩<EFBFBD>隞𦒘<EFBFBD>銝芸<EFBFBD>銝<EFBFBD><EFBFBD><EFBFBD>㺭<EFBFBD>格𤣰<EFBFBD><EFBFBD>極<EFBFBD>瑟<EFBFBD><EFBFBD>䀝蛹銝<EFBFBD>銝芾<EFBFBD>憭<EFBFBD>𣈲<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>葩摨𡃏<EFBFBD>撉䎚<EFBFBD><EFBFBD><EFBFBD><EFBFBD>亙極雿𨀣<EFBFBD><EFBFBD>𣬚熊<EFBFBD>𤑳<EFBFBD>蝛嗥<EFBFBD>撘箏之<EFBFBD><EFBFBD><EFBFBD><EFBFBD>頂蝏麄<EFBFBD><EFBFBD>蒾<EFBFBD>嗉<EFBFBD>敺瑕嵗憭批郎嚗Āanderbilt University嚗匧<E59A97><E58CA7>𤑳<EFBFBD><F0A491B3>詨<EFBFBD>摨𠉛鍂蝔见<E89D94><E8A781>𣂷<EFBFBD>鈭<EFBFBD><E988AD>憟堒<E6869F><E5A092><EFBFBD><EFBFBD>靚<EFBFBD>䰻蝞∠<E89D9E><E288A0>峕㺭<E5B395>桀<EFBFBD><E6A180>亙極<E4BA99>瘀<EFBFBD>雿<EFBFBD>笆鈭𦒘<E988AD>銝𡁶漣<F0A181B6>𠉛弦<F0A0899B><E5BCA6><EFBFBD><EFBFBD><EFBFBD>葩摨𦠜㺭<F0A6A09C>桃恣<E6A183><E681A3><EFBFBD>諹<EFBFBD>嚗朙EDCap<61><70>迤<EFBFBD><E8BFA4><EFBFBD><EFBFBD>𥕦銁鈭𤾸<E988AD><F0A4BEB8>靝<EFBFBD>甈∪<E79488><E288AA>爗<EFBFBD>肽<EFBFBD><E882BD>䜘<EFBFBD><E49C98><EFBFBD>銝<EFBFBD><E98A9D>航祗瘨萇<E798A8>鈭<EFBFBD><E988AD>朞<EFBFBD>憭㚚<E686AD>璅∪<E79285>嚗𠄌xternal Module, EM嚗㗇<E59A97><E39787>嗚<EFBFBD><E5979A><EFBFBD><EFBFBD>函<EFBFBD>摨讐<E691A8>蝔𧢲𦻖<F0A7A2B2><F0A6BB96><EFBFBD>API嚗剹<E59A97><E589B9>㺭<EFBFBD>桀<EFBFBD><E6A180>亥圻<E4BAA5>穃膥嚗㇄ET嚗劐誑<E58A90>𦠜<EFBFBD><F0A6A09C>䟕EDCap蝘餃𢆡摨𠉛鍂蝔见<E89D94><E8A781>愢yCap<61><70>宏<EFBFBD>券<EFBFBD><E588B8>鞟<EFBFBD><E99E9F>亙笆REDCap餈𥡝<E9A488><F0A5A19D><EFBFBD><EFBFBD>摨誩<E691A8><E8AAA9>拙<EFBFBD>1<EFBFBD>?
<EFBFBD>祆𥁒<EFBFBD>𦠜秄<EFBFBD>冽<EFBFBD>靘𥕦<EFBFBD>鈭竃EDCap鈭峕活撘<EFBFBD><EFBFBD>𤑳<EFBFBD>霂血偷<EFBFBD><EFBFBD><EFBFBD>臬<EFBFBD><EFBFBD>僐<EFBFBD><EFBFBD><EFBFBD>銝滢<EFBFBD><EFBFBD>Ｚ悄鈭<EFBFBD>沲<EFBFBD><EFBFBD><EFBFBD><EFBFBD>單辺隞嗚<EFBFBD><EFBFBD><EFBFBD><EFBFBD>抒<EFBFBD><EFBFBD>雴辣嚗㇊lugin嚗匧<EFBFBD><EFBFBD>唬誨憭㚚<EFBFBD>璅∪<EFBFBD>獢<EFBFBD>沲<EFBFBD><EFBFBD><EFBFBD>皜～<EFBFBD><EFBFBD><EFBFBD><EFBFBD>函<EFBFBD><EFBFBD><EFBFBD><EFBFBD>頝蛛<EFBFBD>餈䀹楛<EFBFBD>亙<EFBFBD><EFBFBD>𣂷<EFBFBD>蝘餃𢆡蝡臬<EFBFBD>甇亦<EFBFBD>憭齿<EFBFBD><EFBFBD>箏<EFBFBD><EFBFBD><EFBFBD>迨憭吔<EFBFBD><EFBFBD>亙<EFBFBD>霂衣<EFBFBD><EFBFBD>堒枂鈭<EFBFBD>鸌摰𡁶<EFBFBD>皞𣂷誨<EFBFBD><EFBFBD>芋撘𧶏<EFBFBD><EFBFBD><EFBFBD><EFBFBD>鈭<EFBFBD>虜閫<EFBFBD><EFBFBD><EFBFBD>琿𩐠嚗<EFBFBD>朖撘<EFBFBD><EFBFBD>睲葉<EFBFBD><EFBFBD><EFBFBD>𨅯<EFBFBD><EFBFBD>嘅<EFBFBD>嚗<EFBFBD>僎<EFBFBD>𣂷<EFBFBD>鈭<EFBFBD>銁摰𡁜<EFBFBD><EFBFBD>蠘<EFBFBD><EFBFBD>嗥輕<EFBFBD>斤頂蝏笔<EFBFBD><EFBFBD>湔<EFBFBD>抒<EFBFBD><EFBFBD><EFBFBD>雿喳<EFBFBD>頝萸<EFBFBD>?
### **1.1 <20>𠉛<EFBFBD>璅∪<E79285>銝擧<E98A9D><E693A7><EFBFBD>挪<EFBFBD>格<EFBFBD><E6A0BC>鞟<EFBFBD><E99E9F>寞<EFBFBD><E5AF9E>?*
Research Electronic Data Capture (REDCap) 已经从一个单一的数据收集工具演变为一个能够支持复杂临床试验、运营工作流和纵向研究的强大生态系统。虽然范德堡大学（Vanderbilt University）开发的核心应用程序提供了一套完善的调查管理和数据录入工具，但对于企业级研究和复杂临床数据管理而言，REDCap真正的潜力在于其“二次开发”能力。这一术语涵盖了通过外部模块（External Module, EM）框架、应用程序编程接口（API）、数据录入触发器（DET）以及涉及REDCap移动应用程序和MyCap的移动集成策略对REDCap进行的程序化扩展1。
本报告旨在提供关于REDCap二次开发的详尽技术分析。它不仅探讨了架构先决条件、从旧版插件（Plugin）向现代外部模块框架的过渡、安全编码实践，还深入剖析了移动端同步的复杂机制。此外，报告详细列出了特定的源代码模式，分析了常见的陷阱（即开发中的“坑”），并提供了在定制功能时维护系统完整性的最佳实践。
### **1.1 联盟模式与源码访问权限的特殊性**
与传统的开源软件不同，REDCap在一种独特的管理模式下运行。它对非营利组织免费提供，但并非公共领域的开源软件。为了获得二次开发所需的源代码，组织必须通过与范德堡大学签署最终用户许可协议（EULA）加入REDCap联盟3。
这种区别对开发者至关重要。源代码无法在GitHub等公共存储库中以可运行的格式获取；严格来说，核心代码库是联盟的专有财产。然而，扩展机制——特别是外部模块框架——是公开文档化的，且社区通过REDCap Repo分享了数百个模块1。为了进行深度的二次开发，开发者通常需要其所在机构的REDCap管理员授予本地服务器访问权限，以便检查核心PHP文件和进行调试6。
銝𦒘<EFBFBD>蝏毺<EFBFBD>撘<EFBFBD>皞鞱蔓隞嗡<EFBFBD><EFBFBD>䕘<EFBFBD>REDCap<EFBFBD>其<EFBFBD>蝘滨𡠺<EFBFBD>寧<EFBFBD>蝞∠<EFBFBD>璅∪<EFBFBD>銝贝<EFBFBD>銵䎚<EFBFBD><EFBFBD><EFBFBD>撖寥<EFBFBD><EFBFBD>亙⏚蝏<EFBFBD><EFBFBD><EFBFBD>滩晶<EFBFBD>𣂷<EFBFBD>嚗䔶<EFBFBD>撟園<EFBFBD><EFBFBD>砍<EFBFBD>憸<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>皞鞱蔓隞嗚<EFBFBD><EFBFBD>蛹鈭<EFBFBD>繮敺𦯀<EFBFBD>甈∪<EFBFBD><EFBFBD>烐<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>隞<EFBFBD><EFBFBD>嚗𣬚<EFBFBD>蝏<EFBFBD><EFBFBD>憿駁<EFBFBD>朞<EFBFBD>銝舘<EFBFBD>敺瑕嵗憭批郎蝑曄蔡<EFBFBD><EFBFBD>蝏<EFBFBD>鍂<EFBFBD>瑁捂<EFBFBD>臬<EFBFBD>霈殷<EFBFBD>EULA嚗匧<EFBFBD><EFBFBD>充EDCap<EFBFBD>𠉛<EFBFBD>3<EFBFBD>?
餈嗵<EFBFBD><EFBFBD>箏<EFBFBD>撖孵<EFBFBD><EFBFBD>𤏸<EFBFBD><EFBFBD>秐<EFBFBD>喲<EFBFBD>閬<EFBFBD><EFBFBD><EFBFBD><EFBFBD>隞<EFBFBD><EFBFBD><EFBFBD>䭾<EFBFBD><EFBFBD>沁itHub蝑匧<EFBFBD><EFBFBD>勗<EFBFBD><EFBFBD>典<EFBFBD>銝凋誑<EFBFBD>航<EFBFBD>銵𣬚<EFBFBD><EFBFBD>澆<EFBFBD><EFBFBD>瑕<EFBFBD>嚗𥕢艇<EFBFBD>潭䔉霂湛<EFBFBD><EFBFBD>詨<EFBFBD>隞<EFBFBD><EFBFBD>摨𤘪糓<EFBFBD>𠉛<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>㕑揣鈭扼<EFBFBD><EFBFBD><EFBFBD><EFBFBD>䕘<EFBFBD><EFBFBD>拙<EFBFBD><EFBFBD>箏<EFBFBD><EFBFBD>婙<EFBFBD>𠉛鸌<EFBFBD>急糓憭㚚<EFBFBD>璅∪<EFBFBD>獢<EFBFBD>沲<EFBFBD>婙<EFBFBD>娍糓<EFBFBD>砍<EFBFBD><EFBFBD><EFBFBD>﹝<EFBFBD>𣇉<EFBFBD>嚗䔶<EFBFBD>蝷曉躹<EFBFBD>朞<EFBFBD>REDCap Repo<70><6F>澈鈭<E6BE88>㺭<EFBFBD>曆葵璅∪<E79285>1<EFBFBD><31>蛹鈭<E89BB9><E988AD>銵峕楛摨衣<E691A8>鈭峕活撘<E6B4BB><E69298>𡢅<EFBFBD>撘<EFBFBD><E69298>𤏸<EFBFBD><F0A48FB8><EFBFBD>𡁜虜<F0A1819C><E8999C>閬<EFBFBD><E996AC><EFBFBD><EFBFBD><EFBFBD>冽㦤<E586BD><E3A6A4><EFBFBD>REDCap蝞∠<E89D9E><E288A0>䀹<EFBFBD>鈭<EFBFBD>𧋦<EFBFBD>唳<EFBFBD><E594B3>∪膥霈輸䔮<E8BCB8><E494AE><EFBFBD>嚗䔶誑靘踵<E99D98><E8B8B5>交瓲敹<E793B2>HP<48><50>辣<EFBFBD>諹<EFBFBD>銵諹<E98AB5>霂?<3F>?
### **1.2 技术架构：LAMP栈与EAV模型**
二次开发要求对REDCap的底层基础设施有深刻的理解。REDCap构建在LAMP栈之上：
* **Linux/Windows嚗?* <20>条恣摨𠉛鍂蝔见<E89D94><E8A781><EFBFBD><EFBFBD>雿𦦵頂蝏麄<E89D8F>?
* **Apache/IIS/Nginx嚗?* 憭<><E686AD>HTTP霂瑟<E99C82><E7919F><EFBFBD>eb<65>滚𦛚<E6BB9A>具<EFBFBD>?
* **MySQL/MariaDB嚗?* <20>喟頂<E5969F>𧢲㺭<F0A7A2B2>桀<EFBFBD>蝞∠<E89D9E>蝟餌<E89D9F><E9A48C>?
* **PHP嚗?* <20>其<EFBFBD><E585B6>詨<EFBFBD><E8A9A8>餉<EFBFBD><E9A489>峕<EFBFBD>撅閧<E69285><E996A7>滚𦛚<E6BB9A>函垢<E587BD>𡁏𧋦霂剛<E99C82><E5899B>?
REDCap鋡急<EFBFBD>餈唬蛹<EFBFBD>𡏭蝠<EFBFBD>讐漣<EFBFBD>嘅<EFBFBD><EFBFBD>𡁜虜<EFBFBD><EFBFBD>閬<EFBFBD>eb<EFBFBD>滚𦛚<EFBFBD>典<EFBFBD><EFBFBD>祉<EFBFBD><EFBFBD><EFBFBD>㺭<EFBFBD>桀<EFBFBD><EFBFBD>滚𦛚<EFBFBD>具<EFBFBD><EFBFBD>笆鈭擧<EFBFBD><EFBFBD><EFBFBD>蝙<EFBFBD>剁<EFBFBD>Web<EFBFBD>滚𦛚<EFBFBD>典<EFBFBD><EFBFBD>唳旿摨枏<EFBFBD><EFBFBD><EFBFBD><EFBFBD>10GB<EFBFBD><EFBFBD><EFBFBD><EFBFBD>函征<EFBFBD>湧<EFBFBD>𡁜虜頞喃誑<EFBFBD>舀<EFBFBD>蝚砌<EFBFBD>撟渡<EFBFBD>擃睃撩摨虫蝙<EFBFBD>?<3F><><EFBFBD><EFBFBD>䕘<EFBFBD>鈭峕活撘<E6B4BB><E69298>穃<EFBFBD>敺<EFBFBD>隡𡁜蒂<F0A1819C>交凒擃条<E69383>韏<EFBFBD><E99F8F><EFBFBD><EFBFBD>瘙<EFBFBD><E79899><EFBFBD><EFBFBD>銵<EFBFBD><E98AB5><EFBFBD><EFBFBD>䰻霂Ｘ<E99C82><EFBCB8>朞<EFBFBD>API憭<49><E686AD>憭扳㺭<E689B3>桃<EFBFBD><E6A183>芸<EFBFBD>銋㗇芋<E39787>堒<EFBFBD><E5A092>𨀣𧊋蝏讛<E89D8F>隡睃<E99AA1>嚗<EFBFBD>虾<EFBFBD>賭<EFBFBD>蝏蹱㺭<E8B9B1>桀<EFBFBD>撣行䔉撌典之<E585B8>见<EFBFBD><E8A781>?
<EFBFBD>唳旿摨𤘪芋撘譍蜓閬<EFBFBD><EFBFBD><EFBFBD>典<EFBFBD>雿?撅墧<E69285>?<3F>潘<EFBFBD>Entity-Attribute-Value, EAV嚗㗇芋<E39787>页<EFBFBD><E9A1B5>孵<EFBFBD><E5ADB5>盍edcap\_data銵剁<E98AB5>摰<EFBFBD>誑<EFBFBD>剔<EFBFBD><E58994><EFBFBD>熊<EFBFBD>烐聢撘𧶏<E69298>record\_id, project\_id, field\_name, value嚗匧<E59A97><E58CA7>函<EFBFBD>憭折<E686AD><E68A98><EFBFBD>★<EFBFBD>格㺭<E6A0BC>柴<EFBFBD><E69FB4><EFBFBD>銝<EFBFBD><E98A9D>嗆<EFBFBD><E59786>喟<EFBFBD><E5969F><EFBFBD>捂<EFBFBD>其<EFBFBD><E585B6>湔㺿<E6B994>唳旿摨𤘪芋撘讐<E69298><E8AE90><EFBFBD><EFBFBD>銝𧢲<E98A9D><F0A7A2B2><EFBFBD>𧑐<EFBFBD>𥕦遣<F0A595A6><E981A3>㺭<EFBFBD>桅店<E6A185>函<EFBFBD>銵典<E98AB5>嚗䔶<E59A97>餈蹱遬<E8B9B1>堒<EFBFBD><E5A092>牐<EFBFBD>鈭峕活撘<E6B4BB><E69298>睲葉<E79DB2>湔𦻖SQL<51>亥砭<E4BAA5><E7A0AD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>?<3F><><EFBFBD><EFBFBD>𤏸<EFBFBD><F0A48FB8><EFBFBD>憿餃<E686BF>敹<EFBFBD>𧑐瘚讛<E7989A>甇斗芋撘譍誑<E8AD8D>踹<EFBFBD><E8B8B9>扯<EFBFBD>銝钅<E98A9D><E99285>?
* **Linux/Windows：** 托管应用程序的操作系统。
* **Apache/IIS/Nginx：** 处理HTTP请求的Web服务器。
* **MySQL/MariaDB：** 关系型数据库管理系统。
* **PHP：** 用于核心逻辑和扩展的服务器端脚本语言。
REDCap被描述为“轻量级”，通常需要Web服务器和独立的数据库服务器。对于标准使用，Web服务器和数据库各分配10GB的存储空间通常足以支持第一年的高强度使用7。然而，二次开发往往会带来更高的资源需求。执行复杂查询或通过API处理大数据的自定义模块如果未经过优化，可能会给数据库带来巨大压力。
数据库模式主要采用实体-属性-值（Entity-Attribute-Value, EAV）模型，特别是redcap\_data表，它以狭窄的纵向格式（record\_id, project\_id, field\_name, value）存储绝大部分项目数据。这一架构决策允许在不更改数据库模式的情况下流畅地创建元数据驱动的表单，但这显著增加了二次开发中直接SQL查询的复杂性2。开发者必须小心地浏览此模式以避免性能下降。
## ---
**2\. 外部模块框架（External Module Framework）：定制化的现代标准**
<EFBFBD><EFBFBD>蟮銝𠺪<EFBFBD>REDCap<EFBFBD><EFBFBD><EFBFBD><EFBFBD>嗆糓<EFBFBD>朞<EFBFBD><EFBFBD>𣿯ooks嚗<EFBFBD>偬摮琜<EFBFBD><EFBFBD>嘥<EFBFBD><EFBFBD>憕lugins嚗<EFBFBD><EFBFBD>隞塚<EFBFBD><EFBFBD>嘥<EFBFBD><EFBFBD>啁<EFBFBD><EFBFBD>婙<EFBFBD>𥪜朖<EFBFBD>湔𦻖瘜典<EFBFBD>Web<EFBFBD>滚𦛚<EFBFBD>冽<EFBFBD>隞嗉楝敺<EFBFBD><EFBFBD><EFBFBD>𡁏𧋦<EFBFBD><EFBFBD>蒾<EFBFBD>嗉<EFBFBD>蝘齿䲮瘜閙<EFBFBD><EFBFBD><EFBFBD><EFBFBD>雿<EFBFBD><EFBFBD><EFBFBD>𧼮虜<EFBFBD><EFBFBD>摹嚗𢡱EDCap<EFBFBD>詨<EFBFBD><EFBFBD><EFBFBD><EFBFBD>蝥抒<EFBFBD>撣詨紡<EFBFBD>游<EFBFBD><EFBFBD>嗅<EFBFBD><EFBFBD>賢仃<EFBFBD><EFBFBD><EFBFBD>銝磰楊憭帋葵憿寧𤌍蝞∠<EFBFBD><EFBFBD><EFBFBD>𧋦<EFBFBD>刻<EFBFBD><EFBFBD>蹂<EFBFBD><EFBFBD>舐<EFBFBD><EFBFBD>鞟<EFBFBD>9<EFBFBD>?
**憭㚚<E686AD>璅∪<E79285>嚗𠄌xternal Module, EM嚗㗇<E59A97><E39787>?*<2A><><EFBFBD><EFBFBD>亙蝠摨閙㺿<E99699>䀝<EFBFBD>鈭峕活撘<E6B4BB><E69298>𤑳<EFBFBD><F0A491B3>澆<EFBFBD><E6BE86><EFBFBD><EFBFBD>撠<EFBFBD>䌊摰帋<E691B0>隞<EFBFBD><E99A9E>撠<EFBFBD><E692A0><EFBFBD>典蒂<E585B8><E89282>𧋦<EFBFBD><F0A78BA6><EFBFBD>銝哨<E98A9D><E593A8>臭誑<E887AD>典<EFBFBD><E585B8>舐鍂<E88890>𡝗<EFBFBD>憿寧𤌍<E5AFA7>舐鍂嚗<E98D82>僎<EFBFBD>朞<EFBFBD><E69C9E>曉耦<E69B89>冽<EFBFBD><E586BD>屸𢒰嚗𠃑UI嚗㕑<E59A97>銵𣬚恣<F0A3AC9A><E681A3><EFBFBD>銝磰<E98A9D><E7A3B0>刻<EFBFBD><E588BB>笔<EFBFBD><E7AC94>曹澈1<E6BE88>?
历史上，REDCap的定制是通过“Hooks（钩子）”和“Plugins（插件）”实现的——即直接注入Web服务器文件路径的脚本。虽然这种方法有效，但它非常脆弱；REDCap核心的升级经常导致定制功能失效，且跨多个项目管理版本在行政上是繁琐的9。
**外部模块（External Module, EM）框架**的引入彻底改变了二次开发的格局。它将自定义代码封装在带版本的包中，可以全局启用或按项目启用，并通过图形用户界面（GUI）进行管理，且能在联盟内共享1。
### **2.1 外部模块的解剖学结构**
銝<EFBFBD>銝芸<EFBFBD><EFBFBD>冽芋<EFBFBD>埈糓雿滢<EFBFBD>\<redcap-root\>/modules/<EFBFBD>桀<EFBFBD>銝讠<EFBFBD><EFBFBD><EFBFBD>辣<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>賢<EFBFBD>蝥血<EFBFBD><EFBFBD>𧼮虜銝交聢嚗䨵<prefix\>\_v\<version\_number\><EFBFBD><EFBFBD><EFBFBD>憒<EFBFBD><EFBFBD>銝<EFBFBD>銝芰眏<EFBFBD>滨<EFBFBD>銝算<EFBFBD>𦣇ompany<EFBFBD>萘<EFBFBD>撘<EFBFBD><EFBFBD>𤏸<EFBFBD><EFBFBD><EFBFBD><EFBFBD>𤑳<EFBFBD><EFBFBD>滢蛹<EFBFBD>𣿯ello World<6C>萘<EFBFBD>璅∪<E79285><E288AA>航<EFBFBD>雿滢<E99BBF>modules/company\_hello\_world\_v1.0.010<EFBFBD>?
一个外部模块是位于\<redcap-root\>/modules/目录下的文件集合。其命名约定非常严格：\<prefix\>\_v\<version\_number\>。例如，一个由前缀为“company”的开发者开发的名为“Hello World”的模块可能位于modules/company\_hello\_world\_v1.0.010。
外部模块的核心组件如下表所示：
| 蝏<EFBFBD>辣<EFBFBD>滨妍 | <20><>辣<EFBFBD>?| <20>蠘<EFBFBD><E8A098>讛膩 |
| 组件名称 | 文件名 | 功能描述 |
| :---- | :---- | :---- |
| **<EFBFBD>滨蔭皜<EFBFBD><EFBFBD>** | config.json | 摰帋<EFBFBD><EFBFBD><EFBFBD>㺭<EFBFBD>柴<EFBFBD><EFBFBD><EFBFBD><EFBFBD>僐<EFBFBD><EFBFBD>曎<EFBFBD>乓<EFBFBD><EFBFBD>頂蝏?憿寧𤌍霈曄蔭隞亙<E99A9E>Cron雿靝<E99BBF><E99D9D><EFBFBD><EFBFBD><EFBFBD>舀芋<E88880>㛖<EFBFBD><E39B96>亙藁<E4BA99>嫘<EFBFBD>?|
| **<EFBFBD>餉<EFBFBD>蝐?* | Module.php | 蝏扳㗁<EFBFBD>服bstractExternalModule<EFBFBD><EFBFBD>HP蝐颯<EFBFBD><EFBFBD><EFBFBD><EFBFBD>思<EFBFBD><EFBFBD>⊿<EFBFBD>餉<EFBFBD><EFBFBD>屸偬摮𣂼<EFBFBD><EFBFBD>啜<EFBFBD>?|
| **<EFBFBD><EFBFBD>﹝** | README.md | 雿輻鍂霂湔<EFBFBD>嚗<EFBFBD>笆鈭擧<EFBFBD>鈭文<EFBFBD>Repo<EFBFBD>喳<EFBFBD><EFBFBD>滩<EFBFBD>嚗剹<EFBFBD>?|
| **霈詨虾霂?* | LICENSE | 霈詨虾<EFBFBD>⊥狡嚗<EFBFBD><EFBFBD>𡁜虜銝撤IT<EFBFBD>𣇉掩隡潭辺甈曆誑靘蹂<EFBFBD><EFBFBD>𠉛<EFBFBD><EFBFBD>曹澈嚗剹<EFBFBD>?|
| **颲<EFBFBD>𨭌<EFBFBD><EFBFBD>辣** | /pages, /js | <EFBFBD>其<EFBFBD>摮䀹𦆮<EFBFBD>芸<EFBFBD>銋厰△<EFBFBD>Ｕ<EFBFBD><EFBFBD>avaScript<EFBFBD>𥟟SS韏<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>桀<EFBFBD><EFBFBD>?|
| **配置清单** | config.json | 定义元数据、权限、链接、系统/项目设置以及Cron作业。它是模块的入口点。 |
| **逻辑类** | Module.php | 继承自AbstractExternalModule的PHP类。包含业务逻辑和钩子实现。 |
| **文档** | README.md | 使用说明（对于提交到Repo至关重要）。 |
| **许可证** | LICENSE | 许可条款（通常为MIT或类似条款以便于联盟共享）。 |
| **辅助文件** | /pages, /js | 用于存放自定义页面、JavaScript或CSS资源的子目录。 |
#### **2.1.1 <EFBFBD>滨蔭<EFBFBD><EFBFBD>辣 (config.json) <EFBFBD><EFBFBD>楛摨西圾<EFBFBD>?*
#### **2.1.1 配置文件 (config.json) 的深度解析**
config.json文件不仅是配置，它是模块的声明书。它告诉REDCap该模块能做什么以及它需要什么权限。如果JSON文件配置错误，模块将无法加载。
config.json<6F><6E>辣銝滢<E98A9D><E6BBA2>舫<EFBFBD>蝵殷<E89DB5>摰<EFBFBD>糓璅∪<E79285><E288AA><EFBFBD>ㄟ<EFBFBD>𦒘髡<F0A69298><E9ABA1><EFBFBD><EFBFBD>𡃏<EFBFBD>REDCap霂交芋<E4BAA4>𡑒<EFBFBD><F0A19192>帋<EFBFBD>銋<EFBFBD>誑<EFBFBD>𠰴<EFBFBD><F0A0B0B4><EFBFBD>閬<EFBFBD><E996AC>銋<EFBFBD><E98A8B><EFBFBD>僐<EFBFBD><E58390><EFBFBD><EFBFBD>䯀SON<4F><4E>辣<EFBFBD>滨蔭<E6BBA8>躰秤嚗峕芋<E5B395>堒<EFBFBD><E5A092>䭾<EFBFBD><E4ADBE>㰘蝸<E3B098>?
**源代码示范：config.json结构**
JSON
{
"name": "Advanced Data Processor",
"description": "<EFBFBD>其<EFBFBD>摮䀹𧒄憭<EFBFBD><EFBFBD><EFBFBD>唳旿撟嗡<EFBFBD>憭㚚<EFBFBD>API<EFBFBD><EFBFBD><EFBFBD><EFBFBD>?,
"description": "在保存时处理数据并与外部API集成。",
"permissions": \[
"redcap\_save\_record",
"redcap\_every\_page\_top"
@@ -54,14 +65,14 @@ JSON
"links": {
"project": \[
{
"name": "<EFBFBD>唳旿憭<EFBFBD><EFBFBD>隞芾”<EFBFBD>?,
"name": "数据处理仪表盘",
"icon": "fas fa-chart-line",
"url": "pages/dashboard.php"
}
\],
"control-center": \[
{
"name": "憭<EFBFBD><EFBFBD><EFBFBD>冽𠯫敹?,
"name": "处理器日志",
"icon": "fas fa-server",
"url": "pages/admin\_logs.php"
}
@@ -71,10 +82,12 @@ JSON
"authors":
}
*獢<><E78DA2><EFBFBD><EFBFBD><EFBFBD>嚗? permissions<6E>啁<EFBFBD><E59581>曉<EFBFBD>霂瑟<E99C82>撖寧鸌摰𡁻偬摮鞟<E691AE>霈輸䔮<E8BCB8><E494AE><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>𨀣迨憭<E8BFA8>𧊋<EFBFBD>堒枂<E5A092>𣂷葵<F0A382B7>拙<EFBFBD>嚗<EFBFBD>朖雿踹銁PHP蝐颱葉摰帋<E691B0>鈭<EFBFBD>砲<EFBFBD>賣㺭嚗<E3BAAD><E59A97>銋<EFBFBD>偶餈靝<E9A488>隡𡁏<E99AA1>銵䎚<E98AB5><E48E9A>roject-settings<67>啁<EFBFBD><E59581>券★<E588B8>株挽蝵桅△<E6A185>Ｖ葉<EFBCB6>𥕦遣鈭<E981A3><E988AD>銝果UI嚗<49><E59A97>霈貊鍂<E8B28A>瑕銁銝齿𦻖閫虫誨<E899AB><E8AAA8><EFBFBD><EFBFBD><EFBFBD><EFBFBD>銝钅<E98A9D>蝵格芋<E6A0BC>?1<>?
#### **2.1.2 璅∪<E79285>蝐?(ExternalModule.php) <20><><EFBFBD><EFBFBD>圈<EFBFBD>餉<EFBFBD>**
*案例分析：* permissions数组显式请求对特定钩子的访问权限。如果此处未列出某个钩子，即使在PHP类中定义了该函数，它也永远不会执行。project-settings数组在项目设置页面中创建了一个GUI，允许用户在不接触代码的情况下配置模块11。
#### **2.1.2 模块类 (ExternalModule.php) 的实现逻辑**
这个文件包含扩展AbstractExternalModule的PHP类。这种继承提供了对框架辅助方法的访问，如getProjectSetting、query和日志记录功能。
餈嗘葵<EFBFBD><EFBFBD>辣<EFBFBD><EFBFBD>鉄<EFBFBD>拙<EFBFBD>AbstractExternalModule<EFBFBD><EFBFBD>HP蝐颯<EFBFBD><EFBFBD><EFBFBD>蝘滨誧<EFBFBD>踵<EFBFBD>靘𥕢<EFBFBD>撖寞<EFBFBD><EFBFBD>嗉<EFBFBD><EFBFBD>拇䲮瘜閧<EFBFBD>霈輸䔮嚗<EFBFBD><EFBFBD>getProjectSetting<EFBFBD><EFBFBD>uery<EFBFBD>峕𠯫敹𡑒扇敶訫<EFBFBD><EFBFBD>賬<EFBFBD>?
**源代码示范：类结构与逻辑封装**
PHP
@@ -87,7 +100,7 @@ use REDCap;
class AdvancedDataProcessor extends AbstractExternalModule {
// 敶栞扇敶蓥<EFBFBD>摮䀹𧒄<EFBFBD>芸𢆡閫血<EFBFBD><EFBFBD><EFBFBD>䲮瘜?
// 当记录保存时自动触发的方法
public function redcap\_save\_record($project\_id, $record, $instrument, $event\_id, $group\_id, $survey\_hash, $response\_id, $repeat\_instance) {
// 1\. 检查该项目是否启用了模块逻辑
@@ -95,9 +108,9 @@ class AdvancedDataProcessor extends AbstractExternalModule {
return;
}
// 2\. <EFBFBD>脫迫<EFBFBD>𣳇<EFBFBD>敺芰㴓嚗?Infinite Loop Trap)
// 憒<EFBFBD><EFBFBD>甇文遆<EFBFBD>唬<EFBFBD>摮䀹㺭<EFBFBD>殷<EFBFBD>摰<EFBFBD>虾<EFBFBD>賭<EFBFBD><EFBFBD>齿活閫血<EFBFBD>redcap\_save\_record<EFBFBD>?
// 雿輻鍂<EFBFBD>蹱<EFBFBD><EFBFBD><EFBFBD>敹埈<EFBFBD>璉<EFBFBD><EFBFBD>乩<EFBFBD>摮䀹糓<EFBFBD>衣眏<EFBFBD>祆芋<EFBFBD>𡑒圻<EFBFBD>烐糓敹<EFBFBD>◆<EFBFBD><EFBFBD><EFBFBD>?
// 2\. 防止无限循环！(Infinite Loop Trap)
// 如果此函数保存数据，它可能会再次触发redcap\_save\_record。
// 使用静态标志或检查保存是否由本模块触发是必须的。
static $is\_processing \= false;
if ($is\_processing) return;
$is\_processing \= true;
@@ -106,7 +119,7 @@ class AdvancedDataProcessor extends AbstractExternalModule {
// 3\. 执行核心逻辑
$this\-\>processData($project\_id, $record, $instrument);
} catch (\\Exception $e) {
$this\-\>emError("憭<EFBFBD><EFBFBD>霈啣<EFBFBD> $record <EFBFBD>嗅枂<EFBFBD>? ". $e\-\>getMessage());
$this\-\>emError("处理记录 $record 时出错: ". $e\-\>getMessage());
}
$is\_processing \= false;
@@ -119,40 +132,50 @@ class AdvancedDataProcessor extends AbstractExternalModule {
}
}
餈嗵<EFBFBD>蝏𤘪<EFBFBD>蝖桐<EFBFBD>鈭<EFBFBD><EFBFBD>鋆<EFBFBD><EFBFBD>扼<EFBFBD><EFBFBD><EFBFBD>朞<EFBFBD>雿輻鍂namespace嚗峕芋<EFBFBD>烾<EFBFBD><EFBFBD>滢<EFBFBD>銝𤾸<EFBFBD>隞硋虾<EFBFBD>賭蝙<EFBFBD>函㮾隡潛掩<EFBFBD>滨<EFBFBD>璅∪<EFBFBD><EFBFBD>𤑳<EFBFBD><EFBFBD>脩<EFBFBD>13<EFBFBD>?
这种结构确保了封装性。通过使用namespace，模块避免了与其他可能使用相似类名的模块发生冲突13。
### **2.2 关键钩子（Hooks）与事件处理机制**
<EFBFBD>拙<EFBFBD><EFBFBD>臬僕憸<EFBFBD>EDCap撌乩<EFBFBD>瘚<EFBFBD><EFBFBD>銝餉<EFBFBD><EFBFBD>箏<EFBFBD><EFBFBD><EFBFBD><EFBFBD>隞砍<EFBFBD>霈詨<EFBFBD><EFBFBD>𤏸<EFBFBD><EFBFBD>銁摨𠉛鍂蝔见<EFBFBD><EFBFBD>笔𦶢<EFBFBD>冽<EFBFBD><EFBFBD><EFBFBD>鸌摰𡁶<EFBFBD><EFBFBD>扯<EFBFBD>隞<EFBFBD><EFBFBD>9<EFBFBD>?
#### **2.2.1 redcap\_save\_record嚗𡁏瓲敹<E793B2>㺭<EFBFBD>桀<EFBFBD><E6A180>?*
钩子是干预REDCap工作流的主要机制。它们允许开发者在应用程序生命周期的特定点执行代码9。
餈蹱糓鈭峕活撘<EFBFBD><EFBFBD>睲葉<EFBFBD><EFBFBD><EFBFBD>滩<EFBFBD><EFBFBD><EFBFBD>偬摮僐<EFBFBD><EFBFBD><EFBFBD><EFBFBD>冽㺭<EFBFBD>桀歇<EFBFBD>𣂷漱<EFBFBD>唳㺭<EFBFBD>桀<EFBFBD>*銋见<E98A8B>*嚗䔶<E59A97><E494B6>函鍂<E587BD>瑞<EFBFBD><E7919E>啁＆霈斗<E99C88><E69697>臭<EFBFBD><E887AD>㵪<EFBFBD><E3B5AA>冽<EFBFBD>鈭𥕢<E988AD>銝𧢲<E98A9D>銝哨<E98A9D><E593A8>硋銁<E7A18B>𤾸蝱靽嘥<E99DBD><E598A5>𡒊<EFBFBD><F0A1928A>唾圻<E594BE>㻫<EFBFBD>?
* **<2A><>㺭霂西圾嚗?* $project\_id嚗<64>★<EFBFBD>埋D嚗? $record嚗<64>扇敶訫<E695B6>嚗? $instrument嚗<74>”<EFBFBD>訫<EFBFBD>嚗? $event\_id嚗<64><E59A97>隞貂D嚗? $group\_id嚗<64>㺭<EFBFBD>株挪<E6A0AA>桃<EFBFBD>ID嚗? $survey\_hash嚗<68><E59A97><EFBFBD>亙<EFBFBD>撣䕘<E692A3>, $response\_id嚗<64><E59A97>摨㶏D嚗? $repeat\_instance嚗<65><E59A97>憭滚<E686AD>靘页<E99D98>14<31>?
#### **2.2.1 redcap\_save\_record：核心数据处理**
这是二次开发中最重要的钩子。它在数据已提交到数据库*之后*，但在用户看到确认消息之前（在某些上下文中）或在后台保存后立即触发。
* **参数详解：** $project\_id（项目ID）, $record（记录名）, $instrument（表单名）, $event\_id（事件ID）, $group\_id（数据访问组ID）, $survey\_hash（调查哈希）, $response\_id（响应ID）, $repeat\_instance（重复实例）14。
* **最佳应用场景：**
* **<EFBFBD>芸𢆡霂<EFBFBD><EFBFBD>銝舘恣蝞梹<EFBFBD>** 憭<><E686AD>REDCap<61><70>蔭霈∠<E99C88>摮埈挾<E59F88>䭾<EFBFBD>憭<EFBFBD><E686AD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>靘见<E99D98>嚗諹楊鈭衤辣霈∠<E99C88><E288A0>𡝗<EFBFBD><F0A19D97>𦠜辺隞園<E99A9E>餉<EFBFBD><E9A489><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>?
* **<EFBFBD>唳旿敶訫<EFBFBD>閫血<EFBFBD><EFBFBD>剁<EFBFBD>DET嚗㗇芋<EFBFBD><EFBFBD><EFBFBD>** 靽嘥<E99DBD><E598A5>嗥<EFBFBD><E597A5>喳<EFBFBD><E596B3>唳旿<E594B3>券<EFBFBD><E588B8><EFBFBD>憭㚚<E686AD>瘜典<E7989C>銵冽<E98AB5><E586BD>萄<EFBFBD><E89084><EFBFBD><EFBFBD>蝟餌<E89D9F>嚗𠄌MR嚗剹<E59A97>?
* **<EFBFBD>唳旿<EFBFBD>峕郊嚗?* <20>芸𢆡撠<F0A286A1><E692A0>𦦵<EFBFBD><F0A6A6B5>争<EFBFBD>嗪★<E597AA>桐葉<E6A190><E89189>㺭<EFBFBD>桀<EFBFBD><E6A180>嗅<EFBFBD><E59785>靝蜓<E99D9D>𠉛弦<F0A0899B>嗪★<E597AA>桐葉17<31>?
* **<EFBFBD>游𦶢<EFBFBD>琿𩐠嚗㇍he Infinite Loop嚗㚁<EFBFBD>** 銝<>銝芸虜閫<E8999C><E996AB><EFBFBD>躰秤<E8BAB0>盍edcap\_save\_record<EFBFBD><EFBFBD><EFBFBD>靚<EFBFBD>鍂REDCap::saveData<EFBFBD><EFBFBD>眏鈭粃aveData隡𡁜<EFBFBD>甈∟圻<EFBFBD>𩹨edcap\_save\_record嚗諹<EFBFBD>隡𡁜紡<EFBFBD>湔<EFBFBD><EFBFBD>鞾<EFBFBD>鍦<EFBFBD>嚗峕<EFBFBD>蝏<EFBFBD>紡<EFBFBD>湔<EFBFBD><EFBFBD>∪膥撏拇<EFBFBD>嚗<EFBFBD>挾<EFBFBD>躰秤<EFBFBD>硋<EFBFBD>摮䁅<EFBFBD>堒偷嚗剹<EFBFBD>?
* *閫<EFBFBD><EFBFBD><EFBFBD>寞<EFBFBD>嚗? 撘<><E69298>𤏸<EFBFBD><F0A48FB8><EFBFBD>憿餃<E686BF><E9A483>恍<EFBFBD>餉<EFBFBD><E9A489>交<EFBFBD><E4BAA4>乩<EFBFBD>摮䀹糓<E480B9>血歇<E8A180>刻<EFBFBD>銵䔶葉嚗峕<E59A97>雿輻鍂<E8BCBB><E98D82><EFBFBD><EFBFBD>典遆<E585B8>啁眏璅∪<E79285><E288AA>祈澈閫血<E996AB><E8A180>嗆<EFBFBD><E59786>漤<EFBFBD><E6BCA4><EFBFBD>箝<EFBFBD>?
* **自动评分与计算：** 处理REDCap内置计算字段无法处理的复杂评分（例如，跨事件计算或涉及条件逻辑的聚合）。
* **数据录入触发器（DET）模拟：** 保存时立即将数据推送到外部注册表或电子病历系统（EMR）。
* **数据同步：** 自动将“筛选”项目中的数据复制到“主研究”项目中17。
* **致命陷阱（The Infinite Loop）：** 一个常见的错误是redcap\_save\_record内部调用REDCap::saveData。由于saveData会再次触发redcap\_save\_record，这会导致无限递归，最终导致服务器崩溃（段错误或内存耗尽）。
* *解决方案：* 开发者必须包含逻辑来检查保存是否已在进行中，或使用标志在函数由模块本身触发时提前退出。
#### **2.2.2 redcap\_every\_page\_top：UI注入与全局控制**
甇日偬摮𣂼銁瘥譍葵憿寧𤌍銝𠹺<EFBFBD><EFBFBD><EFBFBD><EFBFBD>憿菟𢒰<EFBFBD>㰘蝸<EFBFBD>嗆<EFBFBD>銵䎚<EFBFBD>?
* **<2A><>雿喳<E99BBF><E596B3>典㦤<E585B8>荔<EFBFBD>**
* **UI/DOM<4F>滢<EFBFBD>嚗?* 瘜典<E7989C>JavaScript嚗<74>掩隡嘯hazam璅∪<E79285><E288AA><EFBFBD>䲮瘜𤏪<E7989C><F0A48FAA>乩耨<E4B9A9>道OM嚗<4D>抅鈭𤾸<E988AD><F0A4BEB8><EFBFBD><EFBFBD>餉<EFBFBD><E9A489>鞱<EFBFBD>摮埈挾嚗峕<E59A97><E5B395>湔㺿隞芸膥<E88AB8><E886A5><EFBFBD>閫?3<>?
* **CSS瘜典<EFBFBD>嚗?* <20>㰘蝸<E3B098>芸<EFBFBD>銋㗇甅撘讛”隞亙笆憿寧𤌍餈𥡝<E9A488><F0A5A19D><EFBFBD><EFBFBD><EFBFBD>硔<EFBFBD>?
* **<EFBFBD>扯<EFBFBD>霅血<EFBFBD>嚗?* <20>曹<EFBFBD>甇日偬摮𣂼銁*瘥譍<E798A5>憿?餈鞱<E9A488>嚗<EFBFBD>銁甇日偬摮𣂼<E691AE>餈𥡝<E9A488>蝜<EFBFBD><E89D9C><EFBFBD><EFBFBD>㺭<EFBFBD>桀<EFBFBD><E6A180>亥砭撠<E7A0AD>艇<EFBFBD>漤<EFBFBD>雿𡒊鍂<F0A1928A>瑚<EFBFBD>撉䎚<E69289><E48E9A>迨憭<E8BFA8><E686AD>隞<EFBFBD><E99A9E>敹<EFBFBD>◆<EFBFBD><E29786>漲頧駁<E9A0A7><E9A781>?
#### **2.2.3 redcap\_survey\_complete嚗𡁜<E59A97>銝舘<E98A9D><E88898><EFBFBD>蝔𧢲綉<F0A7A2B2>?*
此钩子在每个项目上下文的页面加载时执行。
* **最佳应用场景：**
* **UI/DOM操作：** 注入JavaScript（类似Shazam模块的方法）来修改DOM，基于复杂逻辑隐藏字段，或更改仪器的外观13。
* **CSS注入：** 加载自定义样式表以对项目进行品牌化。
* **性能警告：** 由于此钩子在*每一页*运行，在此钩子内进行繁重的数据库查询将严重降低用户体验。此处的代码必须极度轻量。
#### **2.2.3 redcap\_survey\_complete：参与者流程控制**
类似于save\_record，但专用于调查完成时。这是根据参与者的回答将他们重定向到不同URL，或发送超出标准“警报和通知”模块功能的自定义电子邮件通知的理想钩子18。
蝐颱撮鈭粃ave\_record嚗䔶<E59A97>銝梶鍂鈭舘<E988AD><E88898>亙<EFBFBD><E4BA99>鞉𧒄<E99E89><F0A79284><EFBFBD><EFBFBD>舀覔<E88880>桀<EFBFBD>銝舘<E98A9D><E88898><EFBFBD><EFBFBD>䂿<EFBFBD>撠<EFBFBD><E692A0>隞祇<E99A9E>摰𡁜<E691B0><F0A1819C>唬<EFBFBD><E594AC>𪄇RL嚗峕<E59A97><E5B395>煾<EFBFBD><E785BE><EFBFBD><EFBFBD>箸<EFBFBD><E7AEB8><EFBFBD><EFBFBD>𡏭郎<F0A18FAD>亙<EFBFBD><E4BA99>𡁶䰻<F0A181B6>脲芋<E884B2>堒<EFBFBD><E5A092>賜<EFBFBD><E8B39C>芸<EFBFBD>銋厩㩞摮鞾<E691AE>隞園<E99A9E>𡁶䰻<F0A181B6><E4B0BB><EFBFBD><EFBFBD>喲偬摮?8<>?
## ---
**3\. 数据库交互与安全工程**
鈭峕活撘<EFBFBD><EFBFBD>睲葉<EFBFBD><EFBFBD>憭抒<EFBFBD>憌𡡞埯銋衤<EFBFBD><EFBFBD>臭<EFBFBD>敶梶<EFBFBD><EFBFBD>唳旿摨㮖漱鈭𡜐<EFBFBD>餈坔虾<EFBFBD>賢紡<EFBFBD>巽QL瘜典<EFBFBD>嚗𠄎QLi嚗㗇<EFBFBD>瘣𠺶<EFBFBD><EFBFBD><EFBFBD>鈭竃EDCap摮睃<EFBFBD><EFBFBD>𤩺<EFBFBD><EFBFBD><EFBFBD><EFBFBD>靽脲擪<EFBFBD>亙熒靽⊥<EFBFBD>嚗㇊HI嚗㚁<EFBFBD>摰匧<EFBFBD><EFBFBD>扯秐<EFBFBD>喲<EFBFBD>閬<EFBFBD><EFBFBD>?
二次开发中最大的风险之一是不当的数据库交互，这可能导致SQL注入（SQLi）漏洞。鉴于REDCap存储敏感的受保护健康信息（PHI），安全性至关重要。
### **3.1 抽象查询方法与SQL注入防御**
<EFBFBD>冽唂<EFBFBD><EFBFBD><EFBFBD>隞嗡葉嚗<EFBFBD><EFBFBD><EFBFBD>𤏸<EFBFBD><EFBFBD><EFBFBD>撣訾蝙<EFBFBD>牡b\_query("SELECT \* FROM table WHERE id \= $id")<EFBFBD>?*餈蹱糓銝仿<E98A9D><E4BBBF><EFBFBD><EFBFBD><EFBFBD>刻<EFBFBD>閫?*嚗<><E59A97>銝箏<E98A9D><E7AE8F>?id<69>舐鍂<E88890>瑁<EFBFBD><E79181>伐<EFBFBD>摰<EFBFBD><E691B0>霈祿QL瘜典<E7989C>19<31>?
憭㚚<EFBFBD>璅∪<EFBFBD>獢<EFBFBD>沲撘訫<EFBFBD>鈭<EFBFBD><EFBFBD><EFBFBD>函<EFBFBD><EFBFBD>亥砭蝐颯<EFBFBD><EFBFBD><EFBFBD><EFBFBD>𤏸<EFBFBD><EFBFBD><EFBFBD>雿輻鍂$this-\>query()嚗<><E59A97>ExternalModules::query嚗㚁<E59A97>霂交䲮瘜閙𣈲<E99699><F0A388B2><EFBFBD><EFBFBD>啣<EFBFBD><E595A3>亥砭<E4BAA5>?
**<EFBFBD><EFBFBD>摹隞<EFBFBD><EFBFBD>嚗<EFBFBD>艇蝳<EFBFBD>蝙<EFBFBD>剁<EFBFBD>嚗?*
在旧版插件中，开发者经常使用db\_query("SELECT \* FROM table WHERE id \= $id")。**这是严重的安全违规**，因为如果$id是用户输入，它允许SQL注入19。
外部模块框架引入了安全的查询类。开发者应使用$this-\>query()（或ExternalModules::query），该方法支持参数化查询。
**脆弱代码（严禁使用）：**
PHP
@@ -160,11 +183,11 @@ PHP
$sql \= "SELECT value FROM redcap\_data WHERE project\_id \= ". $\_GET\['pid'\]. " AND field\_name \= '". $\_GET\['field'\]. "'";
$q \= db\_query($sql);
**摰匧<EFBFBD>隞<EFBFBD><EFBFBD>嚗<EFBFBD><EFBFBD>雿喳<EFBFBD>頝蛛<EFBFBD>嚗?*
**安全代码（最佳实践）：**
PHP
// <EFBFBD><EFBFBD>㺭<EFBFBD>𡝗䰻霂?
// 参数化查询
$sql \= "SELECT value FROM redcap\_data WHERE project\_id \=? AND field\_name \=?";
$q \= $this\-\>query($sql, \[$project\_id, $field\_name\]);
@@ -172,43 +195,55 @@ while ($row \= $q\-\>fetch\_assoc()) {
// 安全处理数据
}
雿輻鍂?<3F>牐<EFBFBD>蝚衣＆靽脲㺭<E884B2>桀<EFBFBD>撽勗𢆡蝔见<E89D94>撖寡<E69296><E5AFA1>亥<EFBFBD>銵諹蓮銋㚁<E98A8B>隞舘<E99A9E>䔶葉<E494B6>峕𤫇<E5B395>餉<EFBFBD><E9A489>釣<EFBFBD>亦<EFBFBD>隞颱<E99A9E><E9A2B1>嗆<EFBFBD>SQL<51>賭誘11<31>?
使用?占位符确保数据库驱动程序对输入进行转义，从而中和攻击者注入的任何恶意SQL命令11。
### **3.2 跨站脚本攻击（XSS）的防御**
敶𤘪芋<EFBFBD>堒<EFBFBD>瘚讛<EFBFBD><EFBFBD>刻<EFBFBD><EFBFBD>箸㺭<EFBFBD>格𧒄<EFBFBD>婙<EFBFBD>𥪜陘<EFBFBD>嗆糓<EFBFBD>冽<EFBFBD>颲枏<EFBFBD><EFBFBD><EFBFBD>㺭<EFBFBD>栽<EFBFBD>婙<EFBFBD>𥪜<EFBFBD>憿駁俈甇°SS<EFBFBD><EFBFBD><EFBFBD><EFBFBD>𦦵鍂<EFBFBD>瑕銁<EFBFBD><EFBFBD>𧋦摮埈挾銝剛<EFBFBD><EFBFBD>功<script\>alert('Hack');\</script\>嚗諹<E59A97>峕芋<E5B395>堒銁隞芾”<E88ABE>蹂<EFBFBD><E8B982>曄內霂亙<E99C82>畾萎<E795BE><E8908E>芾<EFBFBD>銵諹蓮銋㚁<E98A8B><E39A81>𡁏𧋦撠<F0A78BA6>銁<EFBFBD>亦<EFBFBD><E4BAA6><EFBFBD><EFBFBD>瘚讛<E7989A><E8AE9B>其葉<E585B6>扯<EFBFBD><E689AF>?
当模块向浏览器输出数据时——尤其是用户输入的数据——必须防止XSS。如果用户在文本字段中输入\<script\>alert('Hack');\</script\>，而模块在仪表板上显示该字段且未进行转义，脚本将在查看者的浏览器中执行。
最佳实践：
憪讠<EFBFBD>撠<EFBFBD><EFBFBD><EFBFBD>箏<EFBFBD>鋆孵銁REDCap::escapeHtml()銝哨<EFBFBD><EFBFBD>碶蝙<EFBFBD>冽<EFBFBD><EFBFBD>嗥<EFBFBD>撘箏<EFBFBD><EFBFBD>寞<EFBFBD><EFBFBD>?
始终将输出包裹在REDCap::escapeHtml()中，或使用框架的强制方法。
PHP
echo "用户备注: ". REDCap::escapeHtml($user\_note);
<EFBFBD>芾<EFBFBD><EFBFBD>扯<EFBFBD>甇斗<EFBFBD>雿𨀣糓璅∪<EFBFBD><EFBFBD>刻<EFBFBD><EFBFBD>笔恣<EFBFBD>亥<EFBFBD>蝔衤葉鋡急<EFBFBD>蝏萘<EFBFBD>銝餉<EFBFBD><EFBFBD>笔<EFBFBD>22<EFBFBD>?
未能执行此操作是模块在联盟审查过程中被拒绝的主要原因22。
### **3.3 数据访问组（DAGs）与权限隔离**
敶梶凒<EFBFBD>仿<EFBFBD>撖雹edcap\_data蝻硋<EFBFBD>SQL<EFBFBD>亥砭<EFBFBD>塚<EFBFBD>璅∪<EFBFBD>隡𡁶<EFBFBD>餈𧍒EDCap<EFBFBD><EFBFBD><EFBFBD><EFBFBD>函<EFBFBD>摨讐漣摰匧<EFBFBD><EFBFBD>改<EFBFBD><EFBFBD><EFBFBD>𡠺<EFBFBD>唳旿霈輸䔮蝏<EFBFBD><EFBFBD>DAGs嚗剹<EFBFBD><EFBFBD>䰻霂Ｗ虾<EFBFBD>賭<EFBFBD><EFBFBD>䭾<EFBFBD>銝剛<EFBFBD><EFBFBD>鮋★<EFBFBD>桐葉<EFBFBD><EFBFBD><EFBFBD><EFBFBD>㕑扇敶𤏪<EFBFBD>隞舘<EFBFBD><EFBFBD><EFBFBD>霈貊<EFBFBD><EFBFBD>農<EFBFBD><EFBFBD>鍂<EFBFBD>瑞<EFBFBD><EFBFBD>啁<EFBFBD><EFBFBD>運<EFBFBD><EFBFBD>㺭<EFBFBD>柴<EFBFBD>?
当直接针对redcap\_data编写SQL查询时，模块会绕过REDCap的应用程序级安全性，包括数据访问组（DAGs）。查询可能会无意中返回项目中的所有记录，从而允许站点A的用户看到站点B的数据。
最佳实践：
<EFBFBD>芾<EFBFBD><EFBFBD>航<EFBFBD>嚗諹窈雿輻鍂REDCap::getData()<EFBFBD>寞<EFBFBD>隞<EFBFBD>𤜯<EFBFBD>笔<EFBFBD>SQL<EFBFBD><EFBFBD>EDCap::getData()隡朞䌊<EFBFBD>典<EFBFBD><EFBFBD>䄂AG<EFBFBD>𣬚鍂<EFBFBD>瑟<EFBFBD><EFBFBD>僐<EFBFBD>?
只要可能，请使用REDCap::getData()方法代替原始SQL。REDCap::getData()会自动尊重DAG和用户权限。
PHP
$data \= REDCap::getData($project\_id, 'array', $record\_id);
憒<EFBFBD><EFBFBD><EFBFBD>箔<EFBFBD><EFBFBD>扯<EFBFBD><EFBFBD>笔<EFBFBD>敹<EFBFBD>◆雿輻鍂<EFBFBD>笔<EFBFBD>SQL嚗<EFBFBD><EFBFBD><EFBFBD>𤏸<EFBFBD>?敹<>◆*<2A>见𢆡餈墧𦻖redcap\_data\_access\_groups銵剁<E98AB5>撟嗆覔<E59786>桀<EFBFBD><E6A180>滨鍂<E6BBA8>瑞<EFBFBD>group\_id餈𥡝<E9A488>餈<EFBFBD>誘24<32>?
如果出于性能原因必须使用原始SQL，开发者*必须*手动连接redcap\_data\_access\_groups表，并根据当前用户的group\_id进行过滤24。
## ---
**4\. 移动端交互：REDCap Mobile App深度解析**
REDCap<EFBFBD>滚𦛚<EFBFBD>其<EFBFBD>蝘餃𢆡霈曉<EFBFBD>銋钅𡢿<EFBFBD><EFBFBD>漱鈭埝糓鈭峕活撘<EFBFBD><EFBFBD>𤑳<EFBFBD><EFBFBD>喲睸憸<EFBFBD><EFBFBD>嚗𣬚鸌<EFBFBD>急糓<EFBFBD>其<EFBFBD><EFBFBD>𠉛<EFBFBD>餈墧𦻖颲<EFBFBD>榆<EFBFBD><EFBFBD>𧑐<EFBFBD>箄<EFBFBD>銵<EFBFBD><EFBFBD><EFBFBD>啁<EFBFBD>蝛嗆𧒄<EFBFBD>?
### **4.1 REDCap Mobile App<70><70>沲<EFBFBD><E6B2B2><EFBFBD>撌乩<E6928C>瘚?*
REDCap服务器与移动设备之间的交互是二次开发的关键领域，特别是在互联网连接较差的地区进行实地研究时。
### **4.1 REDCap Mobile App的架构与工作流**
REDCap Mobile App是一个“胖客户端”，它将项目结构（元数据）和数据（可选）下载到本地设备。它充当本地Web服务器，允许离线数据收集。当恢复连接时，它通过REDCap API将数据同步回中央服务器25。
REDCap Mobile App<70>臭<EFBFBD>銝芬<E98A9D>𡏭<EFBFBD>摰Ｘ<E691B0>蝡胼<E89DA1>嘅<EFBFBD>摰<EFBFBD><E691B0>憿寧𤌍蝏𤘪<E89D8F>嚗<EFBFBD><E59A97><EFBFBD>唳旿嚗匧<E59A97><E58CA7>唳旿嚗<E697BF>虾<EFBFBD>㚁<EFBFBD>銝贝蝸<E8B49D>唳𧋦<E594B3>啗挽憭<E68CBD><E686AD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>砍𧑐Web<65>滚𦛚<E6BB9A>剁<EFBFBD><E58981><EFBFBD>捂蝳餌瑪<E9A48C>唳旿<E594B3>園<EFBFBD><E59C92><EFBFBD><EFBFBD><EFBFBD>Ｗ<EFBFBD>餈墧𦻖<E5A2A7>塚<EFBFBD>摰<EFBFBD><E691B0>朞<EFBFBD>REDCap API撠<49>㺭<EFBFBD>桀<EFBFBD>甇亙<E79487>銝剖亢<E58996>滚𦛚<E6BB9A>?5<>?
### **4.2 API同步机制与JSON Payload**
<EFBFBD>峕郊餈<EFBFBD><EFBFBD>擃睃漲靘肽<EFBFBD>鈭垾PI隞斤<EFBFBD>嚗㇍oken嚗剹<EFBFBD>?
1. **隞斤<E99A9E><E696A4><EFBFBD><EFBFBD>嚗?* <20>冽<EFBFBD><E586BD>冽<EFBFBD><E586BD>∪膥蝡舐<E89DA1><E88890>𣂷誘<F0A382B7>䎚<EFBFBD>?
2. **<EFBFBD>嘥<EFBFBD><EFBFBD>吔<EFBFBD>** 摨𠉛鍂蝔见<E89D94><E8A781>急<EFBFBD><E680A5><EFBFBD>鉄<EFBFBD>嘥<EFBFBD><E598A5>碶誨<E7A2B6><E8AAA8><EFBFBD>鈭𣬚輕<F0A3AC9A><E8BC95><EFBFBD>霂乩誨<E4B9A9><E8AAA8><EFBFBD>霂<EFBFBD>挽憭<E68CBD>僎銝贝蝸憿寧𤌍XML嚗<4C><E59A97><EFBFBD>唳旿嚗?5<>?
3. **<EFBFBD>唳旿隡㰘<EFBFBD>嚗?* 霈曉<E99C88>銝𦠜𤣰<F0A6A09C><F0A4A3B0><EFBFBD><EFBFBD>唳旿摮睃<E691AE><E79D83>典<EFBFBD>撖<EFBFBD><E69296>SQLCipher<65>唳旿摨㮖葉嚗ǎOS/Android嚗剹<E59A97><E589B9><EFBFBD>甇交𧒄嚗淾pp<70>魀mportRecords API蝡舐<E89DA1><E88890>煾<EFBFBD><E785BE>SON<4F>㗇<EFBFBD>韐蠘蝸<E8A098>?
JSON Payload蝏𤘪<E89D8F>嚗<EFBFBD><E59A97>甇伐<E79487>嚗?
API<EFBFBD><EFBFBD><EFBFBD><EFBFBD>唳旿<EFBFBD><EFBFBD>鍂<EFBFBD>孵<EFBFBD><EFBFBD><EFBFBD>SON蝏𤘪<EFBFBD><EFBFBD><EFBFBD>笆鈭擧<EFBFBD>撱箄䌊撌梁<EFBFBD>蝘餃𢆡<EFBFBD>亙藁嚗<EFBFBD>𤜯隞<EFBFBD><EFBFBD><EFBFBD>農pp嚗厩<EFBFBD>鈭峕活撘<EFBFBD><EFBFBD>𤏸<EFBFBD><EFBFBD>䔉霂湛<EFBFBD><EFBFBD>萄<EFBFBD>甇斗芋撘𤩺糓撘箏<EFBFBD><EFBFBD>抒<EFBFBD><EFBFBD>?
同步过程高度依赖于API令牌（Token）。
1. **令牌生成：** 用户在服务器端生成令牌。
2. **初始化：** 应用程序扫描包含初始化代码的二维码，该代码验证设备并下载项目XML（元数据）25。
3. **数据传输：** 设备上收集的数据存储在加密的SQLCipher数据库中（iOS/Android）。同步时，App向importRecords API端点发送JSON有效负载。
JSON Payload结构（同步）：
API期望数据采用特定的JSON结构。对于构建自己的移动接口（替代官方App）的二次开发者来说，遵守此模式是强制性的。
JSON
\[
@@ -221,44 +256,57 @@ JSON
}
\]
28<EFBFBD>?
### **4.3 <20>脩<EFBFBD>閫<EFBFBD><E996AB>銝𡡞<E98A9D><F0A1A19E>拍恣<E68B8D>?*
28。
### **4.3 冲突解决与风险管理**
移动集成中的一个主要“陷阱”是**同步冲突**。如果用户A在服务器上编辑记录101，而用户B在离线移动应用程序上编辑记录101，则同步期间会发生冲突。REDCap Mobile App具有基本的冲突解决界面，要求用户选择“服务器版本”或“设备版本”。
**二次开发启示：** 如果您正在构建自动脚本（例如DET）来修改正在被移动数据收集者使用的记录，则会增加冲突的风险。
* *最佳实践：* 移动用户应分配新的、唯一的记录或特定的DAG，以防止与服务器端进程发生重叠编辑30。
蝘餃𢆡<EFBFBD><EFBFBD><EFBFBD>銝剔<EFBFBD>銝<EFBFBD>銝芯蜓閬<EFBFBD><EFBFBD>𣈯萅<EFBFBD>晦<EFBFBD>脲糓**<2A>峕郊<E5B395>脩<EFBFBD>**<2A><><EFBFBD><EFBFBD>𦦵鍂<F0A6A6B5>嫂<EFBFBD>冽<EFBFBD><E586BD>∪膥銝羓<E98A9D>颲𤏸扇敶?01嚗諹<E59A97>𣬚鍂<F0A3AC9A>媲<EFBFBD>函氖蝥輻宏<E8BCBB>典<EFBFBD><E585B8>函<EFBFBD>摨譍<E691A8>蝻𤥁<E89DBB>霈啣<E99C88>101嚗<31><E59A97><EFBFBD>峕郊<E5B395>罸𡢿隡𡁜<E99AA1><F0A1819C>笔<EFBFBD>蝒<EFBFBD><E89D92><EFBFBD>EDCap Mobile App<70>瑟<EFBFBD><E7919F>箸𧋦<E7AEB8><F0A78BA6><EFBFBD>蝒<EFBFBD>圾<EFBFBD>喟<EFBFBD><E5969F>ｇ<EFBFBD>閬<EFBFBD><E996AC><EFBFBD>冽<EFBFBD><E586BD>㗇𥋘<E39787>𨀣<EFBFBD><F0A880A3>∪膥<E288AA><E886A5>𧋦<EFBFBD>脲<EFBFBD><E884B2>𡏭挽憭<E68CBD><E686AD><EFBFBD>砂<EFBFBD>腈<EFBFBD>?
**鈭峕活撘<E6B4BB><E69298>穃鍳蝷綽<E89DB7>** 憒<><E68692><EFBFBD>冽迤<E586BD>冽<EFBFBD>撱箄䌊<E7AE84>刻<EFBFBD><E588BB>穿<EFBFBD>靘见<E99D98>DET嚗㗇䔉靽格㺿甇<E3BABF>銁鋡怎宏<E6808E>冽㺭<E586BD>格𤣰<E6A0BC><F0A4A3B0><EFBFBD><EFBFBD>蝙<EFBFBD>函<EFBFBD>霈啣<E99C88>嚗<EFBFBD><E59A97>隡𡁜<E99AA1><F0A1819C>惩<EFBFBD>蝒<EFBFBD><E89D92>憌𡡞埯<F0A1A19E>?
* *<EFBFBD><EFBFBD>雿喳<EFBFBD>頝蛛<EFBFBD>* 蝘餃𢆡<E9A483>冽<EFBFBD>摨𥪜<E691A8><F0A5AA9C>齿鰵<E9BDBF><E9B0B5><EFBFBD><EFBFBD>𣈲銝<F0A388B2><E98A9D><EFBFBD>扇敶閙<E695B6><E99699>孵<EFBFBD><E5ADB5><EFBFBD>AG嚗䔶誑<E494B6>脫迫銝擧<E98A9D><E693A7>∪膥蝡航<E89DA1>蝔见<E89D94><E8A781>罸<EFBFBD><E7BDB8>删<EFBFBD>颲?0<>?
## ---
**5\. MyCap：参与者端的定制与交互**
<EFBFBD>賜<EFBFBD>REDCap Mobile App<EFBFBD>舫𢒰<EFBFBD>𤑳<EFBFBD>蝛嗡犖<EFBFBD>条<EFBFBD>嚗䔶<EFBFBD>**MyCap**<2A>舫𢒰<E888AB>穃<EFBFBD>銝舘<E98A9D><E88898><EFBFBD><EFBFBD><EFBFBD>yCap<61><70><EFBFBD>脲糓銝<E7B393>銝芸<E98A9D><E88AB8>冽芋<E586BD>梹<EFBFBD><E6A2B9>𤾸銁13.0<EFBFBD><EFBFBD>𧋦銝剛◤<EFBFBD><EFBFBD><EFBFBD><EFBFBD>訌EDCap<EFBFBD>詨<EFBFBD>銝哨<EFBFBD>蝒<EFBFBD>遬鈭<EFBFBD><EFBFBD><EFBFBD>滩<EFBFBD><EFBFBD>?2<>?
虽然REDCap Mobile App是面向研究人员的，但**MyCap**是面向参与者的。MyCap最初是一个外部模块，后在13.0版本中被集成到REDCap核心中，突显了其重要性32。
### **5.1 架构：ResearchKit与ResearchStack**
MyCap<EFBFBD>拍鍂鈭<EFBFBD>pple<EFBFBD>?*ResearchKit**嚗ǎOS嚗匧<EFBFBD>**ResearchStack**嚗㇁ndroid嚗剹<EFBFBD><EFBFBD><EFBFBD>鈭𥟇糓銝㮖蛹<EFBFBD>餃郎<EFBFBD>𠉛弦摨𠉛鍂蝔见<EFBFBD>霈曇恣<EFBFBD><EFBFBD><EFBFBD>皞鞉<EFBFBD><EFBFBD>嗚<EFBFBD><EFBFBD>yCap<EFBFBD><EFBFBD><EFBFBD>獢交<EFBFBD>嚗?
1. **<EFBFBD>滨蔭嚗?* <20>𠉛弦鈭箏<E988AD><E7AE8F>沖EDCap銝剝<E98A9D>蝵桐遙<E6A190>～<EFBFBD>?
2. **頧祆揢嚗?* MyCap撠<70>EDCap<61><70>㺭<EFBFBD>株蓮<E6A0AA>Ｖ蛹ResearchKit撖寡情摰帋<E691B0><E5B88B>?
3. **<EFBFBD>扯<EFBFBD>嚗?* 摨𠉛鍂蝔见<E89D94>撠<EFBFBD><E692A0>鈭𥕦笆鞊⊥葡<E28AA5>㮖蛹<E3AE96>毺<EFBFBD>蝘餃𢆡閫<F0A286A1>㦛嚗<E3A69B><E59A97>屸<EFBFBD>Web閫<62>㦛嚗㚁<E59A97><E39A81>𣂷<EFBFBD>瘚<EFBFBD><E7989A><EFBFBD><EFBFBD>pp雿㯄<E99BBF>34<33>?
MyCap利用了Apple的**ResearchKit**（iOS）和**ResearchStack**（Android）。这些是专为医学研究应用程序设计的开源框架。MyCap充当桥梁：
1. **配置：** 研究人员在REDCap中配置任务。
2. **转换：** MyCap将REDCap元数据转换为ResearchKit对象定义。
3. **执行：** 应用程序将这些对象渲染为原生移动视图（而非Web视图），提供流畅的App体验34。
### **5.2 主动任务（Active Tasks）的定制**
MyCap<EFBFBD><EFBFBD><EFBFBD>祉鸌<EFBFBD><EFBFBD><EFBFBD><EFBFBD>賣糓<EFBFBD>靝蜓<EFBFBD>其遙<EFBFBD>﹦<EFBFBD>吲<EFBFBD>婙<EFBFBD>𥪜⏚<EFBFBD>冽<EFBFBD><EFBFBD>箔<EFBFBD><EFBFBD>笔膥嚗<EFBFBD><EFBFBD><EFBFBD>笔漲霈～<EFBFBD><EFBFBD>漲<EFBFBD>钅<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>箔貌嚗㗇<EFBFBD><EFBFBD>讛恕<EFBFBD>交<EFBFBD>頨思<EFBFBD><EFBFBD>蠘<EFBFBD><EFBFBD><EFBFBD>暑<EFBFBD>剁<EFBFBD>靘见<EFBFBD>嚗峕䛵<EFBFBD>駁<EFBFBD>笔漲<EFBFBD><EFBFBD>郊<EFBFBD><EFBFBD><EFBFBD>撟唾﹛<EFBFBD><EFBFBD>征<EFBFBD>渲扇敹<EFBFBD><EFBFBD>37<EFBFBD>?
MyCap最独特的功能是“主动任务”——利用手机传感器（加速度计、麦克风、陀螺仪）测量认知或身体功能的活动（例如，敲击速度、步态与平衡、空间记忆）37。
二次开发机会：
撘<EFBFBD><EFBFBD>𤏸<EFBFBD><EFBFBD>虾隞亙<EFBFBD>撱箄䌊摰帋<EFBFBD><EFBFBD><EFBFBD>蜓<EFBFBD>其遙<EFBFBD>∴<EFBFBD>雿<EFBFBD><EFBFBD><EFBFBD><EFBFBD>閬<EFBFBD>wift嚗ǎOS嚗㗇<EFBFBD>Kotlin/Java嚗㇁ndroid嚗厩<EFBFBD>擃条漣<EFBFBD>亥<EFBFBD>嚗<EFBFBD>僎靽格㺿MyCap皞𣂷誨<EFBFBD><EFBFBD><EFBFBD>餈䠷<EFBFBD>閬<EFBFBD><EFBFBD><EFBFBD>䔶<EFBFBD>REDCap<EFBFBD>詨<EFBFBD>霈詨虾<EFBFBD><EFBFBD>鸌摰朞<EFBFBD><EFBFBD>鬹pp皞𣂷誨<EFBFBD><EFBFBD>捂<EFBFBD>荔<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>䕘<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>甈∪<EFBFBD><EFBFBD>煾<EFBFBD>𡁜虜靘折<EFBFBD>鈭舘圻<EFBFBD>餹yCap<EFBFBD>滢<EFBFBD><EFBFBD>硋<EFBFBD><EFBFBD><EFBFBD>yCap<EFBFBD>唳旿<EFBFBD>?
* *獢<><E78DA2>嚗? 銝<>銝芸<E98A9D><E88AB8>冽芋<E586BD>梹<EFBFBD><E6A2B9>朞<EFBFBD>redcap\_save\_record<72>烐綉隡惩<E99AA1><E683A9><EFBFBD>yCap銝餃𢆡隞餃𦛚<E9A483>唳旿嚗<E697BF><E59A97><EFBFBD>𨅯<EFBFBD>銝舘<E98A9D><E88898><EFBFBD><EFBFBD>𨀣郊<F0A880A3><E9838A><EFBFBD>笔漲<E7AC94>苷<EFBFBD>鈭𡒊鸌摰𡁻<E691B0><F0A181BB>潘<EFBFBD>銵冽<E98AB5>頝<EFBFBD><E9A09D>㘾<EFBFBD><E398BE>抬<EFBFBD>嚗<EFBFBD><E59A97>閫血<E996AB>霅行𥁒38<33>?
开发者可以创建自定义的主动任务，但这需要Swift（iOS）或Kotlin/Java（Android）的高级知识，并修改MyCap源代码（这需要不同于REDCap核心许可的特定联盟App源代码许可）。然而，标准的二次开发通常侧重于触发MyCap操作或处理MyCap数据。
* *案例：* 一个外部模块，通过redcap\_save\_record监控传入的MyCap主动任务数据，如果参与者的“步态速度”低于特定阈值（表明跌倒风险），则触发警报38。
### **5.3 通过外部模块定制MyCap**
撠賜恣MyCap<EFBFBD>舀瓲敹<EFBFBD><EFBFBD><EFBFBD>踝<EFBFBD>EM隞滨<EFBFBD><EFBFBD>臭誑憓𧼮撩摰<EFBFBD><EFBFBD><EFBFBD><EFBFBD>憒<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>其<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>𣬚<EFBFBD><EFBFBD>芸<EFBFBD>銋劐<EFBFBD>蝏渡<EFBFBD>撟嗉䌊<EFBFBD>券<EFBFBD>朞<EFBFBD><EFBFBD>萄<EFBFBD><EFBFBD>桐辣<EFBFBD>煾<EFBFBD><EFBFBD><EFBFBD><EFBFBD>pp Links<6B>蠘<EFBFBD><E8A098><EFBFBD>捂隞𤾸<E99A9E><F0A4BEB8>冽<EFBFBD>瘛勗漲<E58B97>暹𦻖<E69AB9>衽yCap摨𠉛鍂蝔见<E89D94>39<33>?
尽管MyCap是核心功能，EM仍然可以增强它。例如，生成用于参与者入职的自定义二维码并自动通过电子邮件发送。App Links功能允许从外部源深度链接到MyCap应用程序39。
## ---
**6\. REDCap API嚗𡁶<EFBFBD><EFBFBD><EFBFBD>頂蝏毺<EFBFBD><EFBFBD>芸𢆡<EFBFBD>𡝗‘璇?*
**6\. REDCap API：生态系统的自动化桥梁**
API<EFBFBD>臭<EFBFBD><EFBFBD>滢<EFBFBD><EFBFBD>抒<EFBFBD><EFBFBD>舀<EFBFBD><EFBFBD><EFBFBD>笆鈭𦒘<EFBFBD>甈∪<EFBFBD><EFBFBD>𤏸<EFBFBD>諹<EFBFBD>嚗<EFBFBD><EFBFBD><EFBFBD>𡁜虜<EFBFBD>舐<EFBFBD><EFBFBD>坔<EFBFBD><EFBFBD>冽芋<EFBFBD>㛖<EFBFBD><EFBFBD>蹂誨<EFBFBD>寞<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>𣈯<EFBFBD>餉<EFBFBD><EFBFBD>臭誑<EFBFBD>朞<EFBFBD><EFBFBD>每ron雿靝<EFBFBD>銝𡃏<EFBFBD>銵𣬚<EFBFBD>憭㚚<EFBFBD><EFBFBD>𡁏𧋦嚗㇊ython/R嚗㗇䔉憭<E49489><E686AD>嚗屸<E59A97>銋<EFBFBD><E98A8B><EFBFBD>𡁜虜瘥𥪜銁<F0A5AA9C>滚𦛚<E6BB9A>其<EFBFBD>摰㕑<E691B0>PHP璅∪<E79285><E288AA>游<EFBFBD><E6B8B8>具<EFBFBD>?
### **6.1 撖澆枂銝𤾸紡<F0A4BEB8>亦<EFBFBD><E4BAA6><EFBFBD>雿喳<E99BBF>頝?*
API是互操作性的支柱。对于二次开发而言，它通常是编写外部模块的替代方案。如果逻辑可以通过在Cron作业上运行的外部脚本（Python/R）来处理，那么这通常比在服务器上安装PHP模块更安全。
### **6.1 导出与导入的最佳实践**
* **分批处理（Batching）：** 导出大型数据集时，一次请求所有记录会导致超时。
* *解决方案：* 使用batch\_size参数或分块循环遍历记录。
* **类型处理：** 默认情况下，API在JSON中将所有数据作为字符串返回。
* *陷阱：* 在PHP/Python布尔检查中，字段值“0”（字符串）在某些上下文中为真，但“0”（整数）为假。开发者必须严格对API响应进行类型转换40。
* **“扁平”与“EAV”导出：** API创建一个“扁平”文件（每个记录/事件一行）。这与后端的EAV结构不同。二次开发者通常构建“数据录入触发器”（DET），每当保存记录时，该触发器都会收到来自REDCap的POST请求，然后调用API导出该特定记录进行处理42。
* **<2A><>鸌憭<E9B88C><E686AD>嚗㇂atching嚗㚁<E59A97>** 撖澆枂憭批<E686AD><E689B9>唳旿<E594B3><E697BF>𧒄嚗䔶<E59A97>甈∟窈瘙<E7AA88><E79899><EFBFBD>㕑扇敶蓥<E695B6>撖潸稲頞<E7A8B2>𧒄<EFBFBD>?
* *閫<><E996AB><EFBFBD>寞<EFBFBD>嚗? 雿輻鍂batch\_size<7A><65>㺭<EFBFBD>硋<EFBFBD><E7A18B>堒儐<E5A092>舫<EFBFBD><E888AB><EFBFBD>扇敶𨰻<E695B6>?
* **蝐餃<E89D90>憭<EFBFBD><E686AD>嚗?* 暺䁅恕<E48185><E68195><EFBFBD>銝页<E98A9D>API<50>沅SON銝剖<E98A9D><E58996><EFBFBD><EFBFBD>㗇㺭<E39787>桐<EFBFBD>銝箏<E98A9D>蝚虫葡餈𥪜<E9A488><F0A5AA9C>?
* *<2A>琿𩐠嚗? <20>沌HP/Python撣<6E><E692A3>璉<EFBFBD><E79289>乩葉嚗<E89189><E59A97>畾萄<E795BE>潑<EFBFBD>?<3F>嘅<EFBFBD>摮㛖泵銝莎<E98A9D><E88E8E>冽<EFBFBD>鈭𥕢<E988AD>銝𧢲<E98A9D>銝凋蛹<E5878B><E89BB9><EFBFBD>雿<EFBFBD><E99BBF>?<3F>嘅<EFBFBD><E59885>湔㺭嚗劐蛹<E58A90><E89BB9><EFBFBD><EFBFBD><EFBFBD><EFBFBD>𤏸<EFBFBD><F0A48FB8><EFBFBD>憿颱艇<E9A2B1>澆笆API<50>滚<EFBFBD>餈𥡝<E9A488>蝐餃<E89D90>頧祆揢40<34>?
* **<2A>𨀣<EFBFBD>撟喇<E6929F>苷<EFBFBD><E88BB7>諪AV<41>嘥紡<E598A5>綽<EFBFBD>** API<50>𥕦遣銝<E981A3>銝芬<E98A9D>𨀣<EFBFBD>撟喇<E6929F>脲<EFBFBD>隞塚<E99A9E>瘥譍葵霈啣<E99C88>/鈭衤辣銝<E8BEA3>銵䕘<E98AB5><E49598><EFBFBD><EFBFBD>銝𤾸<E98A9D>蝡舐<E89DA1>EAV蝏𤘪<E89D8F>銝滚<E98A9D><E6BB9A><EFBFBD><EFBFBD>甈∪<E79488><E288AA>𤏸<EFBFBD><F0A48FB8><EFBFBD>𡁜虜<F0A1819C><E8999C>遣<EFBFBD>𨀣㺭<F0A880A3>桀<EFBFBD><E6A180>亥圻<E4BAA5>穃膥<E7A983>嘅<EFBFBD>DET嚗㚁<E59A97>瘥誩<E798A5>靽嘥<E99DBD>霈啣<E99C88><E595A3>塚<EFBFBD>霂亥圻<E4BAA5>穃膥<E7A983>賭<EFBFBD><E8B3AD>嗅<EFBFBD><E59785>亥䌊REDCap<61><70>OST霂瑟<E99C82>嚗𣬚<E59A97><F0A3AC9A>舘<EFBFBD><E88898>杗PI撖澆枂霂亦鸌摰朞扇敶閗<E695B6>銵<EFBFBD><E98AB5><EFBFBD>?2<>?
**代码示范：Python API导出脚本**
Python
@@ -267,7 +315,7 @@ import requests
import pandas as pd
api\_url \= 'https://redcap.institution.edu/api/'
\# payload<EFBFBD><EFBFBD><EFBFBD>?
\# payload构造
payload \= {
'token': 'YOUR\_32\_CHAR\_TOKEN',
'content': 'record',
@@ -291,60 +339,74 @@ except requests.exceptions.RequestException as e:
except ValueError:
print("JSON解码失败 \- 响应可能非JSON格式")
44<EFBFBD>?
44。
## ---
**7\. <EFBFBD><EFBFBD>雿單<EFBFBD>靘讠<EFBFBD>蝛塚<EFBFBD>Case Studies嚗?*
**7\. 最佳案例研究（Case Studies）**
为了说明“最佳应用”，我们分析三种突出的二次开发方法。
銝箔<EFBFBD>霂湔<EFBFBD><EFBFBD>𨀣<EFBFBD>雿喳<EFBFBD><EFBFBD>兩<EFBFBD>嘅<EFBFBD><EFBFBD>睲賑<EFBFBD><EFBFBD><EFBFBD>銝厩<EFBFBD>蝒<EFBFBD>枂<EFBFBD><EFBFBD><EFBFBD>甈∪<EFBFBD><EFBFBD>烐䲮瘜𨰻<EFBFBD>?
### **7.1 案例一：Shazam（UI与前端改造）**
* **<EFBFBD>格<EFBFBD>嚗?* 銝箄<E98A9D><E7AE84>亙<EFBFBD>撱箄䌊摰帋<E691B0>撣<EFBFBD><E692A3>嚗<EFBFBD><E59A97>摮埈挾<E59F88><E68CBE><EFBFBD>銝箇畆<E7AE87>菜<EFBFBD><E88F9C>墧<EFBFBD><E5A2A7><EFBFBD><EFBFBD>閫㗇聢撘譌<E69298>?
* **<EFBFBD>箏<EFBFBD>嚗?* Shazam<EFBFBD>臭<EFBFBD>銝芸<EFBFBD><EFBFBD>冽芋<EFBFBD>梹<EFBFBD>摰<EFBFBD>釣<EFBFBD>仔avaScript/CSS<53><53><EFBFBD>閫<EFBFBD><E996AB><EFBFBD>讛膩<E8AE9B>扳<EFBFBD><E689B3>砍<EFBFBD>畾萎葉<E8908E><E89189>鸌摰尠<E691B0>侻hazam<61>脲<EFBFBD>蝑橘<E89D91><E6A998>嗅<EFBFBD><E59785>齿鰵<E9BDBF>鍦<EFBFBD><E98DA6>唳旿敶訫<E695B6>銵典<E98AB5><E585B8><EFBFBD>TML DOM<EFBFBD>?
* **瘣𧼮<EFBFBD>嚗?* 餈坔<E9A488>蝷箔<E89DB7>EM憒<4D><E68692><EFBFBD>其<EFBFBD><E585B6>湔㺿<E6B994>滚𦛚<E6BB9A>函垢<E587BD>唳旿蝏𤘪<E89D8F><F0A498AA><EFBFBD><EFBFBD><EFBFBD>萎<EFBFBD>嚗䔶<E59A97>*摰Ｘ<E691B0>蝡?敶餃<E695B6><E9A483>孵<EFBFBD><E5ADB5>冽<EFBFBD>雿㯄<E99BBF>1<EFBFBD>?
* **目标：** 为调查创建自定义布局，将字段分组为矩阵或非标准视觉格式。
* **机制：** Shazam是一个外部模块，它注入JavaScript/CSS。它解析描述性文本字段中的特定“Shazam”标签，然后重新排列数据录入表单的HTML DOM。
* **洞察：** 这展示了EM如何在不更改服务器端数据结构的情况下，从*客户端*彻底改变用户体验1。
### **7.2 案例二：Auto-Schedule（工作流自动化）**
* **<EFBFBD>格<EFBFBD>嚗?* <20>箔<EFBFBD><E7AE94>箇瑪<E7AE87>交<EFBFBD>嚗<EFBFBD><E59A97>憒<EFBFBD><E68692><EFBFBD>舀𠯫<E88880><F0A0AFAB><EFBFBD><EFBFBD>芸𢆡<E88AB8><F0A286A1><EFBFBD>蝥萄<E89DA5>鈭衤辣<E8A1A4><E8BEA3>𧒄<EFBFBD>渲”<E6B8B2>?
* **<EFBFBD>箏<EFBFBD>嚗?* 雿輻鍂redcap\_save\_record<EFBFBD>拙<EFBFBD><EFBFBD><EFBFBD><EFBFBD>靽嘥<EFBFBD><EFBFBD>𦨴urgery\_date<EFBFBD>嘥<EFBFBD>畾菜𧒄嚗峕芋<EFBFBD>𡑒恣蝞埈𧊋<EFBFBD>交𠯫<EFBFBD><EFBFBD><EFBFBD>+30憭抬<E686AD>+60憭抬<E686AD>撟嗅‵<E59785><E280B5>★<EFBFBD>格𠯫<E6A0BC><F0A0AFAB><EFBFBD>?
* **瘣𧼮<EFBFBD>嚗?* 餈蹱𤜯隞<F0A49CAF><E99A9E>鈭箏極霈∠<E99C88>嚗<EFBFBD><E59A97>撠睲<E692A0><E79DB2>讛<EFBFBD><E8AE9B>条<EFBFBD><E69DA1>躰秤嚗<E7A7A4><E59A97>蝷箔<E89DB7><E7AE94>𡒊垢<F0A1928A>拙<EFBFBD><E68B99>刻<EFBFBD><E588BB>交<EFBFBD><E4BAA4><EFBFBD>葉<EFBFBD><E89189><EFBFBD><EFBFBD>?5<>?
* **目标：** 基于基线日期（例如手术日期）自动生成纵向事件的时间表。
* **机制：** 使用redcap\_save\_record钩子。当保存“surgery\_date”字段时，模块计算未来日期（+30天，+60天）并填充项目日历。
* **洞察：** 这替代了人工计算，减少了协调员的错误，展示了后端钩子在运营效率中的作用45。
### **7.3 案例三：Cross-Project Piping（跨项目数据互通）**
* **<EFBFBD>格<EFBFBD>嚗?* 撠<>犖<EFBFBD><E78A96><EFBFBD>霈⊥㺭<E28AA5>桐<EFBFBD>銝剖亢<E58996>𨀣釣<F0A880A3>𢞖<EFBFBD>嗪★<E597AA>格<EFBFBD><E6A0BC>硋<EFBFBD><E7A18B>孵<EFBFBD><E5ADB5><EFBFBD><EFBFBD>𦦵<EFBFBD>蝛嗯<E89D9B>嗪★<E597AA>桐葉<E6A190>?
* **<EFBFBD>箏<EFBFBD>嚗?* 銝<>銝枕M嚗<4D><E59A97><EFBFBD>亥砭皞鞾★<E99EBE>桃<EFBFBD><E6A183>唳旿摨橒<E691A8>雿輻鍂REDCap::getData嚗匧僎撠<E5838E>㺭<EFBFBD>格<EFBFBD><E6A0BC>亙<EFBFBD><E4BA99>漤★<E6BCA4>株”<E6A0AA>𨰻<EFBFBD>?
* **<EFBFBD>𣂼<EFBFBD><EFBFBD>喲睸嚗?* 摰<>蝙<EFBFBD>兩<EFBFBD>𡏭圻<F0A18FAD>穃<EFBFBD>畾菊<E795BE>腈<EFBFBD><E88588>蘨<EFBFBD>匧銁靽格㺿<E6A0BC>孵<EFBFBD>摮埈挾<E59F88>嗆<EFBFBD>隡朞<E99AA1>銵<EFBFBD><E98AB5><EFBFBD>塚<EFBFBD><E5A19A>脫迫銝齿鱏閬<E9B18F><E996AC>47<34>?
* **目标：** 将人口统计数据从中央“注册”项目拉取到特定的“研究”项目中。
* **机制：** 一个EM，它查询源项目的数据库（使用REDCap::getData）并将数据插入当前项目表单。
* **成功关键：** 它使用“触发字段”。只有在修改特定字段时才会进行复制，防止不断覆盖47。
## ---
**8\. 避坑指南：常见问题与解决方案**
鈭峕活撘<EFBFBD><EFBFBD>穃<EFBFBD>皛⊿<EFBFBD><EFBFBD>押<EFBFBD><EFBFBD>誑銝𧢲糓<EFBFBD>𠉛<EFBFBD>銝剜𥁒<EFBFBD>羓<EFBFBD><EFBFBD><EFBFBD>撣貉<EFBFBD><EFBFBD>桅<EFBFBD>嚗?
### **8.1 <20>𨅯<EFBFBD>蝥扯稲甇領<E79487>嘅<EFBFBD>The Upgrade Death嚗?*
二次开发充满风险。以下是联盟中报告的最常见问题：
### **8.1 “升级致死”（The Upgrade Death）**
* **场景：** 开发者使用非标准文件路径编写插件，或依赖于REDCap内部（私有）核心函数。
* **后果：** 当REDCap更新时，函数名称更改或路径移动，导致插件崩溃。
* **避坑指南：** 严格坚持使用外部模块框架，并仅调用REDCap::类方法，这些方法为了向后兼容性而受到维护。
* **<2A>箸艶嚗?* 撘<><E69298>𤏸<EFBFBD><F0A48FB8>蝙<EFBFBD>券<EFBFBD><E588B8><EFBFBD><EFBFBD><EFBFBD><EFBFBD>辣頝臬<E9A09D>蝻硋<E89DBB><E7A18B>雴辣嚗峕<E59A97>靘肽<E99D98>鈭竃EDCap<61><70><EFBFBD>嚗<EFBFBD><E59A97><EFBFBD>㚁<EFBFBD><E39A81>詨<EFBFBD><E8A9A8>賣㺭<E8B3A3>?
* **<2A>擧<EFBFBD>嚗?* 敶𣫮EDCap<61>湔鰵<E6B994>塚<EFBFBD><E5A19A>賣㺭<E8B3A3>滨妍<E6BBA8>湔㺿<E6B994>𤥁楝敺<E6A59D>宏<EFBFBD>剁<EFBFBD>撖潸稲<E6BDB8>雴辣撏拇<E6928F><E68B87>?
* **<2A>踹<EFBFBD><E8B8B9><EFBFBD><EFBFBD>嚗?* 銝交聢<E4BAA4>𡁏<EFBFBD>雿輻鍂憭㚚<E686AD>璅∪<E79285>獢<EFBFBD>沲嚗<E6B2B2>僎隞<E5838E><E99A9E><EFBFBD>沖EDCap::蝐餅䲮瘜𤏪<E7989C>餈嗘<E9A488><E59798>寞<EFBFBD>銝箔<E98A9D><E7AE94>穃<EFBFBD><E7A983>澆捆<E6BE86>扯<EFBFBD><E689AF><EFBFBD><EFBFBD>啁輕<E59581>扎<EFBFBD>?
### **8.2 redcap\_data的性能瓶颈**
* **<EFBFBD>箸艶嚗?* 璅∪<E79285><E288AA>𦦵揣<F0A6A6B5>𨀣<EFBFBD><F0A880A3>匧僑樴?\> 50<35><30>扇敶𨰝<E695B6>腈<EFBFBD>?
* **<EFBFBD>琿𩐠嚗?* <20>其<EFBFBD>銝芣𥅾<E88AA3>?0銝<30>辺霈啣<E99C88><E595A3><EFBFBD>★<EFBFBD>桐葉嚗屸<E59A97>朞<EFBFBD>SELECT \* FROM redcap\_data WHERE value \> 50<EFBFBD>扯<EFBFBD>甇斗<EFBFBD>雿靝<EFBFBD>撘箏<EFBFBD>撖寡”餈𥡝<EFBFBD><EFBFBD>刻”<EFBFBD>急<EFBFBD>嚗<EFBFBD><EFBFBD>銝箄砲銵典<EFBFBD><EFBFBD>?<3F><><EFBFBD>?憿寧𤌍<E5AFA7><F0A48C8D>㺭<EFBFBD>殷<EFBFBD><E6AEB7>?
* **閫<EFBFBD><EFBFBD><EFBFBD>寞<EFBFBD>嚗?* 憪讠<E686AA><E8AEA0>沒QL<51>亥砭銝剖<E98A9D><E58996>厚roject\_id雿靝蛹擐𤥁<E69390>餈<EFBFBD>誘<EFBFBD>∩辣<E288A9><E8BEA3>⏚<EFBFBD>沖EDCap::getData()<29><><EFBFBD>皛日<E79A9B>餉<EFBFBD>嚗峕<E59A97><E5B395><EFBFBD><EFBFBD><EFBFBD>𣈯<EFBFBD>閬<EFBFBD><E996AC>憪喹QL嚗𣬚＆靽脲<E99DBD><E884B2><EFBFBD>𧑐<EFBFBD>拍鍂鈭<E98D82>roject\_id<EFBFBD>靕ield\_name銝羓<EFBFBD>蝝Ｗ<EFBFBD><EFBFBD>?
### **8.3 靚<>䰻憿菟𢒰甇餃儐<E9A483>荔<EFBFBD>Survey Loop嚗?*
* **场景：** 模块搜索“所有年龄 \> 50的记录”。
* **陷阱：** 在一个拥有10万条记录的项目中，通过SELECT \* FROM redcap\_data WHERE value \> 50执行此操作会强制对表进行全表扫描（因为该表包含*所有*项目的数据）。
* **解决方案：** 始终在SQL查询中包含project\_id作为首要过滤条件。利用REDCap::getData()的过滤逻辑，或者如果需要原始SQL，确保有效地利用了project\_id和field\_name上的索引。
* **<2A>箸艶嚗?* 雿輻鍂redcap\_survey\_page\_top<6F>拙<EFBFBD><E68B99>冽說頞單辺隞嗆𧒄<E59786>滚<EFBFBD><E6BB9A>𤑳鍂<F0A491B3>瑯<EFBFBD>?
* **<2A>琿𩐠嚗?* 憒<><E68692><EFBFBD>滚<EFBFBD><E6BB9A>煾<EFBFBD>餉<EFBFBD><E9A489>厩撩<E58EA9>瘀<EFBFBD>靘见<E99D98>嚗屸<E59A97>摰𡁜<E691B0><F0A1819C>∩辣<E288A9>函𤌍<E587BD><F0A48C8D>△<EFBFBD>Ｖ<EFBFBD>銋煺蛹<E785BA><E89BB9><EFBFBD>嚗𣬚鍂<F0A3AC9A>瑕<EFBFBD>鋡怠撕<E680A0>𧼮<EFBFBD>銝<EFBFBD>憿菟𢒰嚗<F0A292B0>紡<EFBFBD>湔<EFBFBD>閫<EFBFBD>膥<EFBFBD><E886A5>絲<EFBFBD>硋援皞<E68FB4><E79A9E>?
* **閫<EFBFBD><EFBFBD><EFBFBD>寞<EFBFBD>嚗?* <20>冽<EFBFBD>銵屸<E98AB5>摰𡁜<E691B0>銋见<E98A8B>嚗峕<E59A97><E5B395>亙<EFBFBD><E4BA99>䔛RL<52>臬炏撌脩<E6928C><E884A9>舐𤌍<E88890>䱗RL<52>?
### **8.4 蝘餃𢆡<E9A483>峕郊銝剔<E98A9D><E58994>𨅯迨<F0A885AF>踵㺭<E8B8B5>栽<EFBFBD>?*
### **8.3 调查页面死循环（Survey Loop）**
* **场景：** 使用redcap\_survey\_page\_top钩子在满足条件时重定向用户。
* **陷阱：** 如果重定向逻辑有缺陷（例如，重定向条件在目标页面上也为真），用户将被弹回同一页面，导致浏览器挂起或崩溃。
* **解决方案：** 在执行重定向之前，检查当前URL是否已经是目标URL。
### **8.4 移动同步中的“孤儿数据”**
* **场景：** 当移动设备检出项目时，管理员更改了项目结构（例如，删除了一个字段）。
* **后果：** 移动用户无法将数据同步回来，因为服务器上不再存在该字段。数据被困在设备上。
* **规则：** **绝对不要**在项目处于“生产”状态且有活跃移动用户时修改项目设计30。
* **<2A>箸艶嚗?* 敶梶宏<E6A2B6>刻挽憭<E68CBD><E686AD><EFBFBD>粹★<E7B2B9>格𧒄嚗𣬚恣<F0A3AC9A><E681A3><EFBFBD><EFBFBD>湔㺿鈭<E3BABF>★<EFBFBD>桃<EFBFBD><E6A183><EFBFBD><EFBFBD>靘见<E99D98>嚗<EFBFBD><E59A97><EFBFBD>支<EFBFBD>銝<EFBFBD>銝芸<E98A9D>畾蛛<E795BE><E89B9B>?
* **<2A>擧<EFBFBD>嚗?* 蝘餃𢆡<E9A483>冽<EFBFBD><E586BD>䭾<EFBFBD>撠<EFBFBD>㺭<EFBFBD>桀<EFBFBD>甇亙<E79487><E4BA99>伐<EFBFBD><E4BC90>牐蛹<E78990>滚𦛚<E6BB9A>其<EFBFBD>銝滚<E98A9D>摮睃銁霂亙<E99C82>畾萸<E795BE><E890B8>㺭<EFBFBD>株◤<E6A0AA>啣銁霈曉<E99C88>銝𨳍<E98A9D>?
* **閫<><E996AB>嚗?* **蝏嘥笆銝滩<E98A9D>**<EFBFBD>券★<EFBFBD>桀<EFBFBD>鈭𢛶<EFBFBD>𦦵<EFBFBD>鈭把<EFBFBD>萘𠶖<EFBFBD><EFBFBD><EFBFBD><EFBFBD>㗇暑頝<EFBFBD>宏<EFBFBD>函鍂<EFBFBD>瑟𧒄靽格㺿憿寧𤌍霈曇恣30<EFBFBD>?
## ---
**9\. 结论**
REDCap<EFBFBD><EFBFBD><EFBFBD>甈∪<EFBFBD><EFBFBD>穃<EFBFBD>銝<EFBFBD>銝芾◤<EFBFBD>函<EFBFBD><EFBFBD>唳旿摮睃<EFBFBD>摨栞蓮<EFBFBD>䀝蛹銝<EFBFBD>銝芯蜓<EFBFBD>函<EFBFBD><EFBFBD>𠉛弦<EFBFBD>滢<EFBFBD>蝟餌<EFBFBD><EFBFBD><EFBFBD><EFBFBD>銝湔𧒄<EFBFBD>雴辣<EFBFBD>𤑳<EFBFBD><EFBFBD><EFBFBD><EFBFBD>憭㚚<EFBFBD>璅∪<EFBFBD>獢<EFBFBD>沲<EFBFBD><EFBFBD><EFBFBD>蝘颱誨銵其<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>頂蝏毺<EFBFBD><EFBFBD>鞟<EFBFBD>嚗䔶<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>鈭<EFBFBD><EFBFBD><EFBFBD>冽<EFBFBD>扼<EFBFBD><EFBFBD>虾蝏湔擪<EFBFBD>批<EFBFBD><EFBFBD>曹澈<EFBFBD>賢<EFBFBD><EFBFBD>?
撖嫣<EFBFBD>撘<EFBFBD><EFBFBD>𤏸<EFBFBD><EFBFBD><EFBFBD>諹<EFBFBD>嚗峕<EFBFBD><EFBFBD>毺<EFBFBD>頝臬<EFBFBD><EFBFBD>其<EFBFBD>銝交聢<EFBFBD>萄<EFBFBD>獢<EFBFBD>沲閫<EFBFBD><EFBFBD>嚗帋蝙<EFBFBD>冽𡂝鞊⊥䰻霂Ｘ䲮瘜閖俈甇㏎QL瘜典<EFBFBD>嚗峕<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>箔誑<EFBFBD>脫迫XSS嚗<EFBFBD>僎<EFBFBD>拍鍂撣行<EFBFBD><EFBFBD>𣳇<EFBFBD>敺芰㴓靽脲擪<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>偬摮𣂼<EFBFBD>redcap\_save\_record<72>?
<EFBFBD>函宏<EFBFBD>券<EFBFBD><EFBFBD><EFBFBD><EFBFBD>MyCap<EFBFBD>愢obile App<70><70><EFBFBD><EFBFBD>𣂼<EFBFBD>REDCap<61><70>圻閫鍦辣隡詨<E99AA1>鈭<EFBFBD><E988AD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>餈𦦵<E9A488>摰𧼮𧑐<F0A7BCAE>啣㦤<E595A3><E3A6A4><EFBFBD><EFBFBD>䕘<EFBFBD>餈嗵<E9A488>餈墧𦻖<E5A2A7>扯<EFBFBD>瘙<EFBFBD>銁API隞斤<E99A9E>蝞∠<E89D9E><E288A0>屸★<E5B1B8>桃<EFBFBD><E6A183>祆綉<E7A586>嗆䲮<E59786>Ｘ<EFBFBD>銝交聢<E4BAA4><E881A2><EFBFBD>雿𦦵漯敺页<E695BA>隞仿俈甇Ｘ㺭<EFBCB8>桐腺憭晞<E686AD>?
<EFBFBD>朞<EFBFBD><EFBFBD>拍鍂餈嗘<EFBFBD>擃条漣<EFBFBD>蠘<EFBFBD><EFBFBD>婙<EFBFBD>𥪜<EFBFBD><EFBFBD>嗅<EFBFBD><EFBFBD>滩<EFBFBD><EFBFBD><EFBFBD><EFBFBD>隞<EFBFBD><EFBFBD><EFBFBD><EFBFBD>沲<EFBFBD><EFBFBD>器<EFBFBD>𢞖<EFBFBD>婙<EFBFBD>娍㦤<EFBFBD><EFBFBD>虾隞仿<EFBFBD>蝵脫𠳿摰匧<EFBFBD><EFBFBD><EFBFBD>虾<EFBFBD>拙<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>䌊<EFBFBD>典<EFBFBD><EFBFBD>𣬚鍂<EFBFBD>瑕<EFBFBD>憟賜<EFBFBD><EFBFBD>𠉛弦<EFBFBD>臬<EFBFBD><EFBFBD>?
REDCap的二次开发将一个被动的数据存储库转变为一个主动的研究操作系统。从临时插件向结构化外部模块框架的迁移代表了生态系统的成熟，优先考虑了安全性、可维护性和共享能力。
对于开发者而言，成功的路径在于严格遵守框架规则：使用抽象查询方法防止SQL注入，清理输出以防止XSS，并利用带有无限循环保护的标准钩子如redcap\_save\_record。
在移动领域，MyCap和Mobile App的集成将REDCap的触角延伸到了患者的口袋和偏远的实地现场。然而，这种连接性要求在API令牌管理和项目版本控制方面有严格的操作纪律，以防止数据丢失。
通过利用这些高级功能——同时尊重联盟源代码的架构边界——机构可以部署既安全又可扩展的复杂、自动化和用户友好的研究环境。
## ---
**10\. 技术附录：核心源代码参考库**
@@ -358,19 +420,19 @@ public function redcap\_save\_record($project\_id, $record, $instrument, $event\
// 确保我们在正确的项目上下文中
if ($project\_id\!= $this\-\>getProjectSetting('target\_project')) return;
// <EFBFBD>㰘蝸<EFBFBD>唳旿隞交<EFBFBD><EFBFBD>交辺隞?
// 加载数据以检查条件
$data \= \\REDCap::getData($project\_id, 'array', $record);
// 璉<EFBFBD><EFBFBD>?status'摮埈挾<EFBFBD>臬炏銝?complete' (2)
// 瘜冽<EFBFBD>嚗帋<EFBFBD>隞嗥<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>?
// 检查'status'字段是否为'complete' (2)
// 注意：事件结构处理
if ($data\[$record\]\[$event\_id\]\['status'\] \== '2') {
// 记录日志
$this\-\>log("霈啣<EFBFBD> $record 摰峕<EFBFBD><EFBFBD>嗆<EFBFBD><EFBFBD><EFBFBD><EFBFBD>乓<EFBFBD>?, \[
$this\-\>log("记录 $record 完成状态检查。", \[
'record' \=\> $record,
'status' \=\> 'complete'
\]);
// <EFBFBD>扯<EFBFBD><EFBFBD>芸<EFBFBD>銋厰<EFBFBD>餉<EFBFBD>嚗<EFBFBD><EFBFBD>憒<EFBFBD><EFBFBD>靚<EFBFBD>鍂憭㚚<EFBFBD>API嚗?
// 执行自定义逻辑（例如，调用外部API）
$this\-\>sendToExternalRegistry($record, $data);
}
}
@@ -379,10 +441,10 @@ public function redcap\_save\_record($project\_id, $record, $instrument, $event\
PHP
// <EFBFBD>躰秤<EFBFBD><EFBFBD><EFBFBD>瘜𤏪<EFBFBD>SQL瘜典<EFBFBD>憌𡡞埯嚗?
// 错误的写法（SQL注入风险）
// $sql \= "select value from redcap\_data where record \= '$record\_id'";
// 甇<EFBFBD>＆<EFBFBD><EFBFBD><EFBFBD>瘜?
// 正确的写法
$sql \= "select value from redcap\_data where project\_id \=? and record \=? and field\_name \=?";
$result \= $this\-\>query($sql, \[$project\_id, $record\_id, 'target\_field'\]);
@@ -392,13 +454,13 @@ while($row \= $result\-\>fetch\_assoc()){
//...处理逻辑
}
### **A.3 API Python 鈭支<EFBFBD>嚗<EFBFBD><EFBFBD><EFBFBD><EFBFBD>之<EFBFBD>寥<EFBFBD><EFBFBD>唳旿嚗?*
### **A.3 API Python 交互（处理大批量数据）**
Python
def export\_large\_project(api\_url, token):
"""
<EFBFBD><EFBFBD>鸌撖澆枂憭批<EFBFBD>憿寧𤌍<EFBFBD>唳旿隞仿<EFBFBD><EFBFBD>滩<EFBFBD><EFBFBD>?
分批导出大型项目数据以避免超时
"""
\# 1\. 首先获取所有记录ID
payload \= {
@@ -410,13 +472,13 @@ def export\_large\_project(api\_url, token):
r \= requests.post(api\_url, data=payload)
records \= \[x\['record\_id'\] for x in r.json()\]
\# 2\. <EFBFBD><EFBFBD><EFBFBD>憭<EFBFBD><EFBFBD> (靘见<E99D98>瘥誩<E798A5>100<EFBFBD>?
\# 2\. 分块处理 (例如每块100条)
chunk\_size \= 100
all\_data \=
for i in range(0, len(records), chunk\_size):
chunk \= records\[i:i \+ chunk\_size\]
\# <EFBFBD><EFBFBD>遣霂瑟<EFBFBD><EFBFBD>孵<EFBFBD><EFBFBD><EFBFBD>扇敶?
\# 构建请求特定的记录
batch\_payload \= {
'token': token,
'content': 'record',
@@ -429,57 +491,57 @@ def export\_large\_project(api\_url, token):
r\_batch \= requests.post(api\_url, data=batch\_payload)
all\_data.extend(r\_batch.json())
print(f"撌脣紡<EFBFBD>?{len(all\_data)} <EFBFBD>∟扇敶?..")
print(f"已导出 {len(all\_data)} 条记录...")
return pd.DataFrame(all\_data)
#### **撘閧鍂<EFBFBD><EFBFBD><EFBFBD>雿?*
#### **引用的著作**
1. Supporting rapid innovation in research data capture and management: the REDCap external module framework \- PubMed Central, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://pmc.ncbi.nlm.nih.gov/articles/PMC12202089/](https://pmc.ncbi.nlm.nih.gov/articles/PMC12202089/)
2. The Process of Installing REDCap, a Web Based Database Supporting Biomedical Research: The First Year \- PubMed Central, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://pmc.ncbi.nlm.nih.gov/articles/PMC4287671/](https://pmc.ncbi.nlm.nih.gov/articles/PMC4287671/)
3. Join & Get REDCap, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://projectredcap.org/join/](https://projectredcap.org/join/)
4. How to Acquire a REDCap License \- NACC Docs, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://docs.naccdata.org/edc/data-capture-development/how-to-acquire-a-redcap-license](https://docs.naccdata.org/edc/data-capture-development/how-to-acquire-a-redcap-license)
5. 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://projectredcap.org/join/\#:\~:text=Although%20REDCap%20is%20available%20at,your%20organization%20must%20be%20executed.](https://projectredcap.org/join/#:~:text=Although%20REDCap%20is%20available%20at,your%20organization%20must%20be%20executed.)
6. FAQ \- REDCap, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://projectredcap.org/about/faq/](https://projectredcap.org/about/faq/)
7. Installation & Technical Requirements \- REDCap, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://projectredcap.org/software/requirements/](https://projectredcap.org/software/requirements/)
8. REDCap Technical Overview Introduction REDCap Infrastructure: Best Practices and Dependencies, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://projectredcap.org/wp-content/resources/REDCapTechnicalOverview.pdf](https://projectredcap.org/wp-content/resources/REDCapTechnicalOverview.pdf)
9. REDCap External Module Development for REDCap Admins and Developers, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://ctsit.github.io/redcap\_external\_module\_development\_guide/guide\_for\_admins\_and\_devs.html](https://ctsit.github.io/redcap_external_module_development_guide/guide_for_admins_and_devs.html)
10. REDCap 'Hello World' external module development guide \- Ayesh Alshukri, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://ayeshalshukri.co.uk/category/guides/redcap-external-module-development-guide-hello-world/](https://ayeshalshukri.co.uk/category/guides/redcap-external-module-development-guide-hello-world/)
11. REDCap External Module Development for Developers \- GitHub Pages, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://ctsit.github.io/redcap\_external\_module\_development\_guide/guide\_for\_devs.html](https://ctsit.github.io/redcap_external_module_development_guide/guide_for_devs.html)
12. REDCap External Module Development Beginner's Guide \- GitHub, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://github.com/vanderbilt-redcap/external-module-framework-docs/blob/main/guide.md](https://github.com/vanderbilt-redcap/external-module-framework-docs/blob/main/guide.md)
13. Shazam.php \- GitHub, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://github.com/susom/redcap-em-shazam/blob/master/Shazam.php](https://github.com/susom/redcap-em-shazam/blob/master/Shazam.php)
14. redcap-copy-data-on-save/CopyDataOnSave.php at main 繚 lsgs ..., 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://github.com/lsgs/redcap-copy-data-on-save/blob/main/CopyDataOnSave.php](https://github.com/lsgs/redcap-copy-data-on-save/blob/main/CopyDataOnSave.php)
15. README.md 繚 main 繚 BRIC / Epic Hl7 Integration 繚 GitLab, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://gitlab.msu.edu/bric/epic-hl7-integration/-/blob/main/README.md](https://gitlab.msu.edu/bric/epic-hl7-integration/-/blob/main/README.md)
16. REDCap-Changelog\_8.1.0.docx, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://www.bu.edu/ctsi/files/2016/02/REDCap-Changelog\_8.1.0.docx](https://www.bu.edu/ctsi/files/2016/02/REDCap-Changelog_8.1.0.docx)
17. vanderbilt-redcap/auto-record-generation: Module that allows for a new record to be generated in another project (or the same project) on a flagging field being saved. Allows for data fields to be transferred to the new record as well. \- GitHub, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://github.com/vanderbilt-redcap/auto-record-generation](https://github.com/vanderbilt-redcap/auto-record-generation)
18. 2018 REDCapCon Poster Competition, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://projectredcap.org/wp-content/uploads/2018/08/2018-REDCapCon-Posters.pdf](https://projectredcap.org/wp-content/uploads/2018/08/2018-REDCapCon-Posters.pdf)
19. vanderbilt-redcap/external-module-framework-docs \- GitHub, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://github.com/vanderbilt-redcap/external-module-framework-docs](https://github.com/vanderbilt-redcap/external-module-framework-docs)
20. CVE-2017-7351: REDCap 7.0.0 \- 7.0.10 SQL Injection \- LRQA, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://www.lrqa.com/en/cyber-labs/cve-2017-7351-redcap-7-0-0-7-0-10-sql-injection/](https://www.lrqa.com/en/cyber-labs/cve-2017-7351-redcap-7-0-0-7-0-10-sql-injection/)
21. ctsit/redcap\_webservices: REDCap external module that provides a way to expose SQL query results to the external world. \- GitHub, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://github.com/ctsit/redcap\_webservices](https://github.com/ctsit/redcap_webservices)
22. REDCap: Multiple Cross-Site Scripting (XSS) Vulnerabilities \- LevelBlue, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://levelblue.com/blogs/spiderlabs-blog/redcap-multiple-cross-site-scripting-xss-vulnerabilities](https://levelblue.com/blogs/spiderlabs-blog/redcap-multiple-cross-site-scripting-xss-vulnerabilities)
23. Yale External Module (EM): Checklist for EM Development \- REDCap@Yale, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://portal.redcap.yale.edu/media/91/download?inline](https://portal.redcap.yale.edu/media/91/download?inline)
24. Article \- REDCap Security Information \- TeamDynamix, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://ecu.teamdynamix.com/TDClient/1409/Portal/KB/ArticleDet?ID=67288](https://ecu.teamdynamix.com/TDClient/1409/Portal/KB/ArticleDet?ID=67288)
25. Mobile App Guide \- CENTER FOR RESEARCH INFORMATICS, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://cri.uchicago.edu/wp-content/uploads/2015/12/REDCap-Mobile-App-Guide.pdf](https://cri.uchicago.edu/wp-content/uploads/2015/12/REDCap-Mobile-App-Guide.pdf)
26. Mobile App User's Guide, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://www.ctsi.ufl.edu/wordpress/files/2023/12/new-REDCap-Mobile-App-Guide-1.pdf](https://www.ctsi.ufl.edu/wordpress/files/2023/12/new-REDCap-Mobile-App-Guide-1.pdf)
27. CFRI DM REDCap Mobile App Manual, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://projectredcap.org/wp-content/uploads/2016/08/CFRI-DM-REDCap-Mobile-App-Manual.pdf](https://projectredcap.org/wp-content/uploads/2016/08/CFRI-DM-REDCap-Mobile-App-Manual.pdf)
28. Records \- PyCap \- REDCap-Tools, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[http://redcap-tools.github.io/PyCap/api\_reference/records/](http://redcap-tools.github.io/PyCap/api_reference/records/)
29. API-Best-Practices-and-Guide-1.docx \- UConn Health, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://health.uconn.edu/clinical-research-center/wp-content/uploads/sites/50/2024/02/API-Best-Practices-and-Guide-1.docx](https://health.uconn.edu/clinical-research-center/wp-content/uploads/sites/50/2024/02/API-Best-Practices-and-Guide-1.docx)
30. REDCap: Updating Mobile App Projects \- SMPH Enterprise Applications \- Research KB, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://kb.wisc.edu/smph/informatics/page.php?id=152765](https://kb.wisc.edu/smph/informatics/page.php?id=152765)
31. In-Depth Guide | REDCap, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://projectredcap.org/wp-content/uploads/2019/07/In-Depth-Guide2019.pdf](https://projectredcap.org/wp-content/uploads/2019/07/In-Depth-Guide2019.pdf)
32. Services | REDCap \- The George Washington University, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://redcap.smhs.gwu.edu/services](https://redcap.smhs.gwu.edu/services)
33. MyCap Resources, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://projectmycap.org/mycap-resources/](https://projectmycap.org/mycap-resources/)
34. MyCap <EFBFBD>?Mobilizing the participant voice, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://projectmycap.org/](https://projectmycap.org/)
35. MyCap: a flexible and configurable platform for mobilizing the participant voice \- PMC, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://pmc.ncbi.nlm.nih.gov/articles/PMC9165428/](https://pmc.ncbi.nlm.nih.gov/articles/PMC9165428/)
36. MyCap \- REDCap Support \- University of Alberta, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://help.redcap.ualberta.ca/help-and-faq/mycap](https://help.redcap.ualberta.ca/help-and-faq/mycap)
37. REDCap: MyCap \- Active Task List \- SMPH Enterprise Applications \- Research KB, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://kb.wisc.edu/smph/informatics/133154](https://kb.wisc.edu/smph/informatics/133154)
38. REDCap External Module <EFBFBD>?MyCap, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://projectmycap.org/tag/redcap-external-module/](https://projectmycap.org/tag/redcap-external-module/)
39. MYCAP HELP Table of Contents \- REDCap, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://redcap.med.upenn.edu/redcap\_v14.3.13/Resources/misc/mycap\_help.pdf](https://redcap.med.upenn.edu/redcap_v14.3.13/Resources/misc/mycap_help.pdf)
40. How to use exportRecordsTyped function from the redcapAPI package to import the data without factors? \- Stack Overflow, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://stackoverflow.com/questions/76815004/how-to-use-exportrecordstyped-function-from-the-redcapapi-package-to-import-the](https://stackoverflow.com/questions/76815004/how-to-use-exportrecordstyped-function-from-the-redcapapi-package-to-import-the)
41. JSONDecodeError 繚 Issue \#265 繚 redcap-tools/PyCap \- GitHub, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://github.com/redcap-tools/PyCap/issues/265](https://github.com/redcap-tools/PyCap/issues/265)
42. Importing data into REDCap <EFBFBD>?Backup options <EFBFBD>?API Basics \- ITHS, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://www.iths.org/wp-content/uploads/REDCap-Importing-Exporting-302.pdf](https://www.iths.org/wp-content/uploads/REDCap-Importing-Exporting-302.pdf)
43. BCCHR-IT/data-entry-trigger-builder: An External Module that provides an interface to create a DET between a source and destination project. \- GitHub, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://github.com/BCCHR-IT/data-entry-trigger-builder](https://github.com/BCCHR-IT/data-entry-trigger-builder)
44. RedCap API export \- Python Discussions, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://discuss.python.org/t/redcap-api-export/32252](https://discuss.python.org/t/redcap-api-export/32252)
45. REDCap External Module for automated generation of record event schedules. \- GitHub, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://github.com/lsgs/redcap-autoschedule](https://github.com/lsgs/redcap-autoschedule)
46. redcap-autoschedule/README.md at master \- GitHub, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://github.com/lsgs/redcap-autoschedule/blob/master/README.md](https://github.com/lsgs/redcap-autoschedule/blob/master/README.md)
47. redcap-repo 繚 GitHub Topics, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://github.com/topics/redcap-repo](https://github.com/topics/redcap-repo)
48. A Comprehensive Guide to REDCap | UNMC, 霈輸䔮<EFBFBD>園𡢿銝?<3F><><EFBFBD><EFBFBD>?29, 2025嚗?[https://www.unmc.edu/vcr/\_documents/unmc\_redcap\_usage.pdf](https://www.unmc.edu/vcr/_documents/unmc_redcap_usage.pdf)
1. Supporting rapid innovation in research data capture and management: the REDCap external module framework \- PubMed Central, 访问时间为 十二月 29, 2025， [https://pmc.ncbi.nlm.nih.gov/articles/PMC12202089/](https://pmc.ncbi.nlm.nih.gov/articles/PMC12202089/)
2. The Process of Installing REDCap, a Web Based Database Supporting Biomedical Research: The First Year \- PubMed Central, 访问时间为 十二月 29, 2025， [https://pmc.ncbi.nlm.nih.gov/articles/PMC4287671/](https://pmc.ncbi.nlm.nih.gov/articles/PMC4287671/)
3. Join & Get REDCap, 访问时间为 十二月 29, 2025， [https://projectredcap.org/join/](https://projectredcap.org/join/)
4. How to Acquire a REDCap License \- NACC Docs, 访问时间为 十二月 29, 2025， [https://docs.naccdata.org/edc/data-capture-development/how-to-acquire-a-redcap-license](https://docs.naccdata.org/edc/data-capture-development/how-to-acquire-a-redcap-license)
5. 访问时间为 十二月 29, 2025， [https://projectredcap.org/join/\#:\~:text=Although%20REDCap%20is%20available%20at,your%20organization%20must%20be%20executed.](https://projectredcap.org/join/#:~:text=Although%20REDCap%20is%20available%20at,your%20organization%20must%20be%20executed.)
6. FAQ \- REDCap, 访问时间为 十二月 29, 2025， [https://projectredcap.org/about/faq/](https://projectredcap.org/about/faq/)
7. Installation & Technical Requirements \- REDCap, 访问时间为 十二月 29, 2025， [https://projectredcap.org/software/requirements/](https://projectredcap.org/software/requirements/)
8. REDCap Technical Overview Introduction REDCap Infrastructure: Best Practices and Dependencies, 访问时间为 十二月 29, 2025， [https://projectredcap.org/wp-content/resources/REDCapTechnicalOverview.pdf](https://projectredcap.org/wp-content/resources/REDCapTechnicalOverview.pdf)
9. REDCap External Module Development for REDCap Admins and Developers, 访问时间为 十二月 29, 2025， [https://ctsit.github.io/redcap\_external\_module\_development\_guide/guide\_for\_admins\_and\_devs.html](https://ctsit.github.io/redcap_external_module_development_guide/guide_for_admins_and_devs.html)
10. REDCap 'Hello World' external module development guide \- Ayesh Alshukri, 访问时间为 十二月 29, 2025， [https://ayeshalshukri.co.uk/category/guides/redcap-external-module-development-guide-hello-world/](https://ayeshalshukri.co.uk/category/guides/redcap-external-module-development-guide-hello-world/)
11. REDCap External Module Development for Developers \- GitHub Pages, 访问时间为 十二月 29, 2025， [https://ctsit.github.io/redcap\_external\_module\_development\_guide/guide\_for\_devs.html](https://ctsit.github.io/redcap_external_module_development_guide/guide_for_devs.html)
12. REDCap External Module Development Beginner's Guide \- GitHub, 访问时间为 十二月 29, 2025， [https://github.com/vanderbilt-redcap/external-module-framework-docs/blob/main/guide.md](https://github.com/vanderbilt-redcap/external-module-framework-docs/blob/main/guide.md)
13. Shazam.php \- GitHub, 访问时间为 十二月 29, 2025， [https://github.com/susom/redcap-em-shazam/blob/master/Shazam.php](https://github.com/susom/redcap-em-shazam/blob/master/Shazam.php)
14. redcap-copy-data-on-save/CopyDataOnSave.php at main · lsgs ..., 访问时间为 十二月 29, 2025， [https://github.com/lsgs/redcap-copy-data-on-save/blob/main/CopyDataOnSave.php](https://github.com/lsgs/redcap-copy-data-on-save/blob/main/CopyDataOnSave.php)
15. README.md · main · BRIC / Epic Hl7 Integration · GitLab, 访问时间为 十二月 29, 2025， [https://gitlab.msu.edu/bric/epic-hl7-integration/-/blob/main/README.md](https://gitlab.msu.edu/bric/epic-hl7-integration/-/blob/main/README.md)
16. REDCap-Changelog\_8.1.0.docx, 访问时间为 十二月 29, 2025， [https://www.bu.edu/ctsi/files/2016/02/REDCap-Changelog\_8.1.0.docx](https://www.bu.edu/ctsi/files/2016/02/REDCap-Changelog_8.1.0.docx)
17. vanderbilt-redcap/auto-record-generation: Module that allows for a new record to be generated in another project (or the same project) on a flagging field being saved. Allows for data fields to be transferred to the new record as well. \- GitHub, 访问时间为 十二月 29, 2025， [https://github.com/vanderbilt-redcap/auto-record-generation](https://github.com/vanderbilt-redcap/auto-record-generation)
18. 2018 REDCapCon Poster Competition, 访问时间为 十二月 29, 2025， [https://projectredcap.org/wp-content/uploads/2018/08/2018-REDCapCon-Posters.pdf](https://projectredcap.org/wp-content/uploads/2018/08/2018-REDCapCon-Posters.pdf)
19. vanderbilt-redcap/external-module-framework-docs \- GitHub, 访问时间为 十二月 29, 2025， [https://github.com/vanderbilt-redcap/external-module-framework-docs](https://github.com/vanderbilt-redcap/external-module-framework-docs)
20. CVE-2017-7351: REDCap 7.0.0 \- 7.0.10 SQL Injection \- LRQA, 访问时间为 十二月 29, 2025， [https://www.lrqa.com/en/cyber-labs/cve-2017-7351-redcap-7-0-0-7-0-10-sql-injection/](https://www.lrqa.com/en/cyber-labs/cve-2017-7351-redcap-7-0-0-7-0-10-sql-injection/)
21. ctsit/redcap\_webservices: REDCap external module that provides a way to expose SQL query results to the external world. \- GitHub, 访问时间为 十二月 29, 2025， [https://github.com/ctsit/redcap\_webservices](https://github.com/ctsit/redcap_webservices)
22. REDCap: Multiple Cross-Site Scripting (XSS) Vulnerabilities \- LevelBlue, 访问时间为 十二月 29, 2025， [https://levelblue.com/blogs/spiderlabs-blog/redcap-multiple-cross-site-scripting-xss-vulnerabilities](https://levelblue.com/blogs/spiderlabs-blog/redcap-multiple-cross-site-scripting-xss-vulnerabilities)
23. Yale External Module (EM): Checklist for EM Development \- REDCap@Yale, 访问时间为 十二月 29, 2025， [https://portal.redcap.yale.edu/media/91/download?inline](https://portal.redcap.yale.edu/media/91/download?inline)
24. Article \- REDCap Security Information \- TeamDynamix, 访问时间为 十二月 29, 2025， [https://ecu.teamdynamix.com/TDClient/1409/Portal/KB/ArticleDet?ID=67288](https://ecu.teamdynamix.com/TDClient/1409/Portal/KB/ArticleDet?ID=67288)
25. Mobile App Guide \- CENTER FOR RESEARCH INFORMATICS, 访问时间为 十二月 29, 2025， [https://cri.uchicago.edu/wp-content/uploads/2015/12/REDCap-Mobile-App-Guide.pdf](https://cri.uchicago.edu/wp-content/uploads/2015/12/REDCap-Mobile-App-Guide.pdf)
26. Mobile App User's Guide, 访问时间为 十二月 29, 2025， [https://www.ctsi.ufl.edu/wordpress/files/2023/12/new-REDCap-Mobile-App-Guide-1.pdf](https://www.ctsi.ufl.edu/wordpress/files/2023/12/new-REDCap-Mobile-App-Guide-1.pdf)
27. CFRI DM REDCap Mobile App Manual, 访问时间为 十二月 29, 2025， [https://projectredcap.org/wp-content/uploads/2016/08/CFRI-DM-REDCap-Mobile-App-Manual.pdf](https://projectredcap.org/wp-content/uploads/2016/08/CFRI-DM-REDCap-Mobile-App-Manual.pdf)
28. Records \- PyCap \- REDCap-Tools, 访问时间为 十二月 29, 2025， [http://redcap-tools.github.io/PyCap/api\_reference/records/](http://redcap-tools.github.io/PyCap/api_reference/records/)
29. API-Best-Practices-and-Guide-1.docx \- UConn Health, 访问时间为 十二月 29, 2025， [https://health.uconn.edu/clinical-research-center/wp-content/uploads/sites/50/2024/02/API-Best-Practices-and-Guide-1.docx](https://health.uconn.edu/clinical-research-center/wp-content/uploads/sites/50/2024/02/API-Best-Practices-and-Guide-1.docx)
30. REDCap: Updating Mobile App Projects \- SMPH Enterprise Applications \- Research KB, 访问时间为 十二月 29, 2025， [https://kb.wisc.edu/smph/informatics/page.php?id=152765](https://kb.wisc.edu/smph/informatics/page.php?id=152765)
31. In-Depth Guide | REDCap, 访问时间为 十二月 29, 2025， [https://projectredcap.org/wp-content/uploads/2019/07/In-Depth-Guide2019.pdf](https://projectredcap.org/wp-content/uploads/2019/07/In-Depth-Guide2019.pdf)
32. Services | REDCap \- The George Washington University, 访问时间为 十二月 29, 2025， [https://redcap.smhs.gwu.edu/services](https://redcap.smhs.gwu.edu/services)
33. MyCap Resources, 访问时间为 十二月 29, 2025， [https://projectmycap.org/mycap-resources/](https://projectmycap.org/mycap-resources/)
34. MyCap – Mobilizing the participant voice, 访问时间为 十二月 29, 2025， [https://projectmycap.org/](https://projectmycap.org/)
35. MyCap: a flexible and configurable platform for mobilizing the participant voice \- PMC, 访问时间为 十二月 29, 2025， [https://pmc.ncbi.nlm.nih.gov/articles/PMC9165428/](https://pmc.ncbi.nlm.nih.gov/articles/PMC9165428/)
36. MyCap \- REDCap Support \- University of Alberta, 访问时间为 十二月 29, 2025， [https://help.redcap.ualberta.ca/help-and-faq/mycap](https://help.redcap.ualberta.ca/help-and-faq/mycap)
37. REDCap: MyCap \- Active Task List \- SMPH Enterprise Applications \- Research KB, 访问时间为 十二月 29, 2025， [https://kb.wisc.edu/smph/informatics/133154](https://kb.wisc.edu/smph/informatics/133154)
38. REDCap External Module – MyCap, 访问时间为 十二月 29, 2025， [https://projectmycap.org/tag/redcap-external-module/](https://projectmycap.org/tag/redcap-external-module/)
39. MYCAP HELP Table of Contents \- REDCap, 访问时间为 十二月 29, 2025， [https://redcap.med.upenn.edu/redcap\_v14.3.13/Resources/misc/mycap\_help.pdf](https://redcap.med.upenn.edu/redcap_v14.3.13/Resources/misc/mycap_help.pdf)
40. How to use exportRecordsTyped function from the redcapAPI package to import the data without factors? \- Stack Overflow, 访问时间为 十二月 29, 2025， [https://stackoverflow.com/questions/76815004/how-to-use-exportrecordstyped-function-from-the-redcapapi-package-to-import-the](https://stackoverflow.com/questions/76815004/how-to-use-exportrecordstyped-function-from-the-redcapapi-package-to-import-the)
41. JSONDecodeError · Issue \#265 · redcap-tools/PyCap \- GitHub, 访问时间为 十二月 29, 2025， [https://github.com/redcap-tools/PyCap/issues/265](https://github.com/redcap-tools/PyCap/issues/265)
42. Importing data into REDCap • Backup options • API Basics \- ITHS, 访问时间为 十二月 29, 2025， [https://www.iths.org/wp-content/uploads/REDCap-Importing-Exporting-302.pdf](https://www.iths.org/wp-content/uploads/REDCap-Importing-Exporting-302.pdf)
43. BCCHR-IT/data-entry-trigger-builder: An External Module that provides an interface to create a DET between a source and destination project. \- GitHub, 访问时间为 十二月 29, 2025， [https://github.com/BCCHR-IT/data-entry-trigger-builder](https://github.com/BCCHR-IT/data-entry-trigger-builder)
44. RedCap API export \- Python Discussions, 访问时间为 十二月 29, 2025， [https://discuss.python.org/t/redcap-api-export/32252](https://discuss.python.org/t/redcap-api-export/32252)
45. REDCap External Module for automated generation of record event schedules. \- GitHub, 访问时间为 十二月 29, 2025， [https://github.com/lsgs/redcap-autoschedule](https://github.com/lsgs/redcap-autoschedule)
46. redcap-autoschedule/README.md at master \- GitHub, 访问时间为 十二月 29, 2025， [https://github.com/lsgs/redcap-autoschedule/blob/master/README.md](https://github.com/lsgs/redcap-autoschedule/blob/master/README.md)
47. redcap-repo · GitHub Topics, 访问时间为 十二月 29, 2025， [https://github.com/topics/redcap-repo](https://github.com/topics/redcap-repo)
48. A Comprehensive Guide to REDCap | UNMC, 访问时间为 十二月 29, 2025， [https://www.unmc.edu/vcr/\_documents/unmc\_redcap\_usage.pdf](https://www.unmc.edu/vcr/_documents/unmc_redcap_usage.pdf)

596
docs/03-业务模块/Redcap/04-参考资料/02-REDCap部署指南与环境要求_旧版.md
View File

File diff suppressed because it is too large Load Diff

1106
docs/03-业务模块/Redcap/04-参考资料/03-REDCap本地Docker开发环境部署方案_旧版.md
View File

File diff suppressed because it is too large Load Diff

119
docs/03-业务模块/Redcap/README.md
View File

@@ -1,32 +1,32 @@
# REDCap模块文档
**鐗堟湰锛?* v1.0
**版本：** v1.0
**最后更新：** 2026-01-02
**模块状态：** 🟢 本地环境已部署，API开发中
---
## 馃殌 蹇<>€熷紑濮?
## 🚀 快速开始
### 我想部署REDCap
馃憠 **[10-REDCap_Docker閮ㄧ讲鎿嶄綔鎵嬪唽.md](./01-閮ㄧ讲涓庨厤缃?10-REDCap_Docker閮ㄧ讲鎿嶄綔鎵嬪唽.md)** 猸?
👉 **[10-REDCap_Docker部署操作手册.md](./01-部署与配置/10-REDCap_Docker部署操作手册.md)** ⭐
杩欐槸鏈€鏍稿績鐨勬枃妗ｏ紒鍖呭惈锛?
- 鉁?浠?鍒?鐨勫畬鏁撮儴缃叉祦绋?
- 鉁?Docker鏂囦欢澶嶇敤璇存槑
- 鉁?甯歌<E794AF>闂<EFBFBD><E99782>涓庤В鍐虫柟妗?
- 鉁?閫傜敤浜庢湰鍦?ECS/鍖婚櫌鐜<E6AB8C><E9909C>
这是最核心的文档！包含：
- ✅ 从0到1的完整部署流程
- ✅ Docker文件复用说明
- ✅ 常见问题与解决方案
- ✅ 适用于本地/ECS/医院环境
**30鍒嗛挓瀹屾垚閮ㄧ讲锛?*
**30分钟完成部署！**
---
### 我遇到问题了
馃憠 **[13-閮ㄧ讲闂<EFBFBD><EFBFBD>鎺掓煡鎵嬪唽.md](./01-閮ㄧ讲涓庨厤缃?13-閮ㄧ讲闂<E8AEB2><E99782>鎺掓煡鎵嬪唽.md)** 馃敡
👉 **[13-部署问题排查手册.md](./01-部署与配置/13-部署问题排查手册.md)** 🔧
基于实际踩坑经验，包含：
- ERR_CONTENT_DECODING_FAILED解决方案
- 鐧诲綍澶辫触锛圕RLF姹℃煋锛夎В鍐虫柟妗?
- 登录失败（CRLF污染）解决方案
- Base URL配置错误修复
- MySQL连接问题排查
@@ -36,41 +36,41 @@
### [00-模块概览](./00-模块概览/)
- [00-REDCap模块文档导航.md](./00-模块概览/00-REDCap模块文档导航.md) - 完整文档索引
- [02-REDCap瀵规帴鎬讳綋鏂规<EFBFBD>.md](./00-妯″潡姒傝<EFBFBD>/02-REDCap瀵规帴鎬讳綋鏂规<EFBFBD>.md) - 鎶€鏈<E282AC>灦鏋勮<E98F8B>璁?
- [03-REDCap瀵规帴椋庨櫓璇勪及涓庢妧鏈<EFBFBD>寫鎴樺垎鏋?md](./00-妯″潡姒傝<EFBFBD>/03-REDCap瀵规帴椋庨櫓璇勪及涓庢妧鏈<EFBFBD>寫鎴樺垎鏋?md) - 椋庨櫓璇勪及
- [02-REDCap对接总体方案.md](./00-模块概览/02-REDCap对接总体方案.md) - 技术架构设计
- [03-REDCap对接风险评估与技术挑战分析.md](./00-模块概览/03-REDCap对接风险评估与技术挑战分析.md) - 风险评估
- [04-生产环境部署决策报告_ECS_vs_SAE.md](./00-模块概览/04-生产环境部署决策报告_ECS_vs_SAE.md) - ECS vs SAE对比
### [01-閮ㄧ讲涓庨厤缃甝(./01-閮ㄧ讲涓庨厤缃?) 猸?
- **[10-REDCap_Docker閮ㄧ讲鎿嶄綔鎵嬪唽.md](./01-閮ㄧ讲涓庨厤缃?10-REDCap_Docker閮ㄧ讲鎿嶄綔鎵嬪唽.md)** - 鏍稿績閮ㄧ讲鏂囨。
- [13-閮ㄧ讲闂<EFBFBD><EFBFBD>鎺掓煡鎵嬪唽.md](./01-閮ㄧ讲涓庨厤缃?13-閮ㄧ讲闂<E8AEB2><E99782>鎺掓煡鎵嬪唽.md) - 闂<><E99782>瑙ｅ喅璁板綍
### [01-部署与配置](./01-部署与配置/) ⭐
- **[10-REDCap_Docker部署操作手册.md](./01-部署与配置/10-REDCap_Docker部署操作手册.md)** - 核心部署文档
- [13-部署问题排查手册.md](./01-部署与配置/13-部署问题排查手册.md) - 问题解决记录
### [02-绯荤粺閰嶇疆涓庤繍缁碷(./02-绯荤粺閰嶇疆涓庤繍缁?)
- 馃毀 20-REDCap绯荤粺閰嶇疆鎵嬪唽.md锛堣<E9949B>鍒掍腑锛?
- 馃毀 21-REDCap鏃ュ父杩愮淮鎵嬪唽.md锛堣<E9949B>鍒掍腑锛?
- 馃毀 22-REDCap鍗囩骇鎸囧崡.md锛堣<E9949B>鍒掍腑锛?
### [02-系统配置与运维](./02-系统配置与运维/)
- 🚧 20-REDCap系统配置手册.md（规划中）
- 🚧 21-REDCap日常运维手册.md（规划中）
- 🚧 22-REDCap升级指南.md（规划中）
### [03-API瀵规帴涓庡紑鍙慮(./03-API瀵规帴涓庡紑鍙?)
- [33-REDCap浜屾<EFBFBD>寮€鍙戞繁搴︽寚鍗?md](./03-API瀵规帴涓庡紑鍙?33-REDCap浜屾<EFBFBD>寮€鍙戞繁搴︽寚鍗?md) - External Modules寮€鍙?
- 馃毀 30-REDCap_API浣跨敤鎸囧崡.md锛堝紑鍙戜腑锛?
- 馃毀 31-IIT_Manager涓嶳EDCap瀵规帴璁捐<EFBFBD>.md锛堝紑鍙戜腑锛?
- 馃毀 32-REDCap_API_Adapter寮€鍙戞寚鍗?md锛堝紑鍙戜腑锛?
### [03-API对接与开发](./03-API对接与开发/)
- [33-REDCap二次开发深度指南.md](./03-API对接与开发/33-REDCap二次开发深度指南.md) - External Modules开发
- 🚧 30-REDCap_API使用指南.md（开发中）
- 🚧 31-IIT_Manager与REDCap对接设计.md（开发中）
- 🚧 32-REDCap_API_Adapter开发指南.md（开发中）
### [04-鍙傝€冭祫鏂橾(./04-鍙傝€冭祫鏂?)
### [04-参考资料](./04-参考资料/)
- 旧版文档存档
---
## 📊 当前进度
| 闃舵<EFBFBD> | 鐘舵€?| 瀹屾垚鏃ユ湡 |
| 阶段 | 状态 | 完成日期 |
|------|------|----------|
| 鎶€鏈<EFBFBD>皟鐮?| 鉁?瀹屾垚 | 2025-12 |
| 閮ㄧ讲鏂规<EFBFBD>璁捐<EFBFBD> | 鉁?瀹屾垚 | 2026-01-01 |
| **鏈<EFBFBD>湴鐜<EFBFBD><EFBFBD>閮ㄧ讲** | 鉁?**瀹屾垚** | **2026-01-02** |
| API Adapter寮€鍙?| 鈴?杩涜<E69DA9>涓?| 棰勮<E6A3B0>2026-01-03 |
| 鐢熶骇鐜<EFBFBD><EFBFBD>閮ㄧ讲 | 馃搮 璁″垝涓?| 寰呭畾 |
| 技术调研 | ✅ 完成 | 2025-12 |
| 部署方案设计 | ✅ 完成 | 2026-01-01 |
| **本地环境部署** | ✅ **完成** | **2026-01-02** |
| API Adapter开发 | ⏳ 进行中 | 预计2026-01-03 |
| 生产环境部署 | 📅 计划中 | 待定 |
**璁块棶鍦板潃锛?* http://localhost:8080/
**访问地址：** http://localhost:8080/
**管理员账户：** Admin / Admin123!
---
@@ -79,65 +79,64 @@
```
IIT Manager Agent (企业微信)
鈫?
↓
REDCap API Adapter
鈫?
↓
REDCap系统 (EDC)
鈫?
鐮旂┒鏁版嵁閲囬泦涓庣<EFBFBD>鐞?
↓
研究数据采集与管理
```
**鏍稿績鍔熻兘锛?*
- 馃搵 鐢靛瓙鏁版嵁閲囬泦锛圗DC锛?
**核心功能：**
- 📋 电子数据采集（EDC）
- 📊 数据字典管理
- 🔍 数据质量控制
- 馃搱 鎶ヨ〃涓庡<E6B693>鍑?
- 📈 报表与导出
- 👥 用户权限管理
---
## 馃洜锔?Docker閰嶇疆鏂囦欢浣嶇疆
## 🛠️ Docker配置文件位置
**鎵€鏈塂ocker閰嶇疆鏂囦欢閮藉湪锛?*
**所有Docker配置文件都在：**
```
AIclinicalresearch/redcap-docker-dev/
鈹溾攢鈹€ Dockerfile.redcap 鉁?100%鍙<EFBFBD><EFBFBD>鐢?
├── Dockerfile.redcap ✅ 100%可复用
├── docker-compose.yml ⚠️ 需微调
鈹溾攢鈹€ docker-compose.prod.yml 鈿狅笍 闇€淇<E282AC>敼鏁版嵁搴撻厤缃?
鈹溾攢鈹€ docker-entrypoint.sh 鉁?100%鍙<EFBFBD><EFBFBD>鐢?
├── docker-compose.prod.yml ⚠️ 需修改数据库配置
├── docker-entrypoint.sh ✅ 100%可复用
├── config/
鈹? 鈹溾攢鈹€ apache/redcap.conf 鈿狅笍 闇€淇<E282AC>敼鍩熷悕
鈹? 鈹溾攢鈹€ php/php.ini 鉁?100%鍙<EFBFBD><EFBFBD>鐢?
鈹? 鈹斺攢鈹€ database.php 鉂?蹇呴』鏍规嵁鐜<E5B581><E9909C>瀹氬埗
鈹溾攢鈹€ scripts/ 鍙<EFBFBD>€夎緟鍔╄剼鏈?
鈹斺攢鈹€ .gitattributes 鉁?100%鍙<EFBFBD><EFBFBD>鐢?
│ ├── apache/redcap.conf ⚠️ 需修改域名
│ ├── php/php.ini ✅ 100%可复用
│ └── database.php ❌ 必须根据环境定制
├── scripts/ 可选辅助脚本
└── .gitattributes ✅ 100%可复用
```
璇﹁<EFBFBD>锛歔10-REDCap_Docker閮ㄧ讲鎿嶄綔鎵嬪唽.md](./01-閮ㄧ讲涓庨厤缃?10-REDCap_Docker閮ㄧ讲鎿嶄綔鎵嬪唽.md)
详见：[10-REDCap_Docker部署操作手册.md](./01-部署与配置/10-REDCap_Docker部署操作手册.md)
---
## 📞 获取帮助
- **閮ㄧ讲闂<EFBFBD><EFBFBD>**锛氭煡鐪?[13-閮ㄧ讲闂<E8AEB2><E99782>鎺掓煡鎵嬪唽.md](./01-閮ㄧ讲涓庨厤缃?13-閮ㄧ讲闂<E8AEB2><E99782>鎺掓煡鎵嬪唽.md)
- **部署问题**：查看 [13-部署问题排查手册.md](./01-部署与配置/13-部署问题排查手册.md)
- **REDCap官方**：https://projectredcap.org/
- **鎶€鏈<EFBFBD>敮鎸?*锛氭煡鐪嬬浉鍏虫枃妗ｆ垨鎻怚ssue
- **技术支持**：查看相关文档或提Issue
---
## 馃攧 鏈€杩戞洿鏂?
## 🔄 最近更新
| 日期 | 更新内容 |
|------|----------|
| 2026-01-02 | 鉁?瀹屾垚鏈<E59E9A>湴Docker鐜<72><E9909C>閮ㄧ讲 |
| 2026-01-02 | 鉁?鍒涘缓REDCap Docker閮ㄧ讲鎿嶄綔鎵嬪唽 |
| 2026-01-02 | 鉁?鍒涘缓閮ㄧ讲闂<E8AEB2><E99782>鎺掓煡鎵嬪唽 |
| 2026-01-02 | 鉁?閲嶇粍鏂囨。浣撶郴 |
| 2026-01-02 | ✅ 完成本地Docker环境部署 |
| 2026-01-02 | ✅ 创建REDCap Docker部署操作手册 |
| 2026-01-02 | ✅ 创建部署问题排查手册 |
| 2026-01-02 | ✅ 重组文档体系 |
---
**鍑嗗<EFBFBD>濂藉紑濮嬩簡鍚楋紵** 馃憠 [寮€濮嬮儴缃瞉(./01-閮ㄧ讲涓庨厤缃?10-REDCap_Docker閮ㄧ讲鎿嶄綔鎵嬪唽.md)
**准备好开始了吗？** 👉 [开始部署](./01-部署与配置/10-REDCap_Docker部署操作手册.md)