kami_gateway/.qoder/repowiki/zh/content/数据模型/账户与代理商模型.md

账户与代理商模型

**本文档引用文件** - [account.go](file://internal/models/accounts/account.go) - [agent_info.go](file://internal/models/agent/agent_info.go) - [agent_profit.go](file://internal/models/agent/agent_profit.go) - [account_history_info.go](file://internal/models/accounts/account_history_info.go) - [order_profit_info.go](file://internal/models/order/order_profit_info.go) - [platform_profit.go](file://internal/models/order/platform_profit.go) - [pay_solve.go](file://internal/service/pay_solve.go) - [settle_service.go](file://internal/service/settle_service.go)

目录

1. 账户模型设计
2. 代理商模型与层级关系
3. 账户资金字段详解
4. 账户状态管理机制
5. 账户历史记录审计
6. 代理商利润计算逻辑
7. 资金流水记录机制
8. 账户余额原子性操作
9. 账户安全机制
10. 代理商分润定时结算

账户模型设计

账户模型以 AccountInfo 结构体为核心，定义了商户账户的完整信息体系。该结构体包含账户标识、资金状态、时间戳等关键字段，为系统提供统一的账户数据视图。

classDiagram
class AccountInfo {
+int Id
+string Status
+string AccountUid
+string AccountName
+float64 Balance
+float64 SettleAmount
+float64 LoanAmount
+float64 FreezeAmount
+float64 WaitAmount
+float64 PayforAmount
+time.Time CreateTime
+time.Time UpdateTime
}

图表来源

• account.go

本节来源

• account.go

代理商模型与层级关系

系统通过 AgentInfo 结构体管理代理商信息，与商户账户形成层级管理关系。每个代理商可管理多个商户账户，通过 AgentUid 字段建立关联。代理商与商户之间通过 AgentName 和 AgentUid 字段在订单利润表中建立分润关系。

classDiagram
class AgentInfo {
+int Id
+string Status
+string AgentName
+string AgentPassword
+string PayPassword
+string AgentRemark
+string AgentUid
+string AgentPhone
+time.Time CreateTime
+time.Time UpdateTime
}
class AccountInfo {
+string AccountUid
+string AccountName
+float64 Balance
}
class OrderProfitInfo {
+string AgentName
+string AgentUid
+float64 AgentProfit
}
AgentInfo --> AccountInfo : "管理"
AgentInfo --> OrderProfitInfo : "关联"
AccountInfo --> OrderProfitInfo : "生成"

图表来源

• agent_info.go
• account.go
• order_profit_info.go

本节来源

• agent_info.go
• order_profit_info.go

账户资金字段详解

账户模型包含多个资金字段，分别表示不同的资金状态：

• Balance: 账户总余额，包含所有可用和不可用资金
• SettleAmount: 已结算金额，可随时提现的资金
• LoanAmount: 押款金额，因风控策略被暂时锁定的资金
• FreezeAmount: 冻结金额，因争议订单被冻结的资金
• WaitAmount: 待结算资金，已成功但未完成结算流程的资金
• PayforAmount: 代付在途金额，正在处理中的代付资金

这些字段共同构成了账户资金的完整状态机，确保资金流动的准确追踪。

本节来源

• account.go

账户状态管理机制

账户状态通过 Status 字段进行管理，采用字符串枚举方式表示账户的生命周期状态。系统通过 GetAccountByUid、UpdateAccount 等方法实现状态的查询和更新，所有状态变更操作均通过事务保证数据一致性。

账户状态变更遵循严格的业务流程，如结算、冻结、解冻等操作都需要经过完整的业务验证和事务处理，确保状态转换的正确性和安全性。

本节来源

• account.go
• account.go

账户历史记录审计

账户历史记录由 AccountHistoryInfo 结构体定义，用于审计所有账户资金变动。每次资金变动都会生成一条历史记录，包含变动类型、金额、余额等关键信息。

历史记录表作为重要的审计日志，记录了所有资金流动的完整轨迹，包括加款、冻结、解冻、退款等操作，为财务对账和问题排查提供可靠依据。

classDiagram
class AccountHistoryInfo {
+int Id
+string AccountUid
+string AccountName
+string Type
+string OrderId
+float64 Amount
+float64 Balance
+float64 FeeAmount
+time.Time CreateTime
+time.Time UpdateTime
}

图表来源

• account_history_info.go

本节来源

• account_history_info.go

代理商利润计算逻辑

代理商利润计算基于订单利润表 OrderProfitInfo 中的 AgentRate 代理费率字段。系统在订单成功后，根据实际支付金额和代理费率计算代理商应得利润。

利润分配在 SolvePaySuccess 方法中完成，通过事务性操作同时更新账户余额和生成利润记录，确保数据一致性。代理商利润信息同时存储在订单利润表和平台利润汇总表中，便于后续统计分析。

sequenceDiagram
participant 支付系统
participant 订单服务
participant 账户服务
participant 代理商利润
支付系统->>订单服务 : 支付成功通知
订单服务->>订单服务 : 计算代理费率
订单服务->>账户服务 : 更新账户余额
账户服务-->>订单服务 : 确认
订单服务->>代理商利润 : 记录代理利润
订单服务-->>支付系统 : 处理完成

图表来源

• order_profit_info.go
• pay_solve.go

本节来源

• order_profit_info.go
• pay_solve.go

资金流水记录机制

系统通过 InsertAccountHistory 方法记录每一笔资金流水。在订单结算、退款、冻结等关键操作中，都会生成对应的资金流水记录。

资金流水记录包含完整的上下文信息，包括订单号、变动类型、金额、手续费、变动后余额等，确保每一笔资金流动都可追溯。所有流水记录操作都与主业务操作在同一个数据库事务中完成，保证数据一致性。

本节来源

• account_history_info.go
• pay_solve.go

账户余额原子性操作

账户余额更新采用数据库事务和行级锁机制确保原子性。在 SolvePaySuccess 方法中，通过 SELECT ... FOR UPDATE 语句获取账户记录的排他锁，防止并发场景下的超卖问题。

所有余额更新操作都在事务中完成，包括账户余额更新、待结算资金更新、生成资金流水记录等，确保操作的原子性和一致性。系统还通过余额校验机制防止负余额的出现。

flowchart TD
A[开始事务] --> B[SELECT FOR UPDATE]
B --> C{余额充足?}
C --> |是| D[更新余额]
C --> |否| E[回滚事务]
D --> F[生成流水记录]
F --> G[提交事务]
E --> H[返回错误]

图表来源

• pay_solve.go

本节来源

• pay_solve.go

账户安全机制

账户安全通过多层机制保障：

• 密码存储: 登录密码和支付密码均采用加密存储，防止明文泄露
• 并发控制: 通过数据库事务和行级锁防止并发操作导致的数据不一致
• 操作审计: 所有资金操作都记录到历史表，便于审计和追溯
• 多因素认证: 系统预留了多因素认证扩展接口，可后续集成短信验证、令牌验证等安全机制

安全机制贯穿于账户操作的各个环节，从数据存储到业务处理都考虑了安全性要求。

本节来源

• agent_info.go
• pay_solve.go

代理商分润定时结算

代理商分润结算由 OrderSettle 定时任务处理，通过 settle_service.go 中的 OrderSettleInit 方法启动。系统每隔2分钟检查待结算订单，自动完成结算流程。

结算流程包括：更新订单结算状态、调整账户资金、处理押款逻辑等。对于需要押款的商户，系统还会根据配置的押款天数自动释放押款金额，整个过程完全自动化，确保代理商利润的及时分配。

flowchart TD
A[定时任务启动] --> B{检查待结算订单}
B --> |有订单| C[开始结算事务]
C --> D[锁定订单记录]
D --> E[锁定账户记录]
E --> F{需要押款?}
F --> |是| G[创建押款记录]
F --> |否| H[全款结算]
G --> I[更新账户资金]
H --> I
I --> J[提交事务]
J --> K[继续检查]
B --> |无订单| L[等待下次执行]

图表来源

• settle_service.go

本节来源

• settle_service.go