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%）

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

**旧系统（废弃）：**
```typescript
// 基于版本等级（basic/advanced/premium）
requiredVersion: 'basic'
checkModulePermission(requiredVersion)
```

**新系统（启用）：**
```typescript
// 基于模块代码（AIA/PKB/RVW等）
requiredModule: 'PKB'
hasModule(moduleCode)
```

#### 后端改造
**文件：** `backend/src/common/auth/auth.service.ts`

1. **新增方法：** `getUserModules(userId)`
   - 查询用户所有租户关系
   - 对每个租户，检查租户订阅的模块
   - 如果用户有自定义模块权限，使用自定义权限
   - 否则继承租户的全部模块权限
   - 去重后返回所有可访问模块

2. **修改登录响应：**
   ```typescript
   // 登录成功返回
   {
     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`
  ```typescript
  <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`
```typescript
const page = Number(query.page) || 1;
const pageSize = Number(query.pageSize) || 20;
```

### 3. 前端编译错误修复

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

### 4. 登录跳转逻辑优化

**问题：** 普通用户修改密码后跳转到 `/admin/users`，显示 403
**修复：** 智能跳转逻辑
```typescript
// 检查用户角色是否有权限访问目标页面
// 无权限时自动跳转到首页
```

---

## 📊 技术亮点

### 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. 前端模块权限系统

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

**实现要点：**
```typescript
// 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 不会自动转换查询参数类型

**解决方案：**
```typescript
// 显式类型转换
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