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

12 KiB
Raw Blame History

Apple订单处理

**本文档引用的文件** - [order.go](file://api/card_info_apple/v1/order.go) - [card_info_apple_v1_recharge_submit.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_submit.go) - [card_info_apple_v1_recharge_itunes_callback.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_itunes_callback.go) - [card_info_apple_v1_recharge_handler.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_handler.go) - [card_info_apple_v1_recharge_history_list.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_history_list.go) - [card_apple_order.go](file://internal/service/card_apple_order.go) - [order.go](file://internal/logic/card_apple_order/order.go) - [callback.go](file://internal/logic/card_apple_order/callback.go) - [status.go](file://internal/logic/card_apple_order/status.go) - [card_apple_order.go](file://internal/model/card_apple_order.go) - [v_1_card_apple_recharge_info.go](file://internal/dao/v_1_card_apple_recharge_info.go) - [card_apple.go](file://internal/consts/card_apple.go)

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构概览
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排除指南
  9. 结论

简介

本文档详细阐述了Apple卡密订单处理系统的实现机制，涵盖订单创建、状态管理、iTunes回调处理、历史记录查询等核心功能。系统通过严格的订单状态机管理充值流程，确保交易的完整性和一致性。文档深入分析了订单与Apple账户的关联机制、充值金额验证流程、幂等性保证和事务管理策略，为开发者提供全面的技术参考。

项目结构

Apple卡密订单处理功能主要分布在api/card_info_apple和internal目录下，采用分层架构设计，包含API接口、业务逻辑、数据访问等层次。

graph TD
subgraph "API层"
A[api/card_info_apple/v1/order.go]
B[api/card_info_apple/v1/order_history.go]
C[api/card_info_apple/v1/config.go]
end
subgraph "控制器层"
D[internal/controller/card_info_apple/card_info_apple_v1_recharge_submit.go]
E[internal/controller/card_info_apple/card_info_apple_v1_recharge_itunes_callback.go]
F[internal/controller/card_info_apple/card_info_apple_v1_recharge_handler.go]
end
subgraph "服务层"
G[internal/service/card_apple_order.go]
end
subgraph "逻辑层"
H[internal/logic/card_apple_order/order.go]
I[internal/logic/card_apple_order/callback.go]
J[internal/logic/card_apple_order/status.go]
end
subgraph "数据访问层"
K[internal/dao/v_1_card_apple_recharge_info.go]
end
subgraph "模型层"
L[internal/model/card_apple_order.go]
end
A --> D
B --> D
C --> D
D --> G
E --> G
F --> G
G --> H
G --> I
G --> J
H --> K
I --> K
J --> K
H --> L
I --> L
J --> L

图示来源

本节来源

核心组件

Apple卡密订单处理系统的核心组件包括订单提交处理器、iTunes回调处理器、订单状态管理器和充值历史查询服务。这些组件协同工作，确保订单从创建到完成的整个生命周期得到正确处理。

本节来源

架构概览

系统采用典型的分层架构，从API接口到数据存储，各层职责分明。API层定义了订单相关的REST接口，控制器层处理HTTP请求并调用服务层，服务层协调业务逻辑层完成具体操作，最终由数据访问层与数据库交互。

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 : 提交充值订单
API->>Controller : 转发请求
Controller->>Service : 调用充值服务
Service->>Logic : 执行订单创建逻辑
Logic->>DAO : 检查订单幂等性
DAO->>DB : 查询订单是否存在
DB-->>DAO : 返回查询结果
DAO-->>Logic : 返回检查结果
Logic->>DAO : 创建新订单
DAO->>DB : 插入订单记录
DB-->>DAO : 返回插入结果
DAO-->>Logic : 返回创建结果
Logic-->>Service : 返回订单信息
Service-->>Controller : 返回处理结果
Controller-->>API : 返回响应
API-->>Client : 返回订单创建结果

图示来源

详细组件分析

订单创建分析

订单创建组件负责处理用户提交的Apple卡密充值请求，验证输入参数，检查订单幂等性，并创建新的订单记录。

flowchart TD
Start([开始]) --> ValidateInput["验证输入参数"]
ValidateInput --> CheckIdempotency["检查订单幂等性"]
CheckIdempotency --> OrderExists{"订单已存在?"}
OrderExists --> |是| ReturnExisting["返回现有订单"]
OrderExists --> |否| CreateOrder["创建新订单"]
CreateOrder --> SetStatus["设置初始状态为待处理"]
SetStatus --> SaveOrder["保存订单到数据库"]
SaveOrder --> Notify["触发后续处理流程"]
Notify --> End([结束])

图示来源

本节来源

回调处理分析

iTunes回调处理组件负责接收Apple服务器的充值结果通知，验证回调数据的完整性，更新订单状态，并触发相应的业务逻辑。

sequenceDiagram
participant Apple as "Apple服务器"
participant Callback as "回调接口"
participant Validator as "验证器"
participant Status as "状态管理器"
participant Notifier as "通知服务"
Apple->>Callback : 发送充值结果回调
Callback->>Validator : 验证回调签名
Validator-->>Callback : 验证结果
alt 验证成功
Callback->>Status : 更新订单状态
Status->>Status : 状态转换逻辑
Status-->>Callback : 状态更新结果
Callback->>Notifier : 触发通知
Notifier-->>Callback : 通知结果
Callback-->>Apple : 返回成功响应
else 验证失败
Callback-->>Apple : 返回失败响应
end

图示来源

本节来源

状态机分析

订单状态机管理组件定义了订单的生命周期，包括待处理、处理中、成功、失败等状态的转换规则和触发条件。

stateDiagram-v2
[*] --> 待处理
待处理 --> 处理中 : 开始处理
处理中 --> 成功 : 充值成功
处理中 --> 失败 : 充值失败
处理中 --> 超时 : 处理超时
成功 --> [*]
失败 --> [*]
超时 --> [*]
note right of 处理中
包含子状态 :
- 验证卡密
- 调用Apple API
- 等待回调
end note

图示来源

本节来源

依赖分析

Apple卡密订单处理系统依赖于多个内部组件和外部服务，形成了复杂的依赖关系网络。

graph LR
A[订单提交] --> B[幂等性检查]
A --> C[参数验证]
A --> D[订单创建]
D --> E[数据库]
F[iTunes回调] --> G[签名验证]
F --> H[状态更新]
H --> E
I[历史查询] --> J[数据库查询]
J --> E
K[配置管理] --> L[系统配置]
A --> K
F --> K
style E fill:#f9f,stroke:#333
style K fill:#bbf,stroke:#333

图示来源

本节来源

性能考虑

为确保系统在高并发场景下的稳定性和响应速度，采用了多种性能优化策略。通过Redis缓存频繁访问的配置数据和订单状态，减少数据库查询压力。使用连接池管理数据库连接，提高资源利用率。对关键路径进行异步处理，避免阻塞主线程。同时，通过合理的索引设计和查询优化，确保数据库操作的高效性。

故障排除指南

重复订单处理

当系统检测到重复订单时，会根据幂等性原则返回已有订单信息而非创建新订单。检查v_1_card_apple_recharge_info表中的订单记录，确认订单的唯一标识符是否正确生成。

本节来源

回调验证失败

回调验证失败通常由签名不匹配或时间戳过期引起。检查系统时间是否同步，验证Apple提供的公钥是否正确配置，确认回调数据的完整性。

本节来源

结论

Apple卡密订单处理系统通过分层架构设计和严格的流程控制，实现了高可靠性的充值服务。系统具备完善的订单状态管理、幂等性保证和错误处理机制，能够有效应对各种异常情况。通过持续的性能优化和监控，确保了服务的稳定性和响应速度，为用户提供流畅的充值体验。