1818web-hoduan/docs/user-membership-expiry-enhancement.md

用户端会员过期检查功能完善

问题描述

用户端的me接口和推广粉丝接口没有正确处理会员过期情况，导致：

1. me接口：会员过期后仍然显示VIP角色
2. 推广粉丝接口：统计付费粉丝时包含了已过期的会员

解决方案

1. me接口优化 (/auth/me)

问题：用户会员过期后，角色仍然显示为VIP（role=2或3），误导用户。

解决：

• 在 convertToUserInfoResponse 方法中添加会员过期检查
• 如果会员过期，显示角色降级为普通用户（role=1）
• 添加会员过期状态字段，便于前端处理

核心逻辑：

// 检查会员是否过期
if (user.getRole() > 1) {
    if (user.getMembershipExpiresAt() == null || 
        user.getMembershipExpiresAt().isBefore(LocalDateTime.now())) {
        isMembershipExpired = true;
        displayRole = 1; // 过期会员降级为普通用户
    }
}

2. 推广粉丝接口优化 (/user/promotion/fans)

问题：查询付费粉丝时包含已过期的会员，导致统计数据不准确。

解决：

• 更新 UserMapper.xml 中的粉丝查询SQL
• 所有会员状态判断都添加 membership_expires_at 检查
• 新增 expired 状态，支持查询过期会员

SQL优化示例：

-- 原逻辑：只检查角色和订单记录
WHEN EXISTS (SELECT 1 FROM `order` ...) THEN 'paid'

-- 新逻辑：同时检查会员是否在有效期内
WHEN u.role > 1 
     AND u.membership_expires_at IS NOT NULL 
     AND u.membership_expires_at > NOW()
     AND EXISTS (SELECT 1 FROM `order` ...) THEN 'paid'

修改详情

1. UserService 修改

文件：src/main/java/com/dora/service/impl/UserServiceImpl.java

关键改动：

• 修改 convertToUserInfoResponse() 方法
• 添加会员过期检查逻辑
• 动态调整返回的角色信息
• 添加 isMembershipExpired 字段

2. DTO 增强

文件：src/main/java/com/dora/dto/AuthDto.java

新增字段：

@Schema(description = "会员是否已过期", example = "false")
private Boolean isMembershipExpired;

3. 粉丝查询SQL优化

文件：src/main/resources/mapper/UserMapper.xml

关键改动：

• 所有会员状态判断添加过期时间检查
• 支持新的 expired 状态查询
• 更新会员状态显示文本

新支持的状态：

• paid - 当前有效付费会员
• exchange - 当前有效兑换会员
• gift - 赠送会员（有效期内）
• expired - 过期会员
• none - 非VIP用户
• all - 所有粉丝

4. 接口文档更新

文件：src/main/java/com/dora/controller/PromotionController.java

更新内容：

• 参数描述明确区分当前有效会员和过期会员
• 添加会员过期检查说明

使用示例

1. me接口返回示例

会员未过期：

{
  "code": 200,
  "data": {
    "role": 2,
    "membershipType": "付费会员",
    "membershipExpiresAt": "2024-12-31T23:59:59",
    "isMembershipExpired": false
  }
}

会员已过期：

{
  "code": 200,
  "data": {
    "role": 1,
    "membershipType": "过期会员", 
    "membershipExpiresAt": "2024-01-01T00:00:00",
    "isMembershipExpired": true
  }
}

2. 推广粉丝接口示例

# 查询当前有效的付费粉丝
GET /user/promotion/fans?status=paid

# 查询过期会员粉丝
GET /user/promotion/fans?status=expired

# 查询所有粉丝（包含过期状态标识）
GET /user/promotion/fans?status=all

业务影响

正面影响

1. 用户体验优化：准确显示当前会员状态，避免用户误解
2. 数据准确性：推广统计更加精确，有助于业务决策
3. 系统一致性：前后端数据状态保持一致

注意事项

1. 向后兼容：原有API调用方式保持不变
2. 前端适配：前端可能需要处理新的过期状态字段
3. 数据库角色：数据库中的角色字段不会被修改，只影响接口返回

测试建议

1. me接口测试

• 创建即将过期的测试用户
• 验证过期前后接口返回的差异
• 确认角色显示和状态字段的正确性

2. 推广粉丝接口测试

• 创建不同类型的粉丝（付费、兑换、过期）
• 验证各种状态筛选的准确性
• 确认统计数字的正确性

3. 边界条件测试

• 会员到期时间为NULL的情况
• 恰好在过期时间点的用户
• 兑换后又付费的复合情况

总结

这次优化确保了用户端接口能够正确处理会员过期情况，提供了准确的用户状态信息和推广统计数据。通过细致的会员有效期检查，系统现在能够：

1. 准确反映用户身份：过期会员不再显示为VIP
2. 精确统计数据：推广收益计算更加准确
3. 增强用户体验：用户能够清楚了解自己的会员状态

所有修改都保持了向后兼容性，不会影响现有功能的正常使用。