danial/kami_backend
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Files
96ed936079e5e9da79410aefaf8bd7728771eaff
kami_backend/.qoder/repowiki/zh/content/业务逻辑层架构/卡密管理逻辑/天猫卡密管理逻辑/天猫卡密管理逻辑.md
danial 96ed936079 docs(api): 添加详细Apple卡密管理API文档 
- 新增API端点参考文档，涵盖权限、卡密、订单、商户、监控、限制等模块
- 详细说明Apple卡密充值处理流程，包括提交、查询、回调和轮询接口
- 描述充值订单状态机及生命周期，支持超时重试和状态迁移
- 介绍签名验证、幂等控制及重复卡密防刷单策略
- 增加商户配置管理、历史记录查询和错误处理机制说明
- 提供API使用示例代码及客户端实现指导
- 删除过时的.drone.yml.bak文件，清理无用配置
- 添加.dockerignore忽略指定目录和文件
2025-10-08 20:13:40 +08:00

17 KiB
Raw Blame History

天猫卡密管理逻辑

**本文档引用的文件** - [card_info_t_mall_game_v1_t_mall_game_account_create.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_account_create.go) - [card_info_t_mall_game_v1_t_mall_game_account_delete.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_account_delete.go) - [card_info_t_mall_game_v1_t_mall_game_account_toggle.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_account_toggle.go) - [card_info_t_mall_game_v1_t_mall_game_account_authorize_callback.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_account_authorize_callback.go) - [card_info_t_mall_game_v1_t_mall_game_order_submit.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_order_submit.go) - [card_info_t_mall_game_v1_t_mall_game_agiso_callback.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_agiso_callback.go) - [card_info_t_mall_game_v1_t_mall_game_data_sync.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_data_sync.go) - [card_info_t_mall_game_v1_t_mall_game_daily_order_summary.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_daily_order_summary.go) - [card_t_mall_account.go](file://internal/service/card_t_mall_account.go) - [card_t_mall_order.go](file://internal/service/card_t_mall_order.go) - [card_t_mall_game_account.go](file://internal/model/card_t_mall_game_account.go) - [card_t_mall_game_order.go](file://internal/model/card_t_mall_game_order.go) - [v_1_recharge_t_mall_account.go](file://internal/dao/v_1_recharge_t_mall_account.go) - [v_1_recharge_t_mall_order.go](file://internal/dao/v_1_recharge_t_mall_order.go)

目录

  1. 天猫卡密账户管理
  2. 天猫卡密订单处理
  3. AGISO回调处理
  4. 数据同步与统计
  5. 系统集成与异常处理

天猫卡密账户管理

天猫卡密账户管理模块负责账户的全生命周期管理，包括创建、删除、状态切换和授权等核心功能。系统通过统一的接口服务层（IRechargeTMallGameAccount）提供账户管理能力，确保操作的一致性和可维护性。

账户创建与删除

账户创建功能通过TMallGameAccountCreate接口实现，接收账户创建请求参数，调用账户服务进行持久化存储。系统在创建过程中会验证账户信息的完整性和唯一性，确保不会创建重复账户。账户删除功能通过TMallGameAccountDelete接口实现，根据账户ID执行删除操作，同时清理相关联的数据。

flowchart TD
Start([开始]) --> ValidateInput["验证输入参数"]
ValidateInput --> CheckExistence["检查账户是否存在"]
CheckExistence --> AccountExists{"账户已存在?"}
AccountExists --> |是| ReturnError["返回错误: 账户已存在"]
AccountExists --> |否| CreateAccount["创建账户记录"]
CreateAccount --> SaveToDB["保存到数据库"]
SaveToDB --> UpdateCache["更新缓存"]
UpdateCache --> End([结束])
DeleteStart([开始]) --> ValidateID["验证账户ID"]
ValidateID --> FindAccount["查找账户"]
FindAccount --> AccountFound{"账户找到?"}
AccountFound --> |否| ReturnNotFound["返回: 账户不存在"]
AccountFound --> |是| DeleteRelated["删除关联数据"]
DeleteRelated --> RemoveFromDB["从数据库移除"]
RemoveFromDB --> ClearCache["清除缓存"]
ClearCache --> End

图示来源

本节来源

账户状态管理

账户状态管理功能允许系统管理员对账户进行启用/禁用操作。通过TMallGameAccountToggle接口接收状态切换请求，调用服务层的Toggle方法更新账户状态。系统会记录状态变更历史，便于审计和问题追踪。状态切换操作是幂等的，即重复执行相同的状态切换请求不会产生副作用。

flowchart TD
Start([开始]) --> ValidateRequest["验证请求参数"]
ValidateRequest --> GetAccount["获取账户信息"]
GetAccount --> AccountExists{"账户存在?"}
AccountExists --> |否| ReturnError["返回错误: 账户不存在"]
AccountExists --> |是| GetCurrentStatus["获取当前状态"]
GetCurrentStatus --> DetermineNewStatus["确定新状态"]
DetermineNewStatus --> UpdateStatus["更新账户状态"]
UpdateStatus --> LogChange["记录状态变更日志"]
LogChange --> NotifySystem["通知相关系统"]
NotifySystem --> End([结束])

图示来源

本节来源

账户授权与工作空间管理

账户授权功能通过TMallGameAccountAuthorizeCallback接口处理来自第三方平台（如阿奇索、天猫店铺）的授权回调。系统根据回调中的渠道信息区分处理逻辑，对于天猫店铺授权，会调用天猫API进行OAuth2登录验证。授权成功后，系统会更新账户的授权状态，并建立与工作空间的关联关系。

sequenceDiagram
participant ThirdParty as "第三方平台"
participant System as "卡密系统"
participant TMallAPI as "天猫API"
ThirdParty->>System : 发送授权回调
System->>System : 验证回调签名
alt 阿奇索渠道
System->>System : 记录授权信息
System-->>ThirdParty : 返回成功
else 天猫店铺渠道
System->>TMallAPI : 调用OAuth2Login
alt 授权成功
TMallAPI-->>System : 返回授权结果
System->>System : 更新账户授权状态
System-->>ThirdParty : 返回成功
else 授权失败
TMallAPI-->>System : 返回错误
System->>System : 记录授权失败日志
System-->>ThirdParty : 返回失败
end
else 其他渠道
System-->>ThirdParty : 返回不支持
end

图示来源

本节来源

天猫卡密订单处理

天猫卡密订单处理模块负责订单的全生命周期管理，从订单提交到最终完成的整个流程。系统通过统一的订单服务接口（IRechargeTMallGameOrder）提供订单管理能力，确保订单处理的一致性和可靠性。

订单提交流程

订单提交功能通过TMallGameOrderSubmit接口实现。系统首先验证请求参数的完整性，然后根据账户号码查找对应的账户信息。如果账户不存在或不可用，系统会返回相应的错误信息。验证通过后，系统调用订单服务创建新订单，并返回订单号和状态信息。订单创建过程中会进行数据一致性检查，确保订单金额、回调地址等关键信息的正确性。

flowchart TD
Start([开始]) --> ValidateRequest["验证请求参数"]
ValidateRequest --> FindAccount["查找账户信息"]
FindAccount --> AccountValid{"账户有效?"}
AccountValid --> |否| ReturnError["返回错误: 账户不存在或不可用"]
AccountValid --> |是| CreateOrder["创建订单记录"]
CreateOrder --> SetOrderStatus["设置订单初始状态"]
SetOrderStatus --> GenerateOrderNo["生成订单号"]
GenerateOrderNo --> SaveOrder["保存订单到数据库"]
SaveOrder --> ReturnSuccess["返回订单号和成功状态"]
ReturnSuccess --> End([结束])

图示来源

本节来源

AGISO回调处理

AGISO回调处理模块负责处理来自AGISO平台的各类订单状态变更通知，包括买家付款、确认收货、申请退款和评价等事件。系统通过TMallGameAgisoCallback接口接收回调请求，并根据回调类型分发到相应的处理函数。

回调处理机制

系统采用并发安全的处理机制，通过互斥锁和缓存确保同一订单不会被重复处理。每个回调请求都会先验证签名的正确性，防止伪造请求。处理成功后，系统会更新订单状态，并根据业务规则执行相应的后续操作，如虚拟发货、回调第三方等。

flowchart TD
Start([开始]) --> ValidateSign["验证回调签名"]
ValidateSign --> SignValid{"签名有效?"}
SignValid --> |否| ReturnError["返回错误: 签名验证失败"]
SignValid --> |是| CheckDuplicate["检查重复处理"]
CheckDuplicate --> IsDuplicate{"正在处理?"}
IsDuplicate --> |是| ReturnBusy["返回: 订单正在处理"]
IsDuplicate --> |否| AcquireLock["获取处理锁"]
AcquireLock --> ProcessCallback["处理回调事件"]
ProcessCallback --> UpdateOrder["更新订单状态"]
UpdateOrder --> ExecuteAction["执行后续操作"]
ExecuteAction --> ReleaseLock["释放锁"]
ReleaseLock --> ReturnSuccess["返回成功"]
ReturnSuccess --> End([结束])

图示来源

本节来源

买家付款处理

当收到买家付款回调时，系统会先检查订单是否已存在，防止重复处理。然后创建淘宝订单记录，并调用天猫API获取详细的订单信息。系统会尝试进行虚拟发货，最多重试三次。如果发货成功，更新订单状态为发货成功；如果失败，则标记为发货失败，并记录错误日志。

sequenceDiagram
participant Agiso as "AGISO平台"
participant System as "卡密系统"
participant TMallAPI as "天猫API"
Agiso->>System : 买家付款回调
System->>System : 检查订单是否已存在
alt 订单已存在
System-->>Agiso : 返回 : 订单已存在
else 订单不存在
System->>System : 创建淘宝订单记录
System->>TMallAPI : 获取订单详情
alt 获取成功
TMallAPI-->>System : 返回订单详情
System->>System : 尝试虚拟发货
loop 重试3次
System->>TMallAPI : 虚拟发货
alt 发货成功
TMallAPI-->>System : 发货成功
System->>System : 更新订单状态为发货成功
break
else 发货失败
TMallAPI-->>System : 发货失败
System->>System : 记录发货失败日志
end
end
else 获取失败
TMallAPI-->>System : 获取失败
System->>System : 记录获取失败日志
end
System-->>Agiso : 返回处理结果
end

图示来源

本节来源

数据同步与统计

数据同步与统计模块提供数据实时同步和业务统计功能，支持系统间的数据一致性维护和业务决策支持。

数据同步机制

TMallGameDataSync接口提供数据同步功能，允许客户端获取指定时间段内的最新数据变更。系统会查询订单、账户、店铺和历史记录等实体的更新数据，并按类别返回。同步机制采用时间戳过滤，确保只返回增量数据，提高同步效率。

flowchart TD
Start([开始]) --> ParseRequest["解析请求参数"]
ParseRequest --> GetDuration["获取同步时长"]
GetDuration --> CalculateTime["计算起始时间"]
CalculateTime --> QueryOrders["查询订单变更"]
QueryOrders --> QueryAccounts["查询账户变更"]
QueryAccounts --> QueryShops["查询店铺变更"]
QueryShops --> QueryOrderHistory["查询订单历史变更"]
QueryOrderHistory --> QueryShopHistory["查询店铺历史变更"]
QueryShopHistory --> AssembleData["组装返回数据"]
AssembleData --> ReturnData["返回同步数据"]
ReturnData --> End([结束])

图示来源

本节来源

订单统计功能

TMallGameDailyOrderSummary接口提供订单统计功能，支持按时间范围、状态等条件查询订单汇总数据。系统会调用订单服务的统计方法，获取符合条件的订单总数和详细记录，并进行数据转换后返回。统计功能支持分页查询，便于处理大量数据。

flowchart TD
Start([开始]) --> ParseParams["解析统计参数"]
ParseParams --> CallService["调用订单统计服务"]
CallService --> GetTotal["获取订单总数"]
GetTotal --> GetList["获取订单列表"]
GetList --> TransformData["转换数据格式"]
TransformData --> ReturnResult["返回统计结果"]
ReturnResult --> End([结束])

图示来源

本节来源

系统集成与异常处理

系统集成与异常处理模块确保天猫卡密管理系统与其他系统的稳定集成，并提供完善的错误处理机制。

系统集成模式

天猫卡密管理系统通过标准化的API接口与订单系统、支付系统等外部系统集成。系统采用异步回调机制，当订单状态发生变更时，会通过预设的回调地址通知第三方系统。集成过程中使用数字签名验证确保通信安全，防止数据篡改和伪造请求。

异常处理策略

系统采用分层的异常处理策略。在控制器层，所有异常都会被统一捕获并包装为标准的错误响应。业务逻辑层会根据异常类型进行分类处理，如数据验证错误、系统错误、第三方服务错误等。对于可恢复的错误，系统会尝试重试；对于不可恢复的错误，会记录详细的错误日志并通知相关人员。

数据一致性保障

系统通过事务管理确保数据的一致性。关键操作如订单创建、状态更新等都会在数据库事务中执行，确保要么全部成功，要么全部回滚。系统还实现了幂等性设计，相同的操作重复执行不会产生副作用。此外，通过定期的数据校验任务，系统能够及时发现并修复数据不一致问题。

本节来源