96ed936079
- 新增API端点参考文档，涵盖权限、卡密、订单、商户、监控、限制等模块 - 详细说明Apple卡密充值处理流程，包括提交、查询、回调和轮询接口 - 描述充值订单状态机及生命周期，支持超时重试和状态迁移 - 介绍签名验证、幂等控制及重复卡密防刷单策略 - 增加商户配置管理、历史记录查询和错误处理机制说明 - 提供API使用示例代码及客户端实现指导 - 删除过时的.drone.yml.bak文件，清理无用配置 - 添加.dockerignore忽略指定目录和文件
10 KiB
资金流水
**本文档中引用的文件** - [wallet_log.go](file://api/fund/v1/wallet_log.go) - [fund_v1_menu_log_list.go](file://internal/controller/fund/fund_v1_menu_log_list.go) - [fund_v1_menu_log_create.go](file://internal/controller/fund/fund_v1_menu_log_create.go) - [fund_v1_menu_log_update.go](file://internal/controller/fund/fund_v1_menu_log_update.go) - [fund_v1_menu_log_delete.go](file://internal/controller/fund/fund_v1_menu_log_delete.go) - [sys_user_payment.go](file://internal/service/sys_user_payment.go) - [record.go](file://internal/logic/sys_user_payment/record.go) - [v_1_sys_user_payment_records.go](file://internal/dao/v_1_sys_user_payment_records.go) - [V1SysUserPaymentRecords.go](file://internal/model/do/v_1_sys_user_payment_records.go) - [V1SysUserPaymentRecords.go](file://internal/model/entity/v_1_sys_user_payment_records.go) - [SysUserPaymentRecordInput.go](file://internal/model/sys_user_payment_record.go)目录
简介
本文档详细描述了资金流水API的实现，涵盖资金流水记录的创建、查询、更新和删除等操作。文档详细说明了每个端点的HTTP方法、URL模式、请求/响应模式和认证机制。同时，文档还解释了资金流水的实现细节，包括流水号生成规则、对账机制和数据一致性保障，并提供客户端实现指南和性能优化建议。
项目结构
资金流水功能主要位于api/fund/v1目录下，相关控制器位于internal/controller/fund目录，服务逻辑位于internal/service和internal/logic目录，数据访问对象（DAO）和模型定义位于internal/dao和internal/model目录。
graph TB
subgraph "API 层"
A[wallet_log.go]
end
subgraph "控制器层"
B[fund_v1_menu_log_list.go]
C[fund_v1_menu_log_create.go]
D[fund_v1_menu_log_update.go]
E[fund_v1_menu_log_delete.go]
end
subgraph "服务层"
F[sys_user_payment.go]
end
subgraph "逻辑层"
G[record.go]
end
subgraph "数据访问层"
H[v_1_sys_user_payment_records.go]
end
subgraph "模型层"
I[V1SysUserPaymentRecords.go]
J[SysUserPaymentRecordInput.go]
end
A --> B
A --> C
A --> D
A --> E
B --> F
C --> F
D --> F
E --> F
F --> G
G --> H
H --> I
F --> J
图示来源
- wallet_log.go
- fund_v1_menu_log_list.go
- sys_user_payment.go
- record.go
- v_1_sys_user_payment_records.go
- V1SysUserPaymentRecords.go
- SysUserPaymentRecordInput.go
节来源
核心组件
资金流水功能的核心组件包括API定义、服务接口、数据访问对象和数据库模型。API定义了四个主要操作：创建、查询、更新和删除资金流水记录。服务接口ISysUserPayment提供了AddRecord和ListRecords等方法来处理这些操作。
节来源
架构概述
资金流水功能采用典型的分层架构，包括API层、控制器层、服务层、逻辑层、数据访问层和模型层。API层定义了HTTP端点，控制器层处理HTTP请求并调用服务层，服务层协调业务逻辑，逻辑层实现具体业务规则，数据访问层负责与数据库交互，模型层定义数据结构。
graph TB
A[客户端] --> B[API层]
B --> C[控制器层]
C --> D[服务层]
D --> E[逻辑层]
E --> F[数据访问层]
F --> G[数据库]
图示来源
- wallet_log.go
- fund_v1_menu_log_list.go
- sys_user_payment.go
- record.go
- v_1_sys_user_payment_records.go
详细组件分析
资金流水API分析
资金流水API定义了四个主要操作：创建、查询、更新和删除。这些操作通过MenuLogCreateReq、MenuLogListReq、MenuLogUpdateReq和MenuLogDeleteReq结构体定义。
classDiagram
class MenuLogListReq {
+CommonPageReq
}
class MenuLogCreateReq {
}
class MenuLogUpdateReq {
+CommonIntId
}
class MenuLogDeleteReq {
+CommonIntId
}
MenuLogListReq : path : "/auth/menuLog/getList" tags : "钱包流水" method : "get" summary : "获取钱包流水"
MenuLogCreateReq : path : "/auth/menuLog/create" tags : "钱包流水" method : "post" summary : "创建钱包流水"
MenuLogUpdateReq : path : "/auth/menuLog/update" tags : "钱包流水" method : "post" summary : "修改钱包流水"
MenuLogDeleteReq : path : "/auth/menuLog/delete" tags : "钱包流水" method : "delete" summary : "删除钱包流水"
图示来源
节来源
服务层分析
服务层通过ISysUserPayment接口定义了资金流水操作，包括AddRecord用于创建流水记录，ListRecords用于查询流水记录。
classDiagram
class ISysUserPayment {
+AddRecord(ctx, input, tx) recordId, err
+ListRecords(ctx, input) total, list, err
+DailySummary(ctx, input) total, record, err
}
class SysUserPaymentRecordInput {
+OrderNo string
+UserId string
+PaymentId int
+Amount decimal.Decimal
+Notes string
+TransactionType UserPaymentTransactionType
+Category CardRedeemAccountCategory
}
ISysUserPayment ..> SysUserPaymentRecordInput : 使用
图示来源
节来源
数据访问分析
数据访问层通过V1SysUserPaymentRecords DAO与数据库交互，使用V1SysUserPaymentRecords模型定义数据库表结构。
classDiagram
class V1SysUserPaymentRecords {
+Id uint
+TransactionId string
+PaymentId int
+DeductionId string
+UserId string
+Amount decimal.Decimal
+TransactionType string
+OrderNo string
+Status string
+Category string
+Notes string
+CreatedAt *gtime.Time
+DeletedAt *gtime.Time
+UpdatedAt *gtime.Time
}
class v1SysUserPaymentRecordsDao {
+InsertAndGetId(data) id, err
+Where(column, value) Query
+Page(page, size) Query
+OrderDesc(column) Query
+ScanAndCount(list, total, true) err
}
V1SysUserPaymentRecords ..> v1SysUserPaymentRecordsDao : 使用
图示来源
节来源
依赖分析
资金流水功能依赖于多个组件，包括认证服务、数据库配置、通用工具库等。这些依赖通过Go的包导入机制实现。
graph TD
A[资金流水API] --> B[认证服务]
A --> C[数据库配置]
A --> D[通用工具库]
A --> E[错误处理]
B --> F[用户认证]
C --> G[数据库连接]
D --> H[UUID生成]
D --> I[时间处理]
E --> J[错误码]
图示来源
节来源
性能考虑
当前资金流水功能的性能考虑主要包括：
- 查询操作支持分页和排序，避免一次性加载大量数据
- 使用数据库事务确保数据一致性
- 通过索引优化查询性能（基于
UserId和TransactionType字段） - 使用连接池管理数据库连接
然而，部分控制器方法仍返回gcode.CodeNotImplemented，表明功能尚未完全实现，需要进一步优化和实现。
故障排除指南
常见问题及解决方案：
- API返回501未实现错误：检查控制器方法是否已实现，当前
fund_v1_menu_log_*系列方法均返回未实现错误。 - 查询结果为空：确认
UserId和TransactionType参数是否正确，检查数据库中是否存在相关记录。 - 创建记录失败：检查输入参数是否符合要求，特别是金额字段的精度和范围。
- 权限不足错误：确保请求包含有效的认证令牌，用户具有相应权限。
节来源
结论
资金流水功能提供了创建、查询、更新和删除资金流水记录的基本框架，但部分功能尚未完全实现。建议优先实现控制器层的方法，完善错误处理机制，并添加单元测试确保功能的正确性和稳定性。同时，应考虑添加更多的查询条件和过滤选项，以满足实际业务需求。