file-starter/.claude/commands/check-trainee-学员相关文件检查.md

---

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验证确保数据完整性
• 错误处理: 完善的错误处理和日志记录
• 事务安全: 数据库操作的事务保障

使用示例

设置用户为学员

// 后端服务调用
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'
  }
});

检查学员过期状态

// 自动在认证中间件中执行
// 手动检查
const isExpired = await userService.checkAndUpdateTraineeStatus(userId);