tyapi-server/docs/充值功能说明.md

充值功能说明

概述

本系统支持三种充值方式：

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

请求参数：

{
  "amount": "100.00",
  "transfer_order_id": "TR202412010001",
  "bank_account": "6222021234567890123",
  "bank_name": "中国工商银行",
  "notes": "转账备注"
}

响应示例：

{
  "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

请求参数：

{
  "amount": "50.00",
  "gift_reason": "新用户注册奖励",
  "notes": "系统自动赠送"
}

响应示例：

{
  "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

请求参数：

{
  "amount": "200.00"
}

业务规则

对公转账充值

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

赠送充值

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

通用规则

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

数据库表结构

recharge_records 表

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 - 服务器内部错误

错误消息示例

{
  "code": 409,
  "message": "转账订单号已存在",
  "data": null
}

后续开发计划

1. 支付宝充值功能

   • 集成支付宝支付接口
   • 实现支付回调处理
   • 添加支付状态查询接口

2. 充值记录查询

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

3. 充值统计功能

   • 添加充值金额统计
   • 支持按时间段统计充值情况

注意事项

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