---
description: "学员相关文件检查指令"
---

本指令用于检查项目中学员相关的文件实现情况，为后续学员功能开发和维护提供上下文信息。

## 检查范围

### 1. 用户实体和Schema (`src/server/modules/users/`)
- **user.entity.ts**: 用户实体类，包含学员有效期字段定义
- **user.schema.ts**: 用户数据验证Schema，包含学员相关字段验证
- **user.enum.ts**: 用户类型枚举，包含TRAINEE类型定义

### 2. 用户服务 (`src/server/modules/users/user.service.ts`)
- 学员身份管理功能：设置学员、撤销学员、更新学员有效期
- 学员过期状态检查功能

### 3. 学员过期检查中间件 (`src/server/middleware/trainee-expiry.middleware.ts`)
- 认证后立即检查学员过期状态
- 自动更新过期学员身份

### 4. 用户管理页面 (`src/client/admin/pages/Users.tsx`)
- 学员设置和撤销功能界面
- 学员有效期显示和管理

### 5. 认证中间件 (`src/server/middleware/auth.middleware.ts`)
- 集成学员过期检查功能

## 详细检查结果

### 用户实体实现情况

#### user.entity.ts (数据库实体)
- ✅ **学员有效期字段**: `traineeValidFrom` (有效期开始时间)
- ✅ **学员有效期字段**: `traineeValidTo` (有效期结束时间)  
- ✅ **用户类型字段**: `userType` 支持 TRAINEE 类型
- ✅ **字段注释**: 所有字段都有中文注释说明

#### user.schema.ts (数据验证)
- ✅ **学员字段验证**: `traineeValidFrom` 和 `traineeValidTo` 使用 `z.coerce.date()` 验证
- ✅ **OpenAPI元数据**: 包含完整的示例值和描述信息
- ✅ **类型转换**: 支持字符串到日期的自动转换

#### user.enum.ts (用户类型枚举)
- ✅ **TRAINEE类型**: 定义学员用户类型常量
- ✅ **完整类型体系**: TEACHER、STUDENT、TRAINEE 三种用户类型

### 用户服务实现情况

#### user.service.ts (业务逻辑)
- ✅ **设置学员身份**: `setUserAsTrainee()` - 设置用户为学员并指定有效期
- ✅ **撤销学员身份**: `removeUserTraineeStatus()` - 将学员恢复为学生身份
- ✅ **更新学员有效期**: `updateTraineeValidity()` - 修改学员的有效期
- ✅ **过期状态检查**: `checkAndUpdateTraineeStatus()` - 自动检查并处理过期学员
- ✅ **事务安全**: 所有操作都包含错误处理和日志记录

### 中间件实现情况

#### trainee-expiry.middleware.ts (过期检查)
- ✅ **立即检查**: 在认证成功后立即执行学员过期检查
- ✅ **自动更新**: 检测到过期学员后自动更新用户类型
- ✅ **上下文更新**: 更新认证上下文中的用户信息

#### auth.middleware.ts (认证集成)
- ✅ **中间件集成**: 在认证流程中集成学员过期检查
- ✅ **无缝衔接**: 用户认证后自动进行学员状态验证

### 前端管理界面实现情况

#### Users.tsx (用户管理)
- ✅ **学员状态显示**: 在用户列表中显示学员有效期信息
- ✅ **设置学员功能**: 提供设置用户为学员的对话框界面
- ✅ **撤销学员功能**: 提供撤销学员身份的确认对话框
- ✅ **日期选择器**: 支持选择学员有效期的开始和结束时间
- ✅ **状态反馈**: 使用toast消息提示操作结果

## 功能特性

### 已实现功能
1. **学员身份管理**
   - 设置用户为学员并指定有效期
   - 撤销学员身份恢复为学生
   - 更新学员有效期

2. **自动过期处理**
   - 认证时自动检查学员过期状态
   - 过期学员自动恢复为学生身份
   - 实时更新用户上下文信息

3. **管理界面**
   - 可视化设置和撤销学员身份
   - 学员有效期显示和管理
   - 操作结果反馈

### 技术实现
- **数据库字段**: 使用timestamp类型存储有效期时间
- **类型安全**: 完整的TypeScript类型定义
- **验证机制**: Zod schema验证确保数据完整性
- **错误处理**: 完善的错误处理和日志记录
- **事务安全**: 数据库操作的事务保障

## 使用示例

### 设置用户为学员
```typescript
// 后端服务调用
const userService = new UserService(dataSource);
const updatedUser = await userService.setUserAsTrainee(
  userId, 
  new Date('2024-01-01'), 
  new Date('2024-12-31'),
  operatorId
);

// 前端API调用  
const res = await userClient[':id']['$put']({
  param: { id: userId },
  json: {
    userType: UserType.TRAINEE,
    traineeValidFrom: '2024-01-01T00:00:00Z',
    traineeValidTo: '2024-12-31T23:59:59Z'
  }
});
```

### 检查学员过期状态
```typescript
// 自动在认证中间件中执行
// 手动检查
const isExpired = await userService.checkAndUpdateTraineeStatus(userId);
```