# 充值功能说明

## 概述

本系统支持三种充值方式：
1. **支付宝充值** - 通过支付宝进行在线充值（待实现）
2. **对公转账** - 通过银行转账进行充值
3. **赠送充值** - 管理员为用户进行赠送充值

## 功能架构

### 实体层 (Entities)
- `RechargeRecord` - 充值记录实体
- `Wallet` - 钱包实体
- `WalletTransaction` - 钱包交易记录实体

### 领域服务层 (Domain Services)
- `WalletAggregateService` - 钱包聚合服务，处理充值业务逻辑

### 应用服务层 (Application Services)
- `FinanceApplicationService` - 财务应用服务，协调充值操作

### HTTP层 (HTTP Handlers)
- `FinanceHandler` - 财务HTTP处理器，提供REST API接口

## API接口

### 1. 对公转账充值

**接口地址：** `POST /api/v1/finance/wallet/transfer-recharge`

**请求参数：**
```json
{
  "amount": "100.00",
  "transfer_order_id": "TR202412010001",
  "bank_account": "6222021234567890123",
  "bank_name": "中国工商银行",
  "notes": "转账备注"
}
```

**响应示例：**
```json
{
  "code": 200,
  "message": "对公转账充值成功",
  "data": {
    "id": "uuid",
    "user_id": "user_uuid",
    "amount": "100.00",
    "recharge_type": "transfer",
    "status": "success",
    "transfer_order_id": "TR202412010001",
    "bank_account": "6222021234567890123",
    "bank_name": "中国工商银行",
    "notes": "转账备注",
    "created_at": "2024-12-01T10:00:00Z",
    "updated_at": "2024-12-01T10:00:00Z"
  }
}
```

### 2. 赠送充值

**接口地址：** `POST /api/v1/finance/wallet/gift-recharge`

**请求参数：**
```json
{
  "amount": "50.00",
  "gift_reason": "新用户注册奖励",
  "notes": "系统自动赠送"
}
```

**响应示例：**
```json
{
  "code": 200,
  "message": "赠送充值成功",
  "data": {
    "id": "uuid",
    "user_id": "user_uuid",
    "amount": "50.00",
    "recharge_type": "gift",
    "status": "success",
    "gift_reason": "新用户注册奖励",
    "operator_id": "system",
    "notes": "系统自动赠送",
    "created_at": "2024-12-01T10:00:00Z",
    "updated_at": "2024-12-01T10:00:00Z"
  }
}
```

### 3. 通用充值（保留接口）

**接口地址：** `POST /api/v1/finance/wallet/recharge`

**请求参数：**
```json
{
  "amount": "200.00"
}
```

## 业务规则

### 对公转账充值
1. 转账订单号必须唯一，不能重复使用
2. 充值成功后立即更新钱包余额
3. 充值记录状态标记为成功

### 赠送充值
1. 赠送充值直接标记为成功状态
2. 立即更新钱包余额
3. 记录操作员ID（当前为"system"）

### 通用规则
1. 充值金额必须大于0
2. 用户必须存在钱包
3. 使用乐观锁防止并发问题
4. 所有操作都有详细的日志记录

## 数据库表结构

### recharge_records 表
```sql
CREATE TABLE recharge_records (
    id VARCHAR(36) PRIMARY KEY,
    user_id VARCHAR(36) NOT NULL,
    amount DECIMAL(20,8) NOT NULL,
    recharge_type VARCHAR(20) NOT NULL,
    status VARCHAR(20) NOT NULL DEFAULT 'pending',
    alipay_order_id VARCHAR(64),
    transfer_order_id VARCHAR(64),
    bank_account VARCHAR(100),
    bank_name VARCHAR(100),
    gift_reason VARCHAR(200),
    notes TEXT,
    operator_id VARCHAR(36),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    deleted_at TIMESTAMP NULL,
    INDEX idx_user_id (user_id),
    INDEX idx_recharge_type (recharge_type),
    INDEX idx_status (status),
    INDEX idx_alipay_order_id (alipay_order_id),
    INDEX idx_transfer_order_id (transfer_order_id)
);
```

## 错误处理

### 常见错误码
- `400` - 请求参数错误
- `401` - 用户未登录
- `409` - 转账订单号已存在
- `500` - 服务器内部错误

### 错误消息示例
```json
{
  "code": 409,
  "message": "转账订单号已存在",
  "data": null
}
```

## 后续开发计划

1. **支付宝充值功能**
   - 集成支付宝支付接口
   - 实现支付回调处理
   - 添加支付状态查询接口

2. **充值记录查询**
   - 添加充值记录列表查询接口
   - 支持按用户、类型、状态等条件筛选

3. **充值统计功能**
   - 添加充值金额统计
   - 支持按时间段统计充值情况

## 注意事项

1. 所有金额计算使用 `decimal.Decimal` 类型，确保精度
2. 使用乐观锁机制防止并发充值问题
3. 充值操作都有完整的日志记录
4. 对公转账充值需要人工审核确认
5. 赠送充值需要管理员权限