v0.1

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

@@ -0,0 +1,117 @@
+# 钱包扣款记录功能说明
+
+## 功能概述
+
+为钱包系统添加了简单的扣款记录功能，记录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
+
+**方法签名**:
+```go
+// 扣款方法
+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
+
+```sql
+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
+
+```go
+// 在API应用服务中
+err = s.walletService.Deduct(ctx, apiUser.UserId, subscription.Price, apiCall.ID)
+```
+
+### 查询扣款记录
+
+```go
+// 查询用户扣款记录
+transactions, err := transactionRepo.GetByUserID(ctx, userID, 10, 0)
+
+// 根据API调用ID查询扣款记录
+transaction, err := transactionRepo.GetByApiCallID(ctx, apiCallID)
+```
+
+## 依赖注入配置
+
+在容器配置中已添加钱包扣款记录仓储的依赖注入：
+
+```go
+// 钱包扣款记录仓储
+fx.Annotate(
+    finance_repo.NewGormWalletTransactionRepository,
+    fx.As(new(domain_finance_repo.WalletTransactionRepository)),
+),
+```
+
+## 优势
+
+1. **简单实用**: 只记录必要的信息
+2. **API调用关联**: 可以追踪每个API调用产生的费用
+3. **用户追踪**: 可以查看用户的扣款历史
+4. **轻量级**: 不增加系统复杂度
+
+## 注意事项
+
+1. 扣款记录创建失败不会影响钱包余额更新，确保核心业务不受影响
+2. 所有金额计算使用decimal类型，确保精度
+3. 支持软删除，便于数据恢复