192 lines
4.4 KiB
Markdown
192 lines
4.4 KiB
Markdown
# 充值功能说明
|
||
|
||
## 概述
|
||
|
||
本系统支持三种充值方式：
|
||
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. 赠送充值需要管理员权限 |