# Apple卡密充值处理

<cite>
**本文档引用文件**  
- [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)
</cite>

## 目录
1. [简介](#简介)
2. [核心API端点](#核心api端点)
3. [充值订单状态机与生命周期](#充值订单状态机与生命周期)
4. [iTunes回调机制](#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](file://api/card_info_apple/v1/order.go#L10-L45)
- [card_info_apple_v1_recharge_submit.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_submit.go#L15-L70)

### 充值订单查询接口

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

**Section sources**
- [order.go](file://api/card_info_apple/v1/order.go#L47-L57)
- [card_info_apple_v1_recharge_submit_query.go](file://internal/controller/card_info_apple/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](file://api/card_info_apple/v1/order.go#L77-L97)
- [card_info_apple_v1_recharge_itunes_callback.go](file://internal/controller/card_info_apple/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](file://api/card_info_apple/v1/order.go#L59-L75)
- [card_info_apple_v1_recharge_handler.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_handler.go#L15-L188)

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

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

**Diagram sources**
- [order.go](file://api/card_info_apple/v1/order.go#L77-L97)
- [card_info_apple_v1_recharge_handler.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_handler.go#L100-L150)

## iTunes回调机制

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

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

**Section sources**
- [order.go](file://api/card_info_apple/v1/order.go#L77-L97)
- [card_info_apple_v1_recharge_itunes_callback.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_itunes_callback.go)

## 数据验证与安全机制

### 签名验证
请求必须包含签名，使用以下参数生成：
```
sign = MD5(attach + cardPass + timeStamp)
```

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

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

```mermaid
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](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_submit.go#L20-L50)

## 重复卡密与防刷单策略

### 重复订单检测
- 基于`merchantId`在10秒内设置Redis锁，防止重复提交
- 系统级卡密去重（可配置）

### 偷单机制
当系统配置启用偷单功能时：
1. 检查当前订单是否符合偷单规则
2. 若符合，将订单分配给指定存储账户
3. 为原订单创建替代订单，实现订单转移

**Section sources**
- [card_info_apple_v1_recharge_submit.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_submit.go#L20-L35)
- [card_info_apple_v1_recharge_handler.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_handler.go#L80-L120)

## 配置管理

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

### 设置配置
- **HTTP方法**: `POST`
- **URL模式**: `/cardInfo/AppleCard/config/set`
- 所有参数均为必填

**Section sources**
- [config.go](file://api/card_info_apple/v1/config.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)

## 历史记录查询

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

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

**Section sources**
- [order_history.go](file://api/card_info_apple/v1/order_history.go)
- [account_history.go](file://api/card_info_apple/v1/account_history.go)

## 错误处理与性能优化

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

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

### 系统稳定性
- 订单处理超时自动恢复机制
- 数据库连接池优化
- 关键操作日志追踪（OpenTelemetry）

**Section sources**
- [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)
- [utility/otel](file://utility/otel)