tyapi-server/docs/钱包交易记录功能说明.md

钱包扣款记录功能说明

功能概述

为钱包系统添加了简单的扣款记录功能，记录API调用产生的扣款操作，包含扣款金额、用户ID和关联的ApiCallID。

新增功能

1. 钱包扣款记录实体 (WalletTransaction)

位置: internal/domains/finance/entities/wallet_transaction.go

主要字段:

• ID: 扣款记录唯一标识
• UserID: 扣款用户ID
• ApiCallID: 关联API调用ID
• Amount: 扣款金额
• CreatedAt: 创建时间

2. 钱包扣款记录仓储

接口: internal/domains/finance/repositories/wallet_transaction_repository_interface.go 实现: internal/infrastructure/database/repositories/finance/gorm_wallet_transaction_repository.go

主要方法:

• Create: 创建扣款记录
• GetByUserID: 根据用户ID获取扣款记录
• GetByApiCallID: 根据API调用ID获取扣款记录

3. 钱包聚合服务更新

位置: internal/domains/finance/services/wallet_aggregate_service.go

更新内容:

• 添加了交易记录仓储依赖
• 更新了Deduct方法，支持记录扣款并关联ApiCall

方法签名:

// 扣款方法
Deduct(ctx context.Context, userID string, amount decimal.Decimal, apiCallID string) error

4. API应用服务更新

位置: internal/application/api/api_application_service.go

更新内容:

• 更新了API调用中的扣款逻辑，现在会记录扣款并关联ApiCall

数据库变更

新增表: wallet_transactions

CREATE TABLE wallet_transactions (
    id VARCHAR(36) PRIMARY KEY,
    user_id VARCHAR(36) NOT NULL,
    api_call_id VARCHAR(64) NOT NULL,
    amount DECIMAL(20,8) NOT NULL,
    created_at TIMESTAMP NOT NULL,
    updated_at TIMESTAMP NOT NULL,
    deleted_at TIMESTAMP,
    INDEX idx_user_id (user_id),
    INDEX idx_api_call_id (api_call_id),
    INDEX idx_created_at (created_at)
);

使用示例

API调用扣款

当用户调用API时，系统会自动：

1. 验证用户钱包余额
2. 扣减相应费用
3. 创建扣款记录，关联ApiCall

// 在API应用服务中
err = s.walletService.Deduct(ctx, apiUser.UserId, subscription.Price, apiCall.ID)

查询扣款记录

// 查询用户扣款记录
transactions, err := transactionRepo.GetByUserID(ctx, userID, 10, 0)

// 根据API调用ID查询扣款记录
transaction, err := transactionRepo.GetByApiCallID(ctx, apiCallID)

依赖注入配置

在容器配置中已添加钱包扣款记录仓储的依赖注入：

// 钱包扣款记录仓储
fx.Annotate(
    finance_repo.NewGormWalletTransactionRepository,
    fx.As(new(domain_finance_repo.WalletTransactionRepository)),
),

优势

1. 简单实用: 只记录必要的信息
2. API调用关联: 可以追踪每个API调用产生的费用
3. 用户追踪: 可以查看用户的扣款历史
4. 轻量级: 不增加系统复杂度

注意事项

1. 扣款记录创建失败不会影响钱包余额更新，确保核心业务不受影响
2. 所有金额计算使用decimal类型，确保精度
3. 支持软删除，便于数据恢复