# Apple卡密管理API

<cite>
**本文档引用的文件**
- [account_info.go](file://api/card_info_apple/v1/account_info.go)
- [order.go](file://api/card_info_apple/v1/order.go)
- [config.go](file://api/card_info_apple/v1/config.go)
- [model.go](file://api/card_info_apple/v1/model.go)
- [card_info_apple.go](file://api/card_info_apple/card_info_apple.go)
- [card_info_apple_v1_card_info_create.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_create.go)
- [card_info_apple_v1_card_info_list.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_list.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_list.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_list.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_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)
- [card_info_apple_v1_recharge_steal_rule_add.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_rule_add.go)
- [card_info_apple_v1_recharge_steal_rule_list.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_rule_list.go)
- [card_info_apple_v1_recharge_steal_setting.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_setting.go)
- [card_info_apple_v1_recharge_duplicated_card_pass.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_duplicated_card_pass.go)
- [card_info_apple_v1_call_back_order_manual.go](file://internal/controller/card_info_apple/card_info_apple_v1_call_back_order_manual.go)
- [card_info_apple_v1_recharge_order_modify_actual_amount.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_order_modify_actual_amount.go)
- [card_info_apple_v1_recharge_order_reset_status.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_order_reset_status.go)
- [card_info_apple_v1_card_info_update_status.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_update_status.go)
- [card_info_apple_v1_card_info_delete.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_delete.go)
- [card_info_apple_v1_card_info_batch_add_from_xlsx.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_batch_add_from_xlsx.go)
- [card_info_apple_v1_card_info_download_template.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_download_template.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_recharge_list_download.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_list_download.go)
- [card_info_apple_v1_card_history_info_list.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_history_info_list.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_submit_query.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_submit_query.go)
- [card_info_apple_v1_recharge_steal_rule_update.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_rule_update.go)
- [card_info_apple_v1_recharge_steal_rule_delete.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_rule_delete.go)
- [card_info_apple_v1_recharge_steal_rule_status_update.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_rule_status_update.go)
- [card_info_apple_v1_recharge_steal_setting_get.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_setting_get.go)
- [card_info_apple_v1_card_info_update.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_update.go)
- [card_info_apple_v1_card_info_suspend_or_continue.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_suspend_or_continue.go)
- [card_info_apple_v1_card_info_create.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_create.go)
- [card_info_apple_v1_card_info_list.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_list.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_list.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_list.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_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)
- [card_info_apple_v1_recharge_steal_rule_add.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_rule_add.go)
- [card_info_apple_v1_recharge_steal_rule_list.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_rule_list.go)
- [card_info_apple_v1_recharge_steal_setting.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_setting.go)
- [card_info_apple_v1_recharge_duplicated_card_pass.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_duplicated_card_pass.go)
- [card_info_apple_v1_call_back_order_manual.go](file://internal/controller/card_info_apple/card_info_apple_v1_call_back_order_manual.go)
- [card_info_apple_v1_recharge_order_modify_actual_amount.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_order_modify_actual_amount.go)
- [card_info_apple_v1_recharge_order_reset_status.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_order_reset_status.go)
- [card_info_apple_v1_card_info_update_status.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_update_status.go)
- [card_info_apple_v1_card_info_delete.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_delete.go)
- [card_info_apple_v1_card_info_batch_add_from_xlsx.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_batch_add_from_xlsx.go)
- [card_info_apple_v1_card_info_download_template.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_download_template.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_recharge_list_download.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_list_download.go)
- [card_info_apple_v1_card_history_info_list.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_history_info_list.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_submit_query.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_submit_query.go)
- [card_info_apple_v1_recharge_steal_rule_update.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_rule_update.go)
- [card_info_apple_v1_recharge_steal_rule_delete.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_rule_delete.go)
- [card_info_apple_v1_recharge_steal_rule_status_update.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_rule_status_update.go)
- [card_info_apple_v1_recharge_steal_setting_get.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_setting_get.go)
- [card_info_apple_v1_card_info_update.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_update.go)
- [card_info_apple_v1_card_info_suspend_or_continue.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_suspend_or_continue.go)
- [card_info_apple_v1_card_info_create.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_create.go)
- [card_info_apple_v1_card_info_list.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_list.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_list.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_list.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_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)
- [card_info_apple_v1_recharge_steal_rule_add.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_rule_add.go)
- [card_info_apple_v1_recharge_steal_rule_list.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_rule_list.go)
- [card_info_apple_v1_recharge_steal_setting.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_setting.go)
- [card_info_apple_v1_recharge_duplicated_card_pass.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_duplicated_card_pass.go)
- [card_info_apple_v1_call_back_order_manual.go](file://internal/controller/card_info_apple/card_info_apple_v1_call_back_order_manual.go)
- [card_info_apple_v1_recharge_order_modify_actual_amount.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_order_modify_actual_amount.go)
- [card_info_apple_v1_recharge_order_reset_status.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_order_reset_status.go)
- [card_info_apple_v1_card_info_update_status.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_update_status.go)
- [card_info_apple_v1_card_info_delete.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_delete.go)
- [card_info_apple_v1_card_info_batch_add_from_xlsx.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_batch_add_from_xlsx.go)
- [card_info_apple_v1_card_info_download_template.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_download_template.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_recharge_list_download.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_list_download.go)
- [card_info_apple_v1_card_history_info_list.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_history_info_list.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_submit_query.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_submit_query.go)
- [card_info_apple_v1_recharge_steal_rule_update.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_rule_update.go)
- [card_info_apple_v1_recharge_steal_rule_delete.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_rule_delete.go)
- [card_info_apple_v1_recharge_steal_rule_status_update.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_rule_status_update.go)
- [card_info_apple_v1_recharge_steal_setting_get.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_setting_get.go)
- [card_info_apple_v1_card_info_update.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_update.go)
- [card_info_apple_v1_card_info_suspend_or_continue.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_suspend_or_continue.go)
</cite>

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

## 简介
Apple卡密管理API是一个全面的系统，用于管理Apple卡密的账户、充值处理和订单回调。该API提供了账户创建、状态管理、充值提交和历史查询等端点。它还支持批量导入卡密、充值状态查询和重复卡密处理等场景。文档详细解释了Apple卡密特有的iTunes回调机制和防刷单规则，并提供了错误处理策略和安全考虑。此外，还包括客户端实现指南和性能优化建议，特别关注Apple平台的特殊要求和限制。

## 项目结构
项目结构遵循模块化设计，将不同功能分离到不同的目录中。主要目录包括`api`、`internal`、`manifest`、`resource`和`utility`。`api`目录包含所有API端点的定义，`internal`目录包含核心业务逻辑、数据访问对象（DAO）和服务。`manifest`目录包含配置文件，`resource`目录包含Casbin权限模型，`utility`目录包含各种实用工具和集成。

```mermaid
graph TD
subgraph "API"
A[card_info_apple]
B[card_info_c_trip]
C[card_info_jd]
D[card_info_original_jd]
E[card_info_t_mall_game]
F[card_info_walmart]
G[card_redeem_jd]
H[channel]
I[commonApi]
J[fund]
K[merchant]
L[monitor]
M[order]
N[restriction]
O[road]
P[road_pool]
Q[sysUser]
R[sys_auth_rule]
S[sys_payment]
T[sys_role]
U[sys_user_login]
V[user_center]
W[validation]
end
subgraph "Internal"
X[boot]
Y[cmd]
Z[consts]
AA[controller]
AB[dao]
AC[errHandler]
AD[logic]
AE[middleware]
AF[model]
AG[packed]
AH[service]
AI[systemV2]
end
subgraph "Manifest"
AJ[config]
AK[deploy]
AL[docker]
end
subgraph "Resource"
AM[casbin]
end
subgraph "Utility"
AN[cache]
AO[config]
AP[cron]
AQ[integration]
AR[lib]
AS[limiter]
AT[mfa]
AU[monitor]
AV[notify]
AW[otel]
AX[pool]
AY[token]
AZ[utils]
BA[verify]
end
A --> AA
B --> AA
C --> AA
D --> AA
E --> AA
F --> AA
G --> AA
H --> AA
I --> AA
J --> AA
K --> AA
L --> AA
M --> AA
N --> AA
O --> AA
P --> AA
Q --> AA
R --> AA
S --> AA
T --> AA
U --> AA
V --> AA
W --> AA
```

**图示来源**
- [api](file://api)
- [internal](file://internal)
- [manifest](file://manifest)
- [resource](file://resource)
- [utility](file://utility)

**章节来源**
- [api](file://api)
- [internal](file://internal)
- [manifest](file://manifest)
- [resource](file://resource)
- [utility](file://utility)

## 核心组件
核心组件包括账户管理、充值处理、订单回调和配置管理。账户管理负责创建、更新和删除Apple账户。充值处理负责提交和查询充值订单。订单回调处理来自iTunes的回调请求。配置管理允许用户获取和设置系统配置。

**章节来源**
- [account_info.go](file://api/card_info_apple/v1/account_info.go)
- [order.go](file://api/card_info_apple/v1/order.go)
- [config.go](file://api/card_info_apple/v1/config.go)

## 架构概述
系统架构采用分层设计，包括API层、控制器层、服务层、逻辑层和数据访问层。API层定义了所有端点，控制器层处理HTTP请求并调用服务层，服务层协调业务逻辑，逻辑层包含具体的业务规则，数据访问层负责与数据库交互。

```mermaid
graph TD
A[API层] --> B[控制器层]
B --> C[服务层]
C --> D[逻辑层]
D --> E[数据访问层]
E --> F[数据库]
```

**图示来源**
- [card_info_apple.go](file://api/card_info_apple/card_info_apple.go)
- [card_info_apple_v1_card_info_create.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_create.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_config_get.go](file://internal/controller/card_info_apple/card_info_apple_v1_config_get.go)

## 详细组件分析
### 账户管理分析
账户管理组件负责处理Apple账户的创建、更新、删除和查询。它还支持批量导入和导出账户信息。

#### 账户创建
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "控制器"
participant Service as "服务"
participant Logic as "逻辑"
participant DAO as "数据访问对象"
Client->>Controller : POST /api/apple/account/create
Controller->>Service : 调用Add方法
Service->>Logic : 调用Add方法
Logic->>DAO : 插入新账户
DAO-->>Logic : 返回结果
Logic-->>Service : 返回结果
Service-->>Controller : 返回结果
Controller-->>Client : 返回成功或错误
```

**图示来源**
- [card_info_apple_v1_card_info_create.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_create.go)
- [card_info_apple_v1_card_info_list.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_list.go)

#### 账户更新
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "控制器"
participant Service as "服务"
participant Logic as "逻辑"
participant DAO as "数据访问对象"
Client->>Controller : PUT /api/apple/account/update
Controller->>Service : 调用Update方法
Service->>Logic : 调用Update方法
Logic->>DAO : 更新账户信息
DAO-->>Logic : 返回结果
Logic-->>Service : 返回结果
Service-->>Controller : 返回结果
Controller-->>Client : 返回成功或错误
```

**图示来源**
- [card_info_apple_v1_card_info_update.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_update.go)
- [card_info_apple_v1_card_info_update_status.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_update_status.go)

#### 账户删除
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "控制器"
participant Service as "服务"
participant Logic as "逻辑"
participant DAO as "数据访问对象"
Client->>Controller : DELETE /api/apple/account/delete
Controller->>Service : 调用Delete方法
Service->>Logic : 调用Delete方法
Logic->>DAO : 删除账户
DAO-->>Logic : 返回结果
Logic-->>Service : 返回结果
Service-->>Controller : 返回结果
Controller-->>Client : 返回成功或错误
```

**图示来源**
- [card_info_apple_v1_card_info_delete.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_delete.go)

#### 批量导入账户
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "控制器"
participant Service as "服务"
participant Logic as "逻辑"
participant DAO as "数据访问对象"
Client->>Controller : POST /api/apple/account/batch-add
Controller->>Service : 调用Add方法
Service->>Logic : 调用Add方法
loop 每个账户
Logic->>DAO : 插入账户
DAO-->>Logic : 返回结果
end
Logic-->>Service : 返回结果
Service-->>Controller : 返回结果
Controller-->>Client : 返回成功或错误
```

**图示来源**
- [card_info_apple_v1_card_info_batch_add_from_xlsx.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_batch_add_from_xlsx.go)

**章节来源**
- [card_info_apple_v1_card_info_create.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_create.go)
- [card_info_apple_v1_card_info_update.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_update.go)
- [card_info_apple_v1_card_info_delete.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_delete.go)
- [card_info_apple_v1_card_info_batch_add_from_xlsx.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_batch_add_from_xlsx.go)
- [card_info_apple_v1_card_info_download_template.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_download_template.go)

### 充值处理分析
充值处理组件负责提交和查询充值订单。它还处理来自iTunes的回调请求。

#### 充值提交
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "控制器"
participant Service as "服务"
participant Logic as "逻辑"
participant DAO as "数据访问对象"
Client->>Controller : POST /api/apple/recharge/submit
Controller->>Service : 调用AddRechargeOrder方法
Service->>Logic : 调用AddRechargeOrder方法
Logic->>DAO : 插入充值订单
DAO-->>Logic : 返回结果
Logic-->>Service : 返回结果
Service-->>Controller : 返回结果
Controller-->>Client : 返回成功或错误
```

**图示来源**
- [card_info_apple_v1_recharge_submit.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_submit.go)

#### 充值查询
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "控制器"
participant Service as "服务"
participant Logic as "逻辑"
participant DAO as "数据访问对象"
Client->>Controller : GET /api/apple/recharge/list
Controller->>Service : 调用List方法
Service->>Logic : 调用List方法
Logic->>DAO : 查询充值订单
DAO-->>Logic : 返回结果
Logic-->>Service : 返回结果
Service-->>Controller : 返回结果
Controller-->>Client : 返回成功或错误
```

**图示来源**
- [card_info_apple_v1_recharge_list.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_list.go)

#### iTunes回调处理
```mermaid
sequenceDiagram
participant iTunes as "iTunes"
participant Controller as "控制器"
participant Service as "服务"
participant Logic as "逻辑"
participant DAO as "数据访问对象"
iTunes->>Controller : POST /api/apple/recharge/itunes-callback
Controller->>Service : 调用UpdateActualAmountAndHistoryAndWallet方法
Service->>Logic : 调用UpdateActualAmountAndHistoryAndWallet方法
Logic->>DAO : 更新充值订单和账户余额
DAO-->>Logic : 返回结果
Logic-->>Service : 返回结果
Service-->>Controller : 返回结果
Controller-->>iTunes : 返回成功或错误
```

**图示来源**
- [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.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_submit.go)
- [card_info_apple_v1_recharge_list.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_list.go)
- [card_info_apple_v1_recharge_itunes_callback.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_itunes_callback.go)

### 配置管理分析
配置管理组件允许用户获取和设置系统配置。

#### 获取配置
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "控制器"
participant Service as "服务"
participant Logic as "逻辑"
participant DAO as "数据访问对象"
Client->>Controller : GET /api/apple/config/get
Controller->>Service : 调用GetConfig方法
Service->>Logic : 调用GetConfig方法
Logic->>DAO : 查询配置
DAO-->>Logic : 返回结果
Logic-->>Service : 返回结果
Service-->>Controller : 返回结果
Controller-->>Client : 返回成功或错误
```

**图示来源**
- [card_info_apple_v1_config_get.go](file://internal/controller/card_info_apple/card_info_apple_v1_config_get.go)

#### 设置配置
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "控制器"
participant Service as "服务"
participant Logic as "逻辑"
participant DAO as "数据访问对象"
Client->>Controller : POST /api/apple/config/set
Controller->>Service : 调用SetConfig方法
Service->>Logic : 调用SetConfig方法
Logic->>DAO : 更新配置
DAO-->>Logic : 返回结果
Logic-->>Service : 返回结果
Service-->>Controller : 返回结果
Controller-->>Client : 返回成功或错误
```

**图示来源**
- [card_info_apple_v1_config_set.go](file://internal/controller/card_info_apple/card_info_apple_v1_config_set.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)

### 偷卡规则分析
偷卡规则组件允许用户管理偷卡规则，包括添加、更新、删除和查询规则。

#### 添加偷卡规则
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "控制器"
participant Service as "服务"
participant Logic as "逻辑"
participant DAO as "数据访问对象"
Client->>Controller : POST /api/apple/recharge/steal-rule/add
Controller->>Service : 调用AddStealRule方法
Service->>Logic : 调用AddStealRule方法
Logic->>DAO : 插入偷卡规则
DAO-->>Logic : 返回结果
Logic-->>Service : 返回结果
Service-->>Controller : 返回结果
Controller-->>Client : 返回成功或错误
```

**图示来源**
- [card_info_apple_v1_recharge_steal_rule_add.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_rule_add.go)

#### 查询偷卡规则
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "控制器"
participant Service as "服务"
participant Logic as "逻辑"
participant DAO as "数据访问对象"
Client->>Controller : GET /api/apple/recharge/steal-rule/list
Controller->>Service : 调用GetStealRuleList方法
Service->>Logic : 调用GetStealRuleList方法
Logic->>DAO : 查询偷卡规则
DAO-->>Logic : 返回结果
Logic-->>Service : 返回结果
Service-->>Controller : 返回结果
Controller-->>Client : 返回成功或错误
```

**图示来源**
- [card_info_apple_v1_recharge_steal_rule_list.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_rule_list.go)

#### 更新偷卡规则
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "控制器"
participant Service as "服务"
participant Logic as "逻辑"
participant DAO as "数据访问对象"
Client->>Controller : PUT /api/apple/recharge/steal-rule/update
Controller->>Service : 调用UpdateStealRule方法
Service->>Logic : 调用UpdateStealRule方法
Logic->>DAO : 更新偷卡规则
DAO-->>Logic : 返回结果
Logic-->>Service : 返回结果
Service-->>Controller : 返回结果
Controller-->>Client : 返回成功或错误
```

**图示来源**
- [card_info_apple_v1_recharge_steal_rule_update.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_rule_update.go)

#### 删除偷卡规则
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "控制器"
participant Service as "服务"
participant Logic as "逻辑"
participant DAO as "数据访问对象"
Client->>Controller : DELETE /api/apple/recharge/steal-rule/delete
Controller->>Service : 调用DeleteStealRule方法
Service->>Logic : 调用DeleteStealRule方法
Logic->>DAO : 删除偷卡规则
DAO-->>Logic : 返回结果
Logic-->>Service : 返回结果
Service-->>Controller : 返回结果
Controller-->>Client : 返回成功或错误
```

**图示来源**
- [card_info_apple_v1_recharge_steal_rule_delete.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_rule_delete.go)

**章节来源**
- [card_info_apple_v1_recharge_steal_rule_add.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_rule_add.go)
- [card_info_apple_v1_recharge_steal_rule_list.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_rule_list.go)
- [card_info_apple_v1_recharge_steal_rule_update.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_rule_update.go)
- [card_info_apple_v1_recharge_steal_rule_delete.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_rule_delete.go)
- [card_info_apple_v1_recharge_steal_rule_status_update.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_rule_status_update.go)
- [card_info_apple_v1_recharge_steal_setting.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_setting.go)
- [card_info_apple_v1_recharge_steal_setting_get.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_setting_get.go)

### 重复卡密处理分析
重复卡密处理组件负责处理重复提交的卡密。

#### 检查重复卡密
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "控制器"
participant Service as "服务"
participant Logic as "逻辑"
participant DAO as "数据访问对象"
Client->>Controller : POST /api/apple/recharge/duplicated-card-pass
Controller->>Service : 调用QueryDuplicatedCardPassV2方法
Service->>Logic : 调用QueryDuplicatedCardPassV2方法
Logic->>DAO : 查询重复卡密
DAO-->>Logic : 返回结果
Logic-->>Service : 返回结果
Service-->>Controller : 返回结果
Controller-->>Client : 返回成功或错误
```

**图示来源**
- [card_info_apple_v1_recharge_duplicated_card_pass.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_duplicated_card_pass.go)

**章节来源**
- [card_info_apple_v1_recharge_duplicated_card_pass.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_duplicated_card_pass.go)

### 手动回调订单分析
手动回调订单组件允许用户手动回调订单。

#### 手动回调订单
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "控制器"
participant Service as "服务"
participant Logic as "逻辑"
participant DAO as "数据访问对象"
Client->>Controller : POST /api/apple/recharge/call-back-order-manual
Controller->>Service : 调用CallBackOrderToUpstream方法
Service->>Logic : 调用CallBackOrderToUpstream方法
Logic->>DAO : 查询订单并回调
DAO-->>Logic : 返回结果
Logic-->>Service : 返回结果
Service-->>Controller : 返回结果
Controller-->>Client : 返回成功或错误
```

**图示来源**
- [card_info_apple_v1_call_back_order_manual.go](file://internal/controller/card_info_apple/card_info_apple_v1_call_back_order_manual.go)

**章节来源**
- [card_info_apple_v1_call_back_order_manual.go](file://internal/controller/card_info_apple/card_info_apple_v1_call_back_order_manual.go)

### 充值订单状态修改分析
充值订单状态修改组件允许用户修改充值订单的状态。

#### 修改充值订单状态
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "控制器"
participant Service as "服务"
participant Logic as "逻辑"
participant DAO as "数据访问对象"
Client->>Controller : POST /api/apple/recharge/order-modify-actual-amount
Controller->>Service : 调用UpdateActualAmount方法
Service->>Logic : 调用UpdateActualAmount方法
Logic->>DAO : 更新订单状态
DAO-->>Logic : 返回结果
Logic-->>Service : 返回结果
Service-->>Controller : 返回结果
Controller-->>Client : 返回成功或错误
```

**图示来源**
- [card_info_apple_v1_recharge_order_modify_actual_amount.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_order_modify_actual_amount.go)

**章节来源**
- [card_info_apple_v1_recharge_order_modify_actual_amount.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_order_modify_actual_amount.go)

### 充值订单状态重置分析
充值订单状态重置组件允许用户重置充值订单的状态。

#### 重置充值订单状态
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "控制器"
participant Service as "服务"
participant Logic as "逻辑"
participant DAO as "数据访问对象"
Client->>Controller : POST /api/apple/recharge/order-reset-status
Controller->>Service : 调用ResetDistributionCount方法
Service->>Logic : 调用ResetDistributionCount方法
Logic->>DAO : 重置订单状态
DAO-->>Logic : 返回结果
Logic-->>Service : 返回结果
Service-->>Controller : 返回结果
Controller-->>Client : 返回成功或错误
```

**图示来源**
- [card_info_apple_v1_recharge_order_reset_status.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_order_reset_status.go)

**章节来源**
- [card_info_apple_v1_recharge_order_reset_status.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_order_reset_status.go)

### 账户状态暂停或继续分析
账户状态暂停或继续组件允许用户暂停或继续账户的状态。

#### 暂停或继续账户状态
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "控制器"
participant Service as "服务"
participant Logic as "逻辑"
participant DAO as "数据访问对象"
Client->>Controller : POST /api/apple/account/suspend-or-continue
Controller->>Service : 调用ModifyStatus方法
Service->>Logic : 调用ModifyStatus方法
Logic->>DAO : 更新账户状态
DAO-->>Logic : 返回结果
Logic-->>Service : 返回结果
Service-->>Controller : 返回结果
Controller-->>Client : 返回成功或错误
```

**图示来源**
- [card_info_apple_v1_card_info_suspend_or_continue.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_suspend_or_continue.go)

**章节来源**
- [card_info_apple_v1_card_info_suspend_or_continue.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_suspend_or_continue.go)

### 充值历史查询分析
充值历史查询组件允许用户查询充值历史。

#### 查询充值历史
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "控制器"
participant Service as "服务"
participant Logic as "逻辑"
participant DAO as "数据访问对象"
Client->>Controller : GET /api/apple/recharge/history-list
Controller->>Service : 调用GetRechargeDetails方法
Service->>Logic : 调用GetRechargeDetails方法
Logic->>DAO : 查询充值历史
DAO-->>Logic : 返回结果
Logic-->>Service : 返回结果
Service-->>Controller : 返回结果
Controller-->>Client : 返回成功或错误
```

**图示来源**
- [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_recharge_history_list.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_history_list.go)

### 充值列表下载分析
充值列表下载组件允许用户下载充值列表。

#### 下载充值列表
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "控制器"
participant Service as "服务"
participant Logic as "逻辑"
participant DAO as "数据访问对象"
Client->>Controller : GET /api/apple/recharge/list-download
Controller->>Service : 调用ListWithAccount方法
Service->>Logic : 调用ListWithAccount方法
Logic->>DAO : 查询充值列表
DAO-->>Logic : 返回结果
Logic-->>Service : 返回结果
Service-->>Controller : 返回结果
Controller-->>Client : 返回成功或错误
```

**图示来源**
- [card_info_apple_v1_recharge_list_download.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_list_download.go)

**章节来源**
- [card_info_apple_v1_recharge_list_download.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_list_download.go)

### 账户历史信息查询分析
账户历史信息查询组件允许用户查询账户历史信息。

#### 查询账户历史信息
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "控制器"
participant Service as "服务"
participant Logic as "逻辑"
participant DAO as "数据访问对象"
Client->>Controller : GET /api/apple/account/history-info-list
Controller->>Service : 调用GetWalletHistory方法
Service->>Logic : 调用GetWalletHistory方法
Logic->>DAO : 查询账户历史信息
DAO-->>Logic : 返回结果
Logic-->>Service : 返回结果
Service-->>Controller : 返回结果
Controller-->>Client : 返回成功或错误
```

**图示来源**
- [card_info_apple_v1_card_history_info_list.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_history_info_list.go)

**章节来源**
- [card_info_apple_v1_card_history_info_list.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_history_info_list.go)

### 充值处理分析
充值处理组件负责处理充值请求。

#### 处理充值请求
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "控制器"
participant Service as "服务"
participant Logic as "逻辑"
participant DAO as "数据访问对象"
Client->>Controller : POST /api/apple/recharge/handler
Controller->>Service : 调用HandleWaitingList方法
Service->>Logic : 调用HandleWaitingList方法
Logic->>DAO : 处理等待中的充值订单
DAO-->>Logic : 返回结果
Logic-->>Service : 返回结果
Service-->>Controller : 返回结果
Controller-->>Client : 返回成功或错误
```

**图示来源**
- [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_handler.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_handler.go)

### 充值提交查询分析
充值提交查询组件允许用户查询充值提交的状态。

#### 查询充值提交状态
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "控制器"
participant Service as "服务"
participant Logic as "逻辑"
participant DAO as "数据访问对象"
Client->>Controller : GET /api/apple/recharge/submit-query
Controller->>Service : 调用GetRechargeStatusByOrderNo方法
Service->>Logic : 调用GetRechargeStatusByOrderNo方法
Logic->>DAO : 查询充值提交状态
DAO-->>Logic : 返回结果
Logic-->>Service : 返回结果
Service-->>Controller : 返回结果
Controller-->>Client : 返回成功或错误
```

**图示来源**
- [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_submit_query.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_submit_query.go)

## 依赖分析
系统依赖于多个外部组件和库，包括GoFrame框架、GDB数据库驱动、ShopSpring Decimal库等。这些依赖项在`go.mod`文件中定义，并通过Go模块系统进行管理。

```mermaid
graph TD
A[Apple卡密管理API] --> B[GoFrame框架]
A --> C[GDB数据库驱动]
A --> D[ShopSpring Decimal库]
A --> E[Casbin权限库]
A --> F[Redis缓存]
A --> G[MySQL数据库]
```

**图示来源**
- [go.mod](file://go.mod)
- [go.sum](file://go.sum)

**章节来源**
- [go.mod](file://go.mod)
- [go.sum](file://go.sum)

## 性能考虑
为了确保系统的高性能，采用了多种优化策略。包括使用Redis缓存频繁访问的数据，使用数据库索引优化查询性能，使用并发处理提高处理速度，以及使用连接池管理数据库连接。

**章节来源**
- [utility/cache](file://utility/cache)
- [utility/limiter](file://utility/limiter)
- [utility/pool](file://utility/pool)

## 故障排除指南
### 常见问题
1. **账户创建失败**：检查请求参数是否正确，特别是账户名和密码。
2. **充值提交失败**：检查卡密是否正确，以及账户是否有足够的余额。
3. **回调失败**：检查回调URL是否正确，以及服务器是否能够接收POST请求。
4. **配置更新失败**：检查配置参数是否在允许范围内。

### 错误处理
系统使用统一的错误处理机制，所有错误都通过`errHandler`包进行处理。错误码和错误信息在`errHandler/code.go`文件中定义。

**章节来源**
- [internal/errHandler/code.go](file://internal/errHandler/code.go)
- [internal/errHandler/handler.go](file://internal/errHandler/handler.go)

## 结论
Apple卡密管理API提供了一套完整的解决方案，用于管理Apple卡密的账户、充值和订单回调。通过详细的文档和示例，用户可以轻松地集成和使用该API。系统设计考虑了性能、安全性和可扩展性，确保在高负载下仍能稳定运行。