[Claude Workbench] Initial commit - preserving existing code

2025-11-14 17:41:15 +08:00
commit 0f7bc05697
587 changed files with 103215 additions and 0 deletions
--- a/docs/user-membership-expiry-enhancement.md
+++ b/docs/user-membership-expiry-enhancement.md
@@ -0,0 +1,179 @@
+# 用户端会员过期检查功能完善
+
+## 问题描述
+用户端的me接口和推广粉丝接口没有正确处理会员过期情况，导致：
+1. **me接口**：会员过期后仍然显示VIP角色
+2. **推广粉丝接口**：统计付费粉丝时包含了已过期的会员
+
+## 解决方案
+
+### 1. me接口优化 (`/auth/me`)
+
+**问题**：用户会员过期后，角色仍然显示为VIP（role=2或3），误导用户。
+
+**解决**：
+- 在 `convertToUserInfoResponse` 方法中添加会员过期检查
+- 如果会员过期，显示角色降级为普通用户（role=1）
+- 添加会员过期状态字段，便于前端处理
+
+**核心逻辑**：
+```java
+// 检查会员是否过期
+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优化示例**：
+```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`
+
+**新增字段**：
+```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接口返回示例
+
+**会员未过期**：
+```json
+{
+  "code": 200,
+  "data": {
+    "role": 2,
+    "membershipType": "付费会员",
+    "membershipExpiresAt": "2024-12-31T23:59:59",
+    "isMembershipExpired": false
+  }
+}
+```
+
+**会员已过期**：
+```json
+{
+  "code": 200,
+  "data": {
+    "role": 1,
+    "membershipType": "过期会员", 
+    "membershipExpiresAt": "2024-01-01T00:00:00",
+    "isMembershipExpired": true
+  }
+}
+```
+
+### 2. 推广粉丝接口示例
+
+```bash
+# 查询当前有效的付费粉丝
+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. **增强用户体验**：用户能够清楚了解自己的会员状态
+
+所有修改都保持了向后兼容性，不会影响现有功能的正常使用。