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

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

 **日期**: 2026-01-02  
-**寮€鍙戣€?*: AI Assistant  
-**鐘舵€?*: 鉁?鍏ㄩ儴瀹屾垚
+**开发者**: AI Assistant  
+**状态**: ✅ 全部完成

 ---

 ## 📋 任务完成清单

 - [x] 环境准备：DET配置 + API Token获取
- [x] 寮€鍙?RedcapAdapter锛圓PI閫傞厤鍣<EFBFBD>級
- [x] 寮€鍙?WebhookController锛圵ebhook鎺ユ敹鍣<EFBFBD>級
- [x] 寮€鍙?SyncManager锛堣疆璇㈢<EFBFBD>鐞嗭級
+- [x] 开发 RedcapAdapter（API适配器）
+- [x] 开发 WebhookController（Webhook接收器）
+- [x] 开发 SyncManager（轮询管理）
 - [x] 配置路由和Worker注册
- [x] 缂栧啓娴嬭瘯鑴氭湰锛圓PI + Webhook + 闆嗘垚锛?- [x] 绔<>埌绔<E59F8C>獙璇佹祴璇曞噯澶?
+- [x] 编写测试脚本（API + Webhook + 集成）
+- [x] 端到端验证测试准备
+
 ---

 ## 🎯 核心成果

-### 1. RedcapAdapter - API閫傞厤鍣?
+### 1. RedcapAdapter - API适配器
+
 **文件**: `backend/src/modules/iit-manager/adapters/RedcapAdapter.ts`

 **功能**:
- 鉁?`exportRecords()` - 鏀<EFBFBD>寔澧為噺鍚屾<EFBFBD>锛坉ateRangeBegin锛?- 鉁?`exportMetadata()` - 鑾峰彇瀛楁<E7809B>瀹氫箟
- 鉁?`importRecords()` - 鍥炲啓鏁版嵁锛圥hase 2棰勭暀锛?- 鉁?`testConnection()` - 杩炴帴娴嬭瘯
- 鉁?瀹屾暣鐨勯敊璇<E6958A><E79287>鐞嗗拰鏃ュ織璁板綍
- 鉁?鎬ц兘鐩戞帶锛堣<E9949B>姹傝€楁椂锛?
-**鎶€鏈<E282AC>寒鐐?*:
- 浣跨敤 `form-data` 鏋勯€?multipart/form-data 璇锋眰
- 鏅鸿兘鏃ユ湡鏍煎紡鍖栵紙REDCap鏍煎紡锛歒YYY-MM-DD HH:MM:SS锛?- Axios 瀹炰緥鍖栵紝鏀<E7B49D>寔瓒呮椂閰嶇疆
- 鍙嬪ソ鐨勯敊璇<E6958A>俊鎭<E4BF8A>紙杩炴帴澶辫触銆佹潈闄愪笉瓒炽€佺<E282AC>鐐逛笉瀛樺湪锛?
+- ✅ `exportRecords()` - 支持增量同步（dateRangeBegin）
+- ✅ `exportMetadata()` - 获取字段定义
+- ✅ `importRecords()` - 回写数据（Phase 2预留）
+- ✅ `testConnection()` - 连接测试
+- ✅ 完整的错误处理和日志记录
+- ✅ 性能监控（请求耗时）
+
+**技术亮点**:
+- 使用 `form-data` 构造 multipart/form-data 请求
+- 智能日期格式化（REDCap格式：YYYY-MM-DD HH:MM:SS）
+- Axios 实例化，支持超时配置
+- 友好的错误信息（连接失败、权限不足、端点不存在）
+
 ---

-### 2. WebhookController - Webhook鎺ユ敹鍣?
+### 2. WebhookController - Webhook接收器
+
 **文件**: `backend/src/modules/iit-manager/controllers/WebhookController.ts`

 **功能**:
- 鉁?鎺ユ敹 REDCap DET Webhook
- 鉁?**鏋侀€熷搷搴?*锛?100ms 杩斿洖 200 OK
- 鉁?寮傛<E5AFAE>澶勭悊锛坄setImmediate`锛?- 鉁?**骞傜瓑鎬ф<E98EAC>鏌?*锛?鍒嗛挓鍐呴槻閲嶅<E996B2>
- 鉁?鎷夊彇瀹屾暣璁板綍鏁版嵁
- 鉁?鎺ㄩ€佸埌璐ㄦ帶闃熷垪锛坧g-boss锛?- 鉁?瀹屾暣鐨勫<E990A8>璁℃棩蹇?
+- ✅ 接收 REDCap DET Webhook
+- ✅ **极速响应**：<100ms 返回 200 OK
+- ✅ 异步处理（`setImmediate`）
+- ✅ **幂等性检查**：5分钟内防重复
+- ✅ 拉取完整记录数据
+- ✅ 推送到质控队列（pg-boss）
+- ✅ 完整的审计日志
+
 **性能目标**:
- 鍚屾<EFBFBD>鍝嶅簲锛?100ms 鉁?- 鏁版嵁鎷夊彇锛?2s
- 绔<EFBFBD>埌绔<EFBFBD>€氱煡锛?5s
+- 同步响应：<100ms ✅
+- 数据拉取：<2s
+- 端到端通知：<5s

 **架构设计**:
 ```
-REDCap DET 鈫?Webhook鎺ユ敹鍣?鈫?绔嬪嵆杩斿洖200 OK
-                鈫?(寮傛<E5AFAE>)
+REDCap DET → Webhook接收器 → 立即返回200 OK
+                ↓ (异步)
           查找项目配置
-                鈫?           骞傜瓑鎬ф<E98EAC>鏌?                鈫?           鎷夊彇瀹屾暣鏁版嵁
-                鈫?           鎺ㄩ€佽川鎺ч槦鍒?                鈫?           璁板綍瀹¤<E780B9>鏃ュ織
+                ↓
+           幂等性检查
+                ↓
+           拉取完整数据
+                ↓
+           推送质控队列
+                ↓
+           记录审计日志
 ```

 ---
@@ -61,17 +80,21 @@ REDCap DET
 **文件**: `backend/src/modules/iit-manager/services/SyncManager.ts`

 **功能**:
- 鉁?瀹氭椂杞<E6A482><E69D9E>锛堟瘡5鍒嗛挓锛?- 鉁?**澧為噺鍚屾<E98D9A>**锛氫娇鐢?`lastSyncAt`
- 鉁?**骞跺彂澶勭悊澶氶」鐩?*
- 鉁?鎵嬪姩鍚屾<E98D9A>鎺ュ彛锛坄manualSync`锛?- 鉁?鍏ㄩ噺鍚屾<E98D9A>鎺ュ彛锛坄fullSync`锛?- 鉁?瀹屾暣鐨勯敊璇<E6958A><E79287>鐞嗗拰鎭㈠<E98EAD>鏈哄埗
+- ✅ 定时轮询（每5分钟）
+- ✅ **增量同步**：使用 `lastSyncAt`
+- ✅ **并发处理多项目**
+- ✅ 手动同步接口（`manualSync`）
+- ✅ 全量同步接口（`fullSync`）
+- ✅ 完整的错误处理和恢复机制

 **使用场景**:
 - 内网环境无法接收Webhook
 - Webhook丢失时的兜底方案
 - 定期全量扫描

-**鎶€鏈<EFBFBD>寒鐐?*:
- pg-boss 瀹氭椂浠诲姟锛圕ron: */5 * * * *锛?- 鎸夎<E98EB8>褰旾D鍘婚噸
+**技术亮点**:
+- pg-boss 定时任务（Cron: */5 * * * *）
+- 按记录ID去重
 - 失败自动重试
 - 审计日志记录

@@ -83,13 +106,13 @@ REDCap DET

 **路由列表**:

-| 鏂规硶 | 璺<>緞 | 鍔熻兘 | 鐘舵€?|
+| 方法 | 路径 | 功能 | 状态 |
 |-----|------|------|------|
-| GET | `/api/v1/iit/health` | 鍋ュ悍妫€鏌?| 鉁?|
-| POST | `/api/v1/iit/webhooks/redcap` | DET Webhook鎺ユ敹鍣?| 鉁?|
-| POST | `/api/v1/iit/projects/:id/sync` | 鎵嬪姩瑙﹀彂鍚屾<EFBFBD> | 鉁?|
-| POST | `/api/v1/iit/projects/:id/full-sync` | 鍏ㄩ噺鍚屾<EFBFBD> | 鉁?|
-| GET | `/api/v1/iit/webhooks/health` | Webhook鍋ュ悍妫€鏌?| 鉁?|
+| GET | `/api/v1/iit/health` | 健康检查 | ✅ |
+| POST | `/api/v1/iit/webhooks/redcap` | DET Webhook接收器 | ✅ |
+| POST | `/api/v1/iit/projects/:id/sync` | 手动触发同步 | ✅ |
+| POST | `/api/v1/iit/projects/:id/full-sync` | 全量同步 | ✅ |
+| GET | `/api/v1/iit/webhooks/health` | Webhook健康检查 | ✅ |

 ---

@@ -98,7 +121,9 @@ REDCap DET
 **文件**: `backend/src/modules/iit-manager/index.ts`

 **Worker列表**:
- 鉁?`iit:redcap:poll` - 瀹氭椂杞<EFBFBD><EFBFBD>浠诲姟锛堟瘡5鍒嗛挓锛?- 馃敎 `iit:quality-check` - 璐ㄦ帶浠诲姟锛圥hase 1.5锛?
+- ✅ `iit:redcap:poll` - 定时轮询任务（每5分钟）
+- 🔜 `iit:quality-check` - 质控任务（Phase 1.5）
+
 ---

 ### 6. 测试脚本
@@ -108,10 +133,13 @@ REDCap DET
 **文件**: `backend/src/modules/iit-manager/test-redcap-api.ts`

 **测试内容**:
- 鉁?鍒涘缓 Adapter 瀹炰緥
- 鉁?娴嬭瘯API杩炴帴
- 鉁?瀵煎嚭鍏冩暟鎹?- 鉁?瀵煎嚭鎵€鏈夎<E98F88>褰?- 鉁?瀵煎嚭鎸囧畾璁板綍
- 鉁?澧為噺鍚屾<E98D9A>娴嬭瘯锛堟渶杩?灏忔椂锛?
+- ✅ 创建 Adapter 实例
+- ✅ 测试API连接
+- ✅ 导出元数据
+- ✅ 导出所有记录
+- ✅ 导出指定记录
+- ✅ 增量同步测试（最近1小时）
+
 **运行方式**:
 ```bash
 cd backend
@@ -123,8 +151,14 @@ npm run tsx src/modules/iit-manager/test-redcap-api.ts
 **文件**: `backend/src/modules/iit-manager/test-redcap-webhook.ts`

 **测试内容**:
- 鉁?Webhook鍋ュ悍妫€鏌?- 鉁?妫€鏌ラ」鐩<E3808D>厤缃?- 鉁?鍙戦€佹祴璇昗ebhook
- 鉁?楠岃瘉鍝嶅簲鏃堕棿锛?100ms锛?- 鉁?妫€鏌ュ<E98F8C>璁℃棩蹇?- 鉁?娴嬭瘯骞傜瓑鎬?- 鉁?娴嬭瘯鏃犳晥Webhook锛?00閿欒<E996BF>锛?
+- ✅ Webhook健康检查
+- ✅ 检查项目配置
+- ✅ 发送测试Webhook
+- ✅ 验证响应时间（<100ms）
+- ✅ 检查审计日志
+- ✅ 测试幂等性
+- ✅ 测试无效Webhook（400错误）
+
 **运行方式**:
 ```bash
 cd backend
@@ -136,12 +170,19 @@ npm run tsx src/modules/iit-manager/test-redcap-webhook.ts
 **文件**: `backend/src/modules/iit-manager/test-redcap-integration.ts`

 **测试内容**:
- 鉁?鍚庣<E98D9A>鏈嶅姟妫€鏌?- 鉁?鏁版嵁搴撻厤缃<E58EA4><E7BC83>鏌?- 鉁?REDCap API杩炴帴
- 鉁?鍏冩暟鎹<E69A9F>幏鍙?- 鉁?璁板綍鑾峰彇
- 鉁?Webhook鎺ユ敹鍣ㄦ祴璇?- 鉁?寮傛<E5AFAE>澶勭悊楠岃瘉
- 鉁?瀹¤<E780B9>鏃ュ織妫€鏌?- 鉁?澧為噺鍚屾<E98D9A>娴嬭瘯
- 鉁?鎵嬪姩鍚屾<E98D9A>鎺ュ彛娴嬭瘯
- 鉁?Webhook鍋ュ悍妫€鏌?- 鉁?骞傜瓑鎬ф祴璇?
+- ✅ 后端服务检查
+- ✅ 数据库配置检查
+- ✅ REDCap API连接
+- ✅ 元数据获取
+- ✅ 记录获取
+- ✅ Webhook接收器测试
+- ✅ 异步处理验证
+- ✅ 审计日志检查
+- ✅ 增量同步测试
+- ✅ 手动同步接口测试
+- ✅ Webhook健康检查
+- ✅ 幂等性测试
+
 **运行方式**:
 ```bash
 cd backend
@@ -152,7 +193,8 @@ npm run tsx src/modules/iit-manager/test-redcap-integration.ts

 ## 🔧 环境配置

-### REDCap 閰嶇疆锛堝凡瀹屾垚锛?
+### REDCap 配置（已完成）
+
 **项目信息**:
 - 项目名称: test0102
 - 项目ID (PID): 16
@@ -200,38 +242,48 @@ INSERT INTO iit_schema.projects (

 ## 📊 与文档的对比

-### 鉁?瀹屽叏绗﹀悎鐨勫湴鏂?
-1. **鎶€鏈<E282AC>柟妗?*: DET + REST API锛堜笉浣跨敤External Modules锛?2. **娣峰悎妯″紡**: Webhook瀹炴椂瑙﹀彂 + 杞<><E69D9E>鍏滃簳
-3. **鏍稿績閫昏緫**: 骞傜瓑鎬с€佸紓姝ュ<EFBFBD>鐞嗐€佸<EFBFBD>閲忓悓姝?4. **浠ｇ爜缁撴瀯**: Adapter銆丆ontroller銆丼ervice鍒嗗眰娓呮櫚
-5. **鎬ц兘鐩<EFBFBD>爣**: <100ms鍝嶅簲銆?s绔<73>埌绔?
-### 馃殌 瓒呰秺鏂囨。鐨勫湴鏂?
-1. **鏇村己澶х殑閿欒<EFBFBD>澶勭悊**: 杩炴帴娴嬭瘯銆佸弸濂介敊璇<E6958A>俊鎭?2. **鏇村畬鍠勭殑鏃ュ織**: 鎬ц兘鐩戞帶銆佽<E98A86>缁嗕笂涓嬫枃
+### ✅ 完全符合的地方
+
+1. **技术方案**: DET + REST API（不使用External Modules）
+2. **混合模式**: Webhook实时触发 + 轮询兜底
+3. **核心逻辑**: 幂等性、异步处理、增量同步
+4. **代码结构**: Adapter、Controller、Service分层清晰
+5. **性能目标**: <100ms响应、5s端到端
+
+### 🚀 超越文档的地方
+
+1. **更强大的错误处理**: 连接测试、友好错误信息
+2. **更完善的日志**: 性能监控、详细上下文
 3. **更灵活的同步**: 手动同步、全量同步、并发处理多项目
 4. **更完善的测试**: API测试、Webhook测试、集成测试（12项测试）
-5. **鏇村ソ鐨勪唬鐮佽川閲?*: 璇︾粏娉ㄩ噴銆佺被鍨嬪畾涔夈€丼chema楠岃瘉
+5. **更好的代码质量**: 详细注释、类型定义、Schema验证

-### 鈿狅笍 淇<><E6B787>鐨勫湴鏂?
-1. **鏁版嵁搴撳瓧娈靛悕**: 鏂囨。鐢?`snake_case`锛屽疄闄匰chema鐢?`camelCase`
-   - `redcap_api_token` 鈫?`redcapApiToken`
-   - `redcap_api_base_url` 鈫?`redcapUrl`
-   - `sync_enabled` 鈫?锛堟殏鏈<E6AE8F>湪Schema涓<61>畾涔夛級
+### ⚠️ 修正的地方

-2. **琛ㄥ悕**: 鏂囨。鐢?`projects`锛屽疄闄呯敤 `IitProject`
+1. **数据库字段名**: 文档用 `snake_case`，实际Schema用 `camelCase`
+   - `redcap_api_token` → `redcapApiToken`
+   - `redcap_api_base_url` → `redcapUrl`
+   - `sync_enabled` → （暂未在Schema中定义）

-3. **瀹¤<EFBFBD>鏃ュ織瀛楁<EFBFBD>**: 鏂囨。鐢?`operation_type`锛屽疄闄呯敤 `actionType`
+2. **表名**: 文档用 `projects`，实际用 `IitProject`
+
+3. **审计日志字段**: 文档用 `operation_type`，实际用 `actionType`

 ---

 ## 🔍 Linter 错误修复

-淇<EFBFBD><EFBFBD>浜嗕互涓嬬被鍨嬬殑閿欒<EFBFBD>锛?
-1. 鉁?**妯″潡瀵煎叆璺<E58F86>緞**: 绉婚櫎 `.js` 鎵╁睍鍚嶏紙TypeScript瀵煎叆瑙勮寖锛?2. 鉁?**鏁版嵁搴撳瓧娈靛悕**: 缁熶竴涓?camelCase
-3. 鉁?**绫诲瀷閿欒<E996BF>**: 娣诲姞鏄惧紡绫诲瀷娉ㄨВ
-4. 鉁?**JSON绫诲瀷**: 浣跨敤 `JSON.parse(JSON.stringify())` 杞<>崲
+修复了以下类型的错误：
+
+1. ✅ **模块导入路径**: 移除 `.js` 扩展名（TypeScript导入规范）
+2. ✅ **数据库字段名**: 统一为 camelCase
+3. ✅ **类型错误**: 添加显式类型注解
+4. ✅ **JSON类型**: 使用 `JSON.parse(JSON.stringify())` 转换

 ---

-## 馃摑 涓嬩竴姝ュ伐浣滐紙Day 3锛?
+## 📝 下一步工作（Day 3）
+
 ### Phase 1.5: 数据质控Agent

 1. **质控Worker注册**:
@@ -240,37 +292,45 @@ INSERT INTO iit_schema.projects (

 2. **Dify RAG集成**:
   - 集成 Dify Client
-   - 鏌ヨ<EFBFBD>鐮旂┒鏂规<EFBFBD>鐭ヨ瘑搴?
+   - 查询研究方案知识库
+
 3. **质控规则引擎**:
   - 实现基础质控规则
   - 生成质控意见

 4. **企业微信通知**:
-   - 鍙戦€佽川鎺у崱鐗?   - 鍖呭惈锛氳<E9949B>褰曚俊鎭<E4BF8A>€佽川鎺ч棶棰樸€佸缓璁<E7BC93>搷浣?
-5. **褰卞瓙鐘舵€佺<E282AC>鐞?*:
+   - 发送质控卡片
+   - 包含：记录信息、质控问题、建议操作
+
+5. **影子状态管理**:
   - 创建 PendingAction
-   - 鐘舵€侊細PROPOSED 鈫?APPROVED 鈫?EXECUTED
+   - 状态：PROPOSED → APPROVED → EXECUTED

 ---

 ## 🎉 总结

-Day 2 鐨勫紑鍙戜换鍔?*鍏ㄩ儴瀹屾垚**锛佹垜浠<E59E9C>垚鍔熷疄鐜颁簡锛?
-鉁?**瀹屾暣鐨凴EDCap瀵规帴鑳藉姏**  
-鉁?**娣峰悎鍚屾<E98D9A>妯″紡锛圵ebhook + 杞<><E69D9E>锛?*  
-鉁?**鏋侀€熷搷搴旂殑Webhook鎺ユ敹鍣<E695B9>紙<100ms锛?*  
-鉁?**瀹屽杽鐨勬祴璇曡剼鏈?*  
-鉁?**绗﹀悎涓旇秴瓒婃妧鏈<E5A6A7>枃妗ｇ殑瀹炵幇**  
+Day 2 的开发任务**全部完成**！我们成功实现了：
+
+✅ **完整的REDCap对接能力**  
+✅ **混合同步模式（Webhook + 轮询）**  
+✅ **极速响应的Webhook接收器（<100ms）**  
+✅ **完善的测试脚本**  
+✅ **符合且超越技术文档的实现**  

 **代码质量**:
 - 详细的注释和文档
- 瀹屾暣鐨勯敊璇<EFBFBD><EFBFBD>鐞?- 鎬ц兘鐩戞帶鍜屾棩蹇?- 绫诲瀷瀹夊叏
- 鍙<EFBFBD>祴璇曟€?
-**涓嬩竴姝?*: 鍑嗗<E98D91>娴嬭瘯鐜<E798AF><E9909C>锛岃繍琛屾祴璇曡剼鏈<E589BC>紝楠岃瘉绔<E79889>埌绔<E59F8C>姛鑳斤紒
+- 完整的错误处理
+- 性能监控和日志
+- 类型安全
+- 可测试性
+
+**下一步**: 准备测试环境，运行测试脚本，验证端到端功能！

 ---

-**寮€鍙戞椂闂?*: ~2灏忔椂  
-**浠ｇ爜琛屾暟**: ~1,500琛? 
-**娴嬭瘯瑕嗙洊**: 12椤归泦鎴愭祴璇? 
-**鏂囨。璐ㄩ噺**: 猸愨瓙猸愨瓙猸?
+**开发时间**: ~2小时  
+**代码行数**: ~1,500行  
+**测试覆盖**: 12项集成测试  
+**文档质量**: ⭐⭐⭐⭐⭐
+