AIclinicalresearch/docs/03-业务模块/ADMIN-运营管理端/06-开发记录/2026-01-16_用户管理功能与模块权限系统完成.md

用户管理功能与模块权限系统完成

日期： 2026-01-16
开发者： AI Assistant + User
版本： ADMIN v0.5
开发时长： 1天
代码量： ~3000 行（后端 + 前端）

---

📋 开发概述

本次开发完成了运营管理端的用户管理功能（Phase 4.1），并对整个系统进行了模块权限系统改造（从版本系统升级为模块权限系统）。

---

🎯 完成功能

1. 用户管理功能（100%）

数据库设计

• 新增表： platform_schema.user_modules（用户模块权限表）
• 字段设计：
  • user_id: 用户ID
  • tenant_id: 租户ID（在哪个租户内的权限）
  • module_code: 模块代码（RVW, PKB, ASL, DC, IIT, AIA, SSA, ST）
  • is_enabled: 是否启用
• 唯一约束： (user_id, tenant_id, module_code)
• 关联关系： User ← user_modules → Tenant

权限系统

• 新增权限： 4 个
  • user:view - 查看用户
  • user:create - 创建用户
  • user:edit - 编辑用户
  • user:delete - 删除用户
• 角色分配：
  • SUPER_ADMIN: 全部权限
  • HOSPITAL_ADMIN / PHARMA_ADMIN: view + create + edit（本租户内）
  • DEPARTMENT_ADMIN: view（本科室内）

后端实现

文件列表：

1. backend/src/modules/admin/types/user.types.ts (148 行)
   • 定义请求/响应类型
   • 用户列表、详情、创建、更新等类型
2. backend/src/modules/admin/services/userService.ts (780 行)
   • listUsers() - 列表查询（支持分页、搜索、筛选）
   • getUserById() - 获取详情
   • createUser() - 创建用户
   • updateUser() - 更新用户
   • updateUserStatus() - 启用/禁用
   • resetUserPassword() - 重置密码
   • assignTenantToUser() - 分配租户
   • removeTenantFromUser() - 移除租户
   • updateUserModules() - 更新模块权限
   • importUsers() - 批量导入
   • getUserQueryScope() - 数据隔离（基于角色）
3. backend/src/modules/admin/controllers/userController.ts (526 行)
   • 处理 HTTP 请求和响应
   • 参数验证和错误处理
4. backend/src/modules/admin/routes/userRoutes.ts (122 行)
   • 13 个 API 端点
   • 集成认证和权限中间件

API 端点：

GET    /api/admin/users                    - 用户列表
GET    /api/admin/users/:id                - 用户详情
POST   /api/admin/users                    - 创建用户
PUT    /api/admin/users/:id                - 更新用户
PUT    /api/admin/users/:id/status         - 更新状态
POST   /api/admin/users/:id/reset-password - 重置密码
POST   /api/admin/users/:id/tenants        - 分配租户（仅超管）
DELETE /api/admin/users/:id/tenants/:tid   - 移除租户（仅超管）
PUT    /api/admin/users/:id/modules        - 更新模块权限
POST   /api/admin/users/import             - 批量导入
GET    /api/admin/users/options/tenants    - 租户选项
GET    /api/admin/users/options/tenants/:id/departments - 科室选项
GET    /api/admin/users/options/tenants/:id/modules     - 模块选项

前端实现

文件列表：

1. frontend-v2/src/modules/admin/types/user.ts (197 行)
   • TypeScript 类型定义
   • 角色/租户/状态常量
2. frontend-v2/src/modules/admin/api/userApi.ts (130 行)
   • API 调用封装
3. frontend-v2/src/modules/admin/pages/UserListPage.tsx (412 行)
   • 用户列表页（分页、搜索、筛选）
   • 操作菜单（查看、编辑、禁用、重置密码）
4. frontend-v2/src/modules/admin/pages/UserFormPage.tsx (341 行)
   • 创建/编辑用户表单
   • 租户配置
   • 模块权限配置（多选框）
5. frontend-v2/src/modules/admin/pages/UserDetailPage.tsx (393 行)
   • 用户详细信息展示
   • 租户关系管理
   • 模块权限查看
6. frontend-v2/src/modules/admin/components/ImportUserModal.tsx (302 行)
   • Excel 批量导入
   • 文件解析、预览、导入结果
7. frontend-v2/src/modules/admin/components/AssignTenantModal.tsx (169 行)
   • 分配租户弹窗
   • 角色选择、模块配置
8. frontend-v2/src/modules/admin/components/ModulePermissionModal.tsx (121 行)
   • 模块权限配置弹窗
9. frontend-v2/src/modules/admin/index.tsx (32 行)
   • 模块路由入口

路由配置：

/admin/users             - 用户列表
/admin/users/create      - 创建用户
/admin/users/:id         - 用户详情
/admin/users/:id/edit    - 编辑用户

---

2. 模块权限系统改造（100%）

架构升级：从版本系统 → 模块权限系统

旧系统（废弃）：

// 基于版本等级（basic/advanced/premium）
requiredVersion: 'basic'
checkModulePermission(requiredVersion)

新系统（启用）：

// 基于模块代码（AIA/PKB/RVW等）
requiredModule: 'PKB'
hasModule(moduleCode)

后端改造

文件： backend/src/common/auth/auth.service.ts

1. 新增方法： getUserModules(userId)

   • 查询用户所有租户关系
   • 对每个租户，检查租户订阅的模块
   • 如果用户有自定义模块权限，使用自定义权限
   • 否则继承租户的全部模块权限
   • 去重后返回所有可访问模块

2. 修改登录响应：

   // 登录成功返回
   {
     user: {
       id, phone, name, role, ...
       modules: ['AIA', 'PKB', 'RVW']  // 新增
     }
   }
   

前端改造

1. 类型定义更新

• framework/auth/types.ts
  • AuthUser 添加 modules: string[]
  • AuthContextType 添加 hasModule(moduleCode)

2. AuthContext 更新

• framework/auth/AuthContext.tsx
  • 添加 hasModule() 方法
  • 支持模块权限检查

3. 导航栏改造

• framework/layout/TopNavigation.tsx
  • 移除旧逻辑： 不再使用 requiredVersion
  • 新逻辑： 根据 user.modules 过滤显示
  • 用户体验： 只显示有权限的模块（干净、直观）
  • 显示优化： 用户头像下方显示"X 个模块"

4. 路由守卫改造

• framework/router/RouteGuard.tsx
  • 移除旧参数： requiredVersion
  • 新参数： requiredModule (moduleCode)
  • 权限检查： hasModule(moduleCode)
  • 无权限UI： Ant Design Result 组件

5. 路由配置更新

• App.tsx

  <RouteGuard
    requiredModule={module.moduleCode}  // 新
    moduleName={module.name}
  >
  

---

🐛 问题修复

1. 文档编码修复（紧急修复）

问题描述：

• 2026-01-14 的提交导致 docs 目录下几乎所有 Markdown 文档出现乱码
• UTF-8 中文字符被截断，显示为 <EFBFBD>?
• 示例："指南" → "指<>?"、"团队" → "团<>?"

问题原因：

• PowerShell 重定向操作未指定编码
• 使用 git show commit:file.md > file.md 导致编码丢失

修复方案：

1. 从 Git 历史恢复正常版本（4ed67a8）
2. 手动恢复新增的 5 个文档（AIA 相关）
3. 更新 Git 提交规范 v1.2，添加 UTF-8 编码安全规则

修复文件数： ~100+ 个文档

2. 后端类型错误修复

问题： pageSize 从 HTTP 查询参数传入时是字符串，Prisma 需要数字

take: "20"  // 错误
take: 20    // 正确

修复： userService.ts

const page = Number(query.page) || 1;
const pageSize = Number(query.pageSize) || 20;

3. 前端编译错误修复

问题： 导入路径、未使用变量、类型兼容性 修复： 10+ 个文件的小错误修复

4. 登录跳转逻辑优化

问题： 普通用户修改密码后跳转到 /admin/users，显示 403 修复： 智能跳转逻辑

// 检查用户角色是否有权限访问目标页面
// 无权限时自动跳转到首页

---

📊 技术亮点

1. 多租户 + 多模块权限模型

设计思路：

User (用户)
  ├─ tenant_id (默认租户)
  ├─ role (系统角色：SUPER_ADMIN, USER 等)
  ├─ tenant_members[] (多租户关系)
  │   └─ role (在该租户内的角色)
  └─ user_modules[] (精细化模块权限)
      ├─ tenant_id (在哪个租户内)
      ├─ module_code (模块代码)
      └─ is_enabled (是否启用)

权限计算逻辑：

FOR 每个租户关系:
  IF 用户有自定义模块权限:
    使用自定义权限
  ELSE:
    继承租户所有已订阅模块
END

最终权限 = 所有租户权限的并集（去重）

2. 数据隔离策略

基于角色的查询范围：

• SUPER_ADMIN: 无限制，可查看所有用户
• HOSPITAL_ADMIN / PHARMA_ADMIN: 限制 tenant_id = 当前租户
• DEPARTMENT_ADMIN: 限制 tenant_id = 当前租户 AND department_id = 当前科室

实现： getUserQueryScope() 方法

3. 前端模块权限系统

核心理念：

• 极简用户体验： 只显示有权限的模块，不显示锁定/禁用的模块
• 零认知负担： 用户看到的就是可用的
• 性能优化： 登录时一次性返回模块列表，无需反复查询

实现要点：

// 1. 登录时获取模块列表
user.modules = ['PKB', 'RVW']

// 2. 导航栏过滤
availableModules = MODULES.filter(m => hasModule(m.moduleCode))

// 3. 路由守卫检查
<RouteGuard requiredModule="PKB">

4. 批量导入功能

支持 Excel 导入用户：

• 模板下载
• 文件上传和解析
• 数据预览
• 批量导入
• 错误详情展示

字段映射：

• 手机号、姓名（必填）
• 邮箱、角色、租户代码、科室、模块（可选）

---

🔧 技术难点与解决方案

难点 1：UTF-8 编码损坏

挑战： 大量文档编码被破坏，无法批量恢复（会丢失新增文档）

解决方案：

1. 通过 Git 日志定位最后正常版本（4ed67a8）
2. 识别新增文档（3 个）和修改文档（~100 个）
3. 用户手动备份新增文档
4. 批量恢复修改文档
5. 用户复制回新增文档

经验教训：

• 严禁使用 PowerShell 重定向操作 UTF-8 文件
• 提交前必须检查：git diff --staged | Select-String "<22>"
• 更新 Git 提交规范 v1.2

难点 2：HTTP 查询参数类型转换

挑战： Fastify 不会自动转换查询参数类型

解决方案：

// 显式类型转换
const page = Number(query.page) || 1;
const pageSize = Number(query.pageSize) || 20;

难点 3：模块权限系统架构设计

挑战： 如何优雅地从版本系统迁移到模块权限系统

解决方案：

• 后端：登录时计算并返回 modules 字段
• 前端：AuthContext 统一管理，提供 hasModule() 方法
• 导航栏：只显示有权限的模块
• 路由守卫：检查 requiredModule 而非 requiredVersion

---

📈 代码统计

类别	新增	修改	删除	合计
后端代码	1,580	150	0	1,730
前端代码	1,870	120	30	1,960
类型定义	345	0	0	345
文档	300	5	0	305
总计	4,095	275	30	4,340

---

🧪 测试情况

功能测试

测试项	结果	备注
用户列表加载	✅ 通过	分页、搜索、筛选正常
创建用户	✅ 通过	支持模块配置
编辑用户	✅ 通过	-
启用/禁用用户	✅ 通过	状态切换正常
重置密码	✅ 通过	重置为默认密码
分配租户	✅ 通过	仅超管可操作
模块权限配置	✅ 通过	多选框正常
批量导入	✅ 通过	Excel 解析正常
模块权限系统	✅ 通过	导航栏正确过滤
登录跳转优化	✅ 通过	无权限时跳首页

权限测试

角色	数据范围	测试结果
SUPER_ADMIN	所有用户	✅ 通过
HOSPITAL_ADMIN	本租户用户	✅ 通过
PHARMA_ADMIN	本租户用户	✅ 通过
DEPARTMENT_ADMIN	本科室用户	✅ 通过
USER	无权限	✅ 通过

---

📝 遗留问题

1. pg-boss Worker 注册时序问题

现象： 后端启动时偶尔报 Queue cache is not initialized 影响： 低（重启即可恢复） 优先级： P2 计划： Phase 5 优化异步初始化流程

2. 批量导入性能

现象： 导入 100+ 用户时可能超时 影响： 低（当前场景不常见） 优先级： P3 计划： 后续支持异步导入 + 进度显示

---

🎓 经验总结

开发规范

1. ✅ 提交前必检查： git diff --staged | Select-String "<22>"
2. ✅ PowerShell 操作文件必须指定编码： -Encoding UTF8
3. ✅ HTTP 参数类型转换： Number(query.page)
4. ✅ 每日必提交： 避免代码丢失

设计模式

1. ✅ 数据隔离： 基于角色的查询范围
2. ✅ 权限分层： 系统角色 + 租户角色 + 模块权限
3. ✅ 前端极简： 只显示有权限的功能
4. ✅ 后端统一计算： 登录时返回完整权限

架构演进

1. ✅ 平台层支撑业务层： user_modules 表为所有业务模块提供权限基础
2. ✅ 可扩展性： 新增模块只需添加 modules 表记录
3. ✅ 灵活性： 支持租户级、用户级精细化配置

---

🔜 下一步计划

Phase 4.2：用户管理增强（可选）

• 用户批量操作（批量禁用、批量分配租户）
• 用户操作日志（audit_logs 集成）
• 用户统计分析（活跃度、模块使用率）

Phase 5：机构管理端开发

• 科室/部门管理
• 使用统计
• 审计日志

---

📦 交付物清单

代码

• ✅ 后端：4 个核心文件 + 1 个种子脚本
• ✅ 前端：9 个文件（3 个页面 + 3 个组件 + 3 个工具）
• ✅ 数据库：1 个新表 + 4 个权限

文档

• ✅ 本开发记录
• ✅ 运营管理端状态更新
• ✅ 系统总体状态更新
• ✅ Git 提交规范 v1.2

配置

• ✅ PUBLIC 租户开放 8 个模块
• ✅ 4 个角色的用户权限配置

---

🎉 里程碑

ADMIN 运营管理端进度：

• Phase 3.5 (Prompt 管理) - 83% ✅
• Phase 4.0 (租户管理) - 100% ✅
• Phase 4.1 (用户管理) - 100% ✅ 今日完成

下一个里程碑：

• Phase 5.0 (机构管理端) - 0%

---

开发完成时间： 2026-01-16 13:30