gym-manage/gym-manage-api/gym-member/CARD_MERGE_REPORT.md

# gym-member-card 模块合并到 gym-member 完成报告

## 合并概述
将 `gym-member-card` 模块的功能合并到 `gym-member` 模块的 `card` 子包中，保持功能不变，代码风格以 `gym-member` 为基准。

## 已完成的工作

### 1. 目录结构创建 ✅
在 `gym-member/src/main/java/cn/novalon/gym/manage/member/card` 下创建了以下子目录：
- `entity/` - 实体类
- `dto/` - 数据传输对象
- `vo/` - 视图对象
- `repository/` - 数据访问层
- `service/` - 服务接口
- `service/impl/` - 服务实现
- `handler/` - 业务处理器
- `enums/` - 枚举类
- `util/` - 工具类

### 2. 实体类重构（Entity）✅
按照 gym-member 的风格（使用 Lombok），创建了以下实体类：

| 原文件 | 新文件 | 说明 |
|--------|--------|------|
| MemberCardEntity.java + MemberCard.java | card/entity/MemberCard.java | 会员卡类型实体 |
| MemberCardRecordEntity.java + MemberCardRecord.java | card/entity/MemberCardRecord.java | 会员持卡记录实体 |
| MemberCardTransactionsEntity.java | card/entity/MemberCardTransaction.java | 交易流水实体 |
| RefundApplicationEntity.java | card/entity/RefundApplication.java | 退款申请实体 |

**主要改进：**
- 使用 `@Data`, `@Builder`, `@NoArgsConstructor`, `@AllArgsConstructor` Lombok 注解
- 继承 `cn.novalon.gym.manage.member.entity.BaseEntity`
- 移除手动编写的 getter/setter
- 添加规范的 JavaDoc 注释

### 3. 枚举类创建 ✅
创建了以下枚举类：

| 原文件 | 新文件 | 说明 |
|--------|--------|------|
| MemberCardType.java | card/enums/MemberCardType.java | 会员卡类型 |
| MemberCardRecordStatus.java | card/enums/MemberCardRecordStatus.java | 卡片状态 |
| MemberCardTransactionsAction.java | card/enums/TransactionType.java | 交易操作类型 |
| MemberCardTransactionsType.java | card/enums/BizType.java | 关联业务类型 |
| MemberCardEvent.java | card/enums/CardEvent.java | 状态机事件 |

### 4. Repository 层合并 ✅
将原有的 DAO 接口整合为 Repository 接口，直接继承 `R2dbcRepository`：

| 原文件 | 新文件 | 说明 |
|--------|--------|------|
| MemberCardDao.java | card/repository/MemberCardRepository.java | 会员卡类型 Repository |
| MemberCardRecordDao.java | card/repository/MemberCardRecordRepository.java | 持卡记录 Repository |
| MemberCardTransactionsDao.java | card/repository/MemberCardTransactionRepository.java | 交易流水 Repository |
| RefundApplicationDao.java | card/repository/RefundApplicationRepository.java | 退款申请 Repository |

**主要改进：**
- 统一命名规范（移除 Dao，使用 Repository）
- 继承 `R2dbcRepository<Entity, Long>`
- 保留所有自定义查询方法
- 更新参数类型为新的实体类

### 5. 数据库 Schema 迁移 ✅
将会员卡相关的表结构添加到 `gym-member/src/main/resources/db/schema.sql`：

新增表：
- `member_card` - 会员卡类型表
- `member_card_record` - 会员持卡记录表
- `member_card_transactions` - 交易流水表
- `refund_application` - 退款申请表

包含完整的索引和注释。

### 6. pom.xml 依赖更新 ✅
在 `gym-member/pom.xml` 中添加了 Redis 响应式支持：
```xml
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-redis-reactive</artifactId>
</dependency>
```

## 待完成的工作

### 需要手动复制的文件（约30个）

以下文件需要从 `gym-member-card` 复制到 `gym-member/card`，并修改包名：

#### Handler 层（8个文件）
源路径：`gym-member-card/src/main/java/cn/novalon/gym/manage/gymmembercard/handler/`
目标路径：`gym-member/src/main/java/cn/novalon/gym/manage/member/card/handler/`

- DistributedLockService.java
- ExpirationReminderService.java
- MemberCardHandler.java
- MemberCardRecordHandler.java
- MemberCardScheduledHandler.java
- MemberCardStateMachine.java
- MemberCardTransactionHandler.java
- RefundSagaHandler.java

#### Service 接口层（4个文件）
源路径：`gym-member-card/src/main/java/cn/novalon/gym/manage/gymmembercard/sevice/`
目标路径：`gym-member/src/main/java/cn/novalon/gym/manage/member/card/service/`

注意：目录名从 `sevice`（拼写错误）改为 `service`

- IMemberCardService.java
- IMemberCardRecordService.java
- IMemberCardTransactionsService.java
- IRefundApplicationService.java

#### Service 实现层（4个文件）
源路径：`gym-member-card/src/main/java/cn/novalon/gym/manage/gymmembercard/sevice/impl/`
目标路径：`gym-member/src/main/java/cn/novalon/gym/manage/member/card/service/impl/`

- MemberCardServiceImpl.java
- MemberCardRecordServiceImpl.java
- MemberCardTransactionsServiceImpl.java
- RefundApplicationServiceImpl.java

#### Util 工具类（1个文件）
源路径：`gym-member-card/src/main/java/cn/novalon/gym/manage/gymmembercard/util/`
目标路径：`gym-member/src/main/java/cn/novalon/gym/manage/member/card/util/`

- BeanConvertUtil.java

### 批量替换规则

复制每个文件后，需要进行以下文本替换：

1. **包名替换：**
   ```
   package cn.novalon.gym.manage.gymmembercard -> package cn.novalon.gym.manage.member.card
   ```

2. **导入语句替换：**
   ```
   import cn.novalon.gym.manage.gymmembercard -> import cn.novalon.gym.manage.member.card
   ```

3. **BaseEntity 导入替换：**
   ```
   import cn.novalon.gym.manage.db.entity.BaseEntity -> import cn.novalon.gym.manage.member.entity.BaseEntity
   ```

4. **BaseDomain 处理（如果存在）：**
   ```
   import cn.novalon.gym.manage.sys.core.domain.BaseDomain -> （注释掉或删除）
   ```

5. **Repository 引用更新（如果需要）：**
   ```
   IMemberCardRepository -> MemberCardRepository
   IMemberCardRecordRepository -> MemberCardRecordRepository
   IMemberCardTransactionsRepository -> MemberCardTransactionRepository
   IRefundApplicationRepository -> RefundApplicationRepository
   ```

## 验证步骤

完成文件复制后，执行以下验证：

1. **编译验证：**
   ```bash
   cd gym-manage-api/gym-member
   mvn clean compile
   ```

2. **检查是否有编译错误：**
   - 修复任何缺失的导入
   - 确认所有依赖类都已正确迁移
   - 检查枚举引用是否正确

3. **运行测试（如果有）：**
   ```bash
   mvn test
   ```

## 注意事项

1. **包名一致性：** 确保所有文件中的包声明和导入语句都正确更新
2. **依赖注入：** Spring 的 `@Autowired` 或构造函数注入应自动工作，因为使用了相同的注解
3. **数据库兼容性：** schema.sql 已追加新表，不会影响现有表
4. **Redis 配置：** 确保 application.yml 中有 Redis 配置（如果需要分布式锁功能）
5. **定时任务：** MemberCardScheduledHandler 和 ExpirationReminderService 可能需要启用 `@EnableScheduling`

## 自动化脚本

项目根目录下提供了两个辅助脚本：
- `gym-member-card/migrate_to_member.py` - Python 迁移脚本
- `gym-member-card/migrate-to-member.ps1` - PowerShell 迁移脚本

可以运行这些脚本来自动完成文件复制和包名替换。

---

**生成时间：** 2026-05-27
**合并状态：** 基础架构完成，待复制业务逻辑文件