Files

danial 96ed936079 docs(api): 添加详细Apple卡密管理API文档

- 新增API端点参考文档，涵盖权限、卡密、订单、商户、监控、限制等模块
- 详细说明Apple卡密充值处理流程，包括提交、查询、回调和轮询接口
- 描述充值订单状态机及生命周期，支持超时重试和状态迁移
- 介绍签名验证、幂等控制及重复卡密防刷单策略
- 增加商户配置管理、历史记录查询和错误处理机制说明
- 提供API使用示例代码及客户端实现指导
- 删除过时的.drone.yml.bak文件，清理无用配置
- 添加.dockerignore忽略指定目录和文件

2025-10-08 20:13:40 +08:00

14 KiB

Raw Blame History

天猫卡密订单处理

**本文档引用的文件** - [order.go](file://api/card_info_t_mall_game/v1/order.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_t_mall_order.go](file://internal/service/card_t_mall_order.go) - [order.go](file://internal/logic/card_t_mall_order/order.go) - [card_recharge_t_mall.go](file://internal/consts/card_recharge_t_mall.go) - [v_1_recharge_t_mall_order.go](file://internal/dao/v_1_recharge_t_mall_order.go) - [v_1_recharge_t_mall_order.go](file://internal/model/entity/v_1_recharge_t_mall_order.go) - [shop.go](file://api/card_info_t_mall_game/v1/shop.go) - [v_1_recharge_t_mall_shop.go](file://internal/model/entity/v_1_recharge_t_mall_shop.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_call_back_order_manual.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_call_back_order_manual.go)

简介

本文档详细介绍了天猫卡密订单处理API的设计与实现，涵盖订单提交、状态查询、历史记录等核心功能。系统通过与天猫平台的深度集成，实现了卡密订单的自动化处理流程，包括订单创建、状态同步、回调处理等关键环节。文档重点阐述了订单状态机、幂等性处理、安全认证等核心机制，为开发者提供了完整的实现指南和最佳实践。

项目结构

天猫卡密订单处理系统采用分层架构设计，主要包含API接口层、业务逻辑层、数据访问层和常量定义层。系统通过模块化设计将不同功能分离，确保代码的可维护性和扩展性。

graph TD
subgraph "API层"
A[order.go]
B[shop.go]
end
subgraph "控制器层"
C[card_info_t_mall_game_v1_t_mall_game_order_submit.go]
D[card_info_t_mall_game_v1_t_mall_game_agiso_callback.go]
E[card_info_t_mall_game_v1_call_back_order_manual.go]
end
subgraph "服务层"
F[card_t_mall_order.go]
end
subgraph "逻辑层"
G[order.go]
end
subgraph "数据访问层"
H[v_1_recharge_t_mall_order.go]
I[v_1_recharge_t_mall_shop.go]
end
subgraph "常量层"
J[card_recharge_t_mall.go]
end
A --> C
B --> C
C --> F
D --> F
E --> F
F --> G
G --> H
G --> I
J --> F

图示来源

章节来源

核心组件

天猫卡密订单处理系统的核心组件包括订单管理、状态机处理、回调机制和数据同步四大模块。订单管理模块负责订单的创建、查询和更新；状态机处理模块维护订单的生命周期状态；回调机制实现与第三方系统的通信；数据同步模块确保本地数据与天猫平台数据的一致性。

章节来源

架构概述

系统采用典型的分层架构，从上至下分为API接口层、控制器层、服务层、逻辑层和数据访问层。API接口层定义了外部可访问的RESTful端点；控制器层处理HTTP请求并调用相应的服务；服务层提供业务逻辑的抽象接口；逻辑层实现具体的业务规则；数据访问层负责与数据库交互。

graph TB
Client[客户端] --> API[API接口]
API --> Controller[控制器]
Controller --> Service[服务层]
Service --> Logic[逻辑层]
Logic --> DAO[数据访问层]
DAO --> DB[(数据库)]
style Client fill:#f9f,stroke:#333
style API fill:#bbf,stroke:#333
style Controller fill:#f96,stroke:#333
style Service fill:#6f9,stroke:#333
style Logic fill:#96f,stroke:#333
style DAO fill:#69f,stroke:#333
style DB fill:#9f6,stroke:#333

图示来源

详细组件分析

订单提交组件分析

订单提交组件负责处理客户端的订单创建请求，验证输入参数，创建订单记录，并返回订单号。该组件实现了幂等性处理，确保重复提交不会创建多个订单。

订单提交序列图

sequenceDiagram
participant Client as "客户端"
participant API as "API接口"
participant Controller as "控制器"
participant Service as "服务层"
participant Logic as "逻辑层"
participant DAO as "数据访问层"
participant DB as "数据库"
Client->>API : POST /recharge/tMallGame/order/submit
API->>Controller : 转发请求
Controller->>Controller : 验证账号可用性
Controller->>Service : 调用Create方法
Service->>Logic : 创建订单
Logic->>DAO : 生成订单号
DAO->>DB : 插入订单记录
DB-->>DAO : 返回结果
DAO-->>Logic : 确认创建
Logic-->>Service : 返回订单号
Service-->>Controller : 返回结果
Controller-->>API : 构造响应
API-->>Client : 返回订单号和状态

图示来源

章节来源

订单状态机分析

订单状态机组件管理订单的整个生命周期，从创建到完成的各种状态转换。系统定义了丰富的状态类型，确保订单处理过程的可追踪性和可靠性。

订单状态机图

stateDiagram-v2
[*] --> created
created --> callback : 收到回调
callback --> delivery_failed : 虚拟发货失败
callback --> delivery_succeed : 虚拟发货成功
delivery_succeed --> paid : 已付款
paid --> bind_shop_succeed : 关联淘宝订单成功
bind_shop_succeed --> wait_for_evaluation : 等待用户评价
wait_for_evaluation --> evaluation : 买家评价
evaluation --> callback_succeed : 回调成功
evaluation --> callback_failed : 回调失败
callback_succeed --> finished : 订单结束
callback_succeed --> finished_with_wrong_amount : 金额错误
callback_succeed --> finished_with_wrong_status : 状态错误
callback_succeed --> finished_with_refund_succeed : 退款成功
callback_failed --> refund_failed : 退款失败
delivery_failed --> without_fill_account : 未填写账号
note right of created
订单创建状态
等待处理
end note
note right of delivery_succeed
虚拟商品已发货
等待买家确认
end note
note right of wait_for_evaluation
买家已确认收货
等待评价
end note
note right of finished
订单正常完成
所有流程结束
end note

图示来源

章节来源

card_recharge_t_mall.go

回调处理组件分析

回调处理组件负责接收来自天猫平台的异步通知，解析回调数据，更新订单状态，并触发后续业务流程。该组件实现了多种回调类型的处理，包括支付成功、确认收货和用户评价。

回调处理流程图

flowchart TD
Start([收到回调请求]) --> ParseData["解析回调数据"]
ParseData --> CheckExist["检查订单是否存在"]
CheckExist --> OrderExists{"订单存在?"}
OrderExists --> |否| CreateOrder["创建新订单"]
OrderExists --> |是| UpdateStatus["更新订单状态"]
CreateOrder --> ProcessPayment["处理支付逻辑"]
UpdateStatus --> ProcessPayment
ProcessPayment --> VirtualDelivery["尝试虚拟发货"]
VirtualDelivery --> DeliverySuccess{"发货成功?"}
DeliverySuccess --> |否| RecordFailure["记录失败状态"]
DeliverySuccess --> |是| RecordSuccess["记录成功状态"]
RecordFailure --> End([结束])
RecordSuccess --> BindOrder["关联淘宝订单"]
BindOrder --> WaitForEvaluation["等待用户评价"]
WaitForEvaluation --> ReceiveEvaluation["收到评价回调"]
ReceiveEvaluation --> CheckEvaluation{"好评?"}
CheckEvaluation --> |是| GiveGoodReview["给予买家好评"]
CheckEvaluation --> |否| RecordBadReview["记录差评"]
GiveGoodReview --> CallbackUpstream["回调上游系统"]
RecordBadReview --> CallbackUpstream
CallbackUpstream --> End

图示来源

章节来源

card_info_t_mall_game_v1_t_mall_game_agiso_callback.go

依赖分析

系统各组件之间的依赖关系清晰明确，遵循依赖倒置原则。高层模块依赖于抽象接口，而非具体实现，提高了系统的可测试性和可维护性。

classDiagram
class OrderAPI {
+POST /submit
+GET /list
+GET /query
}
class OrderController {
+TMallGameOrderSubmit()
+TMallGameOrderList()
+TMallGameOrderQueryOrder()
}
class OrderService {
+Create()
+List()
+GetById()
+UpdateStatus()
}
class OrderLogic {
+Create()
+List()
+GetById()
+UpdateStatus()
}
class OrderDAO {
+Insert()
+Select()
+Update()
+Delete()
}
class OrderEntity {
+OrderNo
+AccountNumber
+Amount
+Status
+CreatedAt
}
OrderAPI --> OrderController : "调用"
OrderController --> OrderService : "依赖"
OrderService --> OrderLogic : "实现"
OrderLogic --> OrderDAO : "调用"
OrderDAO --> OrderEntity : "映射"
OrderEntity --> DB : "持久化"
class Consts {
+OrderStatusCreated
+OrderStatusCallback
+OrderStatusDeliverySucceed
+OrderStatusFinished
}
OrderService --> Consts : "引用"
OrderLogic --> Consts : "引用"

图示来源

章节来源

性能考虑

系统在设计时充分考虑了性能优化，采用了多种技术手段确保高并发场景下的稳定运行。包括数据库连接池、缓存机制、异步处理等。订单查询接口支持分页和条件过滤，避免全表扫描。订单创建过程采用事务处理，确保数据一致性。

故障排除指南

常见问题及解决方案

订单创建失败：检查账号状态是否启用，确保账号信息正确无误。
回调处理超时：检查网络连接，确保回调地址可访问，适当增加超时时间。
状态同步延迟：检查定时任务是否正常运行，确认数据同步频率设置合理。
虚拟发货失败：检查天猫API密钥有效性，确认商品配置正确。

章节来源

结论

天猫卡密订单处理系统通过清晰的架构设计和严谨的状态管理，实现了高效可靠的订单处理能力。系统具备良好的扩展性和可维护性，能够满足不断变化的业务需求。通过本文档的指导，开发者可以快速理解系统架构，进行二次开发和问题排查。

14 KiB Raw Blame History Unescape Escape

天猫卡密订单处理

目录

简介

项目结构

核心组件

架构概述

详细组件分析

订单提交组件分析

订单提交序列图

订单状态机分析

订单状态机图

回调处理组件分析

回调处理流程图

依赖分析

性能考虑

故障排除指南

常见问题及解决方案

结论

14 KiB

Raw Blame History