kami_backend/.qoder/repowiki/zh/content/API端点参考/卡密信息管理API/Apple卡密管理API/Apple卡密充值处理.md

Apple卡密充值处理

**本文档引用文件** - [order.go](file://api/card_info_apple/v1/order.go) - [order_history.go](file://api/card_info_apple/v1/order_history.go) - [account_info.go](file://api/card_info_apple/v1/account_info.go) - [account_history.go](file://api/card_info_apple/v1/account_history.go) - [config.go](file://api/card_info_apple/v1/config.go) - [model.go](file://api/card_info_apple/v1/model.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_handler.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_handler.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_submit_query.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_submit_query.go) - [card_info_apple_v1_recharge_history_list.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_history_list.go) - [card_info_apple_v1_config_get.go](file://internal/controller/card_info_apple/card_info_apple_v1_config_get.go) - [card_info_apple_v1_config_set.go](file://internal/controller/card_info_apple/card_info_apple_v1_config_set.go)

目录

1. 简介
2. 核心API端点
3. 充值订单状态机与生命周期
4. iTunes回调机制
5. 数据验证与安全机制
6. 重复卡密与防刷单策略
7. 配置管理
8. 历史记录查询
9. 错误处理与性能优化

简介

本文档详细说明Apple卡密充值处理系统的API设计、工作流程、状态管理及安全机制。系统支持商户提交Apple礼品卡充值请求，通过后台任务轮询分配至合适的iTunes账户进行处理，并提供完整的回调机制、历史查询和防刷单策略。重点描述了高并发场景下的稳定性保障措施。

核心API端点

充值提交接口

• HTTP方法: POST
• URL模式: /cardInfo/appleCard/submit
• 认证机制: 请求签名验证（基于merchantId、attach、cardPass和timeStamp生成）
• 请求参数:
  • cardNo: 卡号
  • cardPass: 卡密
  • faceValue: 面值（单位：分）
  • callbackUrl: 回调地址
  • attach: 附加信息（上游订单号）
  • timeStamp: 时间戳
  • sign: 签名
  • merchantId: 商户ID
• 响应结构:
  • orderNo: 系统生成的订单号
  • status: 充值状态码
  • message: 详细描述信息

Section sources

• order.go
• card_info_apple_v1_recharge_submit.go

充值订单查询接口

• HTTP方法: GET
• URL模式: /cardInfo/appleCard/query
• 请求参数:
  • orderNo: 订单ID（必填）
• 响应结构:
  • status: 当前订单状态
  • message: 状态描述

Section sources

• order.go
• card_info_apple_v1_recharge_submit_query.go

回调处理接口

• HTTP方法: POST
• URL模式: /cardInfo/appleCard/rechargeOrder/callback
• 请求参数:
  • amount: 实际充值金额
  • accountAmount: 充值后账户余额
  • accountId: 账户ID
  • machineId: 机器ID
  • orderNo: 订单ID
  • status: 充值状态（枚举值）
  • remark: 备注信息
• 响应结构: 空对象

Section sources

• order.go
• card_info_apple_v1_recharge_itunes_callback.go

轮询处理接口

• HTTP方法: POST
• URL模式: /cardInfo/appleCard/rechargeOrder/handler
• 用途: 供后台处理机轮询获取待处理的充值订单
• 请求参数:
  • machineId: 机器ID（必填）
• 响应结构:
  • orderNo: 订单ID
  • cardNo: 卡号
  • cardPass: 卡密
  • account: iTunes账户
  • password: 账户密码
  • accountId: 账户ID

Section sources

• order.go
• card_info_apple_v1_recharge_handler.go

充值订单状态机与生命周期

stateDiagram-v2
[*] --> 待处理
待处理 --> 处理中 : 分配账户
处理中 --> 充值成功 : 回调成功
处理中 --> 充值失败 : 回调失败
处理中 --> 超时等待 : 1分钟未完成
超时等待 --> 处理中 : 重新分配
充值成功 --> [*]
充值失败 --> [*]

Diagram sources

• order.go
• card_info_apple_v1_recharge_handler.go

iTunes回调机制

系统通过以下流程处理iTunes充值回调：

1. 后台处理机执行充值操作
2. 成功后调用 /cardInfo/appleCard/rechargeOrder/callback 接口
3. 系统验证回调数据并更新订单状态
4. 根据配置决定是否向商户callbackUrl发起二次回调
5. 记录充值历史和账户余额变化

Section sources

• order.go
• card_info_apple_v1_recharge_itunes_callback.go

数据验证与安全机制

签名验证

请求必须包含签名，使用以下参数生成：

sign = MD5(attach + cardPass + timeStamp)

卡密格式验证

系统对卡密进行格式校验，确保符合Apple卡密规范。

幂等性控制

使用Redis缓存防止同一商户ID在短时间内重复提交相同订单。

flowchart TD
A[接收充值请求] --> B{验证签名}
B --> |失败| C[返回验证错误]
B --> |成功| D{卡密格式校验}
D --> |失败| E[返回卡密错误]
D --> |成功| F{检查重复订单}
F --> |存在| G[返回处理中]
F --> |不存在| H[创建订单并返回成功]

Diagram sources

• card_info_apple_v1_recharge_submit.go

重复卡密与防刷单策略

重复订单检测

• 基于merchantId在10秒内设置Redis锁，防止重复提交
• 系统级卡密去重（可配置）

偷单机制

当系统配置启用偷单功能时：

1. 检查当前订单是否符合偷单规则
2. 若符合，将订单分配给指定存储账户
3. 为原订单创建替代订单，实现订单转移

Section sources

• card_info_apple_v1_recharge_submit.go
• card_info_apple_v1_recharge_handler.go

配置管理

获取配置

• HTTP方法: GET
• URL模式: /cardInfo/AppleCard/config/get
• 响应参数:
  • isAllowDifferentAmount: 是否允许金额异议充值
  • isAllowDifferentSucceedCallback: 是否允许成功时金额异议回调
  • isAllowDifferentFailCallback: 是否允许失败时金额异议回调
  • redeemCardMinAmount: 最小充值金额
  • isAllowCompensatedCallback: 是否允许补卡自动回调
  • redeemCardRate: 充值速率限制

设置配置

• HTTP方法: POST
• URL模式: /cardInfo/AppleCard/config/set
• 所有参数均为必填

Section sources

• config.go
• card_info_apple_v1_config_get.go
• card_info_apple_v1_config_set.go

历史记录查询

充值历史查询

• HTTP方法: GET
• URL模式: /cardInfo/AppleCard/rechargeOrder/getHistoryList
• 请求参数: orderNo（必填）
• 响应结构: 包含每次充值的详细记录

账户余额历史

• HTTP方法: GET
• URL模式: /cardInfo/AppleCard/account/getWalletList
• 响应结构: 包含余额变化记录，包括：
  • 充值前余额
  • 充值后余额
  • 充值金额
  • 操作时间

Section sources

• order_history.go
• account_history.go

错误处理与性能优化

错误处理策略

• 统一错误码体系（基于gcode）
• 详细的错误包装和日志记录
• 客户端友好的错误消息

高并发优化

• Redis缓存实现请求幂等性
• 数据库事务保证状态一致性
• 定时任务避免长时间阻塞
• 读写锁控制并发访问

系统稳定性

• 订单处理超时自动恢复机制
• 数据库连接池优化
• 关键操作日志追踪（OpenTelemetry）

Section sources

• card_info_apple_v1_recharge_submit.go
• card_info_apple_v1_recharge_handler.go
• utility/otel