📝 docs(commands): 完善学员文件检查指令文档

- 重构文档结构，增加检查范围、详细结果、功能特性和使用示例等章节
- 补充各文件实现情况的详细检查结果，使用✅标记已实现功能
- 添加学员身份管理、自动过期处理和管理界面等功能特性说明
- 提供设置学员身份和检查过期状态的代码示例
- 完善用户实体、服务、中间件和前端界面的检查内容描述

.roo/commands/check-trainee-学员相关文件检查.md

@@ -2,22 +2,130 @@
 description: "学员相关文件检查指令"
 ---
 
-学员相关文件检查，为后续学员相关开发提供上下文
+本指令用于检查项目中学员相关的文件实现情况，为后续学员功能开发和维护提供上下文信息。
 
-先检查：
-    用户实体和schema：
-    src/server/modules/users/user.entity.ts
-    src/server/modules/users/user.schema.ts
-    src/server/modules/users/user.enum.ts
+## 检查范围
 
-    用户服务中的学员功能：
-    src/server/modules/users/user.service.ts
+### 1. 用户实体和Schema (`src/server/modules/users/`)
+- **user.entity.ts**: 用户实体类，包含学员有效期字段定义
+- **user.schema.ts**: 用户数据验证Schema，包含学员相关字段验证
+- **user.enum.ts**: 用户类型枚举，包含TRAINEE类型定义
 
-    学员过期检查中间件：
-    src/server/middleware/trainee-expiry.middleware.ts
+### 2. 用户服务 (`src/server/modules/users/user.service.ts`)
+- 学员身份管理功能：设置学员、撤销学员、更新学员有效期
+- 学员过期状态检查功能
 
-    用户管理页面中的学员功能：
-    src/client/admin/pages/Users.tsx
+### 3. 学员过期检查中间件 (`src/server/middleware/trainee-expiry.middleware.ts`)
+- 认证后立即检查学员过期状态
+- 自动更新过期学员身份
 
-    认证中间件中的学员检查：
-    src/server/middleware/auth.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);
+```