tyapi-server/docs/服务重构说明.md

# 钱包聚合服务重构说明

## 重构概述

本次重构将钱包聚合服务中的充值记录相关功能提取到独立的充值记录服务中，实现了更好的职责分离和代码组织。

## 重构内容

### 1. 新增服务

#### RechargeRecordService (充值记录服务)
- **文件位置**: `internal/domains/finance/services/recharge_record_service.go`
- **职责**: 专门处理所有充值记录相关的业务逻辑

**主要功能**:
- 对公转账充值 (`TransferRecharge`)
- 赠送充值 (`GiftRecharge`)
- 支付宝充值记录创建 (`CreateAlipayRecharge`)
- 支付宝订单管理 (`CreateAlipayOrder`)
- 支付宝支付成功回调处理 (`HandleAlipayPaymentSuccess`)
- 充值记录查询 (`GetByID`, `GetByUserID`, `GetByTransferOrderID`)

### 2. 重构的服务

#### WalletAggregateService (钱包聚合服务)
- **文件位置**: `internal/domains/finance/services/wallet_aggregate_service.go`
- **重构后职责**: 专注于钱包核心功能

**保留功能**:
- 钱包创建 (`CreateWallet`)
- 通用充值 (`Recharge`)
- 扣款 (`Deduct`)
- 余额查询 (`GetBalance`)
- 钱包加载 (`LoadWalletByUserId`)

**移除功能**:
- 对公转账充值
- 赠送充值
- 支付宝充值记录管理
- 支付宝订单管理
- 支付宝回调处理

### 3. 应用服务层更新

#### FinanceApplicationService
- **文件位置**: `internal/application/finance/finance_application_service_impl.go`
- **更新内容**: 添加对 `RechargeRecordService` 的依赖

**修改的方法**:
- `TransferRecharge`: 改为调用 `rechargeRecordService.TransferRecharge`
- `GiftRecharge`: 改为调用 `rechargeRecordService.GiftRecharge`
- `CreateAlipayRechargeOrder`: 改为调用 `rechargeRecordService.CreateAlipayRecharge`
- `CreateAlipayOrderRecord`: 改为调用 `rechargeRecordService.CreateAlipayOrder`
- `GetRechargeRecordByAlipayOrderID`: 改为调用 `rechargeRecordService.GetRechargeRecordByAlipayOrderID`
- `HandleAlipayPaymentSuccess`: 改为调用 `rechargeRecordService.HandleAlipayPaymentSuccess`

### 4. 依赖注入更新

#### Container
- **文件位置**: `internal/container/container.go`
- **更新内容**: 添加 `finance_service.NewRechargeRecordService` 的依赖注入

## 重构优势

### 1. 职责分离
- **钱包聚合服务**: 专注于钱包核心功能（创建、充值、扣款、查询）
- **充值记录服务**: 专注于充值记录管理（各种充值方式、订单管理）

### 2. 代码组织
- 相关功能聚合在一起，提高代码可读性
- 减少单个服务的复杂度
- 便于维护和测试

### 3. 扩展性
- 新增充值方式时，只需要在充值记录服务中添加
- 钱包核心功能与充值方式解耦

### 4. 测试友好
- 可以独立测试钱包功能和充值记录功能
- 减少测试的复杂度

## 接口变更

### 钱包聚合服务接口变更
```go
// 移除的方法
TransferRecharge(ctx context.Context, userID string, amount decimal.Decimal, transferOrderID, notes string) (*entities.RechargeRecord, error)
GiftRecharge(ctx context.Context, userID string, amount decimal.Decimal, giftReason, operatorID, notes string) (*entities.RechargeRecord, error)
CreateAlipayRecharge(ctx context.Context, userID string, amount decimal.Decimal, alipayOrderID string) (*entities.RechargeRecord, error)
CreateAlipayOrder(ctx context.Context, rechargeID, outTradeNo, subject string, amount decimal.Decimal, platform string) error
GetRechargeRecordByAlipayOrderID(ctx context.Context, alipayOrderID string) (*entities.RechargeRecord, error)
HandleAlipayPaymentSuccess(ctx context.Context, outTradeNo string, amount decimal.Decimal, tradeNo string) error

// 保留的方法
CreateWallet(ctx context.Context, userID string) (*entities.Wallet, error)
Recharge(ctx context.Context, userID string, amount decimal.Decimal) error
Deduct(ctx context.Context, userID string, amount decimal.Decimal, apiCallID, transactionID, productID string) error
GetBalance(ctx context.Context, userID string) (decimal.Decimal, error)
LoadWalletByUserId(ctx context.Context, userID string) (*entities.Wallet, error)
```

### 新增充值记录服务接口
```go
type RechargeRecordService interface {
    // 对公转账充值
    TransferRecharge(ctx context.Context, userID string, amount decimal.Decimal, transferOrderID, notes string) (*entities.RechargeRecord, error)
    
    // 赠送充值
    GiftRecharge(ctx context.Context, userID string, amount decimal.Decimal, giftReason, operatorID, notes string) (*entities.RechargeRecord, error)
    
    // 支付宝充值
    CreateAlipayRecharge(ctx context.Context, userID string, amount decimal.Decimal, alipayOrderID string) (*entities.RechargeRecord, error)
    GetRechargeRecordByAlipayOrderID(ctx context.Context, alipayOrderID string) (*entities.RechargeRecord, error)
    
    // 支付宝订单管理
    CreateAlipayOrder(ctx context.Context, rechargeID, outTradeNo, subject string, amount decimal.Decimal, platform string) error
    HandleAlipayPaymentSuccess(ctx context.Context, outTradeNo string, amount decimal.Decimal, tradeNo string) error
    
    // 通用查询
    GetByID(ctx context.Context, id string) (*entities.RechargeRecord, error)
    GetByUserID(ctx context.Context, userID string) ([]entities.RechargeRecord, error)
    GetByTransferOrderID(ctx context.Context, transferOrderID string) (*entities.RechargeRecord, error)
}
```

## 注意事项

1. **向后兼容性**: 应用服务层的公共接口保持不变，对调用方透明
2. **事务处理**: 充值记录服务中的方法仍然保持原有的事务处理逻辑
3. **错误处理**: 保持原有的错误处理机制和日志记录
4. **依赖关系**: 充值记录服务依赖钱包仓储来更新钱包余额

## 后续优化建议

1. **实体扩展**: 考虑在 `RechargeRecord` 实体中添加 `GiftReason` 和 `OperatorID` 字段
2. **事件驱动**: 考虑使用事件驱动架构来处理充值成功后的业务逻辑
3. **缓存优化**: 对频繁查询的充值记录添加缓存机制
4. **监控指标**: 添加充值相关的业务监控指标