danial/kami_backend
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Files
15e2426e85a3a02e0f6b0983bd7aa8540212841a
kami_backend/.qoder/repowiki/zh/content/外部集成/Apple Integration.md
danial 15e2426e85 feat(camel_oil): 新增骆驼加油账号管理模块 
- 实现账号增删改查接口和逻辑
- 支持账号状态更新及状态历史记录功能
- 提供账号列表、历史和统计信息查询API
- 实现账号轮询机制，支持按使用时间轮询获取账号
- 增加账号登录流程及批量登录功能，集成接码平台和平台API
- 管理账号订单容量，支持容量检查与账号登录触发
- 提供账号池状态统计接口
- 账号历史记录查询支持多种变更类型文本展示
- 密码等敏感信息采用脱敏展示
- 完善日志记录和错误处理机制，保证业务稳定运行
2025-11-21 00:49:50 +08:00

14 KiB
Raw Blame History

Apple集成

**本文档引用的文件** - [card_info_apple.go](file://api/card_info_apple/card_info_apple.go) - [model.go](file://api/card_info_apple/v1/model.go) - [card_apple_account.go](file://internal/model/card_apple_account.go) - [card_apple_order.go](file://internal/model/card_apple_order.go) - [card_info_apple.go](file://internal/controller/card_info_apple/card_info_apple.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_list.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_list.go) - [card_info_apple_v1_card_info_list.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_list.go) - [api.go](file://utility/integration/apple/api.go) - [card_apple.go](file://internal/consts/card_apple.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.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_submit.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_card_history_info_list.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_history_info_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) - [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_rule_list.go](file://internal/controller/card_info_apple/card_info_apple_v1_recharge_steal_rule_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_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_suspend_or_continue.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_suspend_or_continue.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_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_call_back_order_manual.go](file://internal/controller/card_info_apple/card_info_apple_v1_call_back_order_manual.go)

目录

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

简介

本文档详细介绍了kami_backend项目中Apple集成的实现。该系统提供了一套完整的苹果卡密充值解决方案，包括账户管理、订单处理、状态跟踪和异常处理等功能。系统支持多商户环境下的卡密充值业务，具备账户分配算法、偷卡模式等高级功能。

项目结构

Apple集成相关的代码分布在多个目录中，形成了清晰的分层架构：

graph TD
subgraph API层
A[api/card_info_apple/v1]
B[api/card_info_apple]
end
subgraph 控制器层
C[internal/controller/card_info_apple]
end
subgraph 服务层
D[internal/service]
end
subgraph 模型层
E[internal/model]
F[internal/consts]
end
subgraph 集成层
G[utility/integration/apple]
end
A --> C
B --> C
C --> D
D --> E
D --> F
C --> G

图源

本节来源

核心组件

Apple集成系统由多个核心组件构成，包括账户管理、订单处理、状态管理、配置管理和安全控制等。这些组件协同工作，实现了完整的苹果卡密充值流程。

本节来源

架构概述

Apple集成系统采用分层架构设计，各层职责分明，便于维护和扩展。

graph TD
Client[客户端] --> API[API接口]
API --> Controller[控制器层]
Controller --> Service[服务层]
Service --> Model[模型层]
Service --> Database[(数据库)]
Service --> External[外部服务]
Controller --> Integration[集成层]
classDef default fill:#f9f9f9,stroke:#333,stroke-width:1px;
class Client,API,Controller,Service,Model,Database,External,Integration default;

图源

详细组件分析

Apple账户管理分析

Apple账户管理组件负责处理所有与苹果账户相关的操作，包括账户的创建、更新、删除和查询。

账户数据结构

classDiagram
class AppleAccountRecord {
+string Id
+string Account
+string Password
+float64 Balance
+int32 Status
+int64 MaxRechargeCount
+float64 MaxRechargeAmount
}
class AppleAccountListOutput {
+V1CardAppleAccountInfo
+V1SysUserRecord UploadUser
}
class V1SysUserRecord {
+string Id
+string Username
+string NickName
}
AppleAccountListOutput --> V1SysUserRecord : "包含"
AppleAccountListOutput --> V1CardAppleAccountInfo : "继承"
AppleAccountRecord --> V1CardAppleAccountInfo : "继承"

图源

本节来源

Apple订单处理分析

Apple订单处理是系统的核心功能，负责处理充值请求、分配账户、跟踪状态和回调处理。

订单处理流程

sequenceDiagram
participant Client as "客户端"
participant Controller as "控制器"
participant Service as "服务层"
participant Database as "数据库"
Client->>Controller : 提交充值请求
Controller->>Service : 获取待处理订单
Service->>Service : 获取符合条件的账户
Service->>Service : 检查偷卡规则
alt 符合偷卡条件
Service->>Service : 创建新订单
Service->>Service : 更新偷卡规则
end
Service->>Database : 分配账户并更新状态
Database-->>Service : 返回结果
Service-->>Controller : 返回账户信息
Controller-->>Client : 返回分配结果
Note over Controller,Service : 订单处理包含超时检测机制

图源

本节来源

Apple状态管理分析

Apple状态管理系统负责跟踪账户和订单的各种状态，确保系统的稳定运行。

状态定义

stateDiagram-v2
[*] --> AppleAccountStatus
AppleAccountStatus --> AppleRechargeOrderStatus
AppleRechargeOrderStatus --> AppleOrderItunesStatus
state AppleAccountStatus {
[*] --> AppleAccountForbidden
AppleAccountForbidden --> AppleAccountNormal
AppleAccountNormal --> AppleAccountWrongPassword
AppleAccountNormal --> AppleAccountLimited
AppleAccountNormal --> AppleAccountTmpStoppedByTooManyRequest
AppleAccountTmpStoppedByTooManyRequest --> AppleAccountNormal
}
state AppleRechargeOrderStatus {
[*] --> AppleRechargeOrderWaiting
AppleRechargeOrderWaiting --> AppleRechargeOrderProcessing
AppleRechargeOrderProcessing --> AppleRechargeOrderSuccess
AppleRechargeOrderProcessing --> AppleRechargeOrderFail
AppleRechargeOrderProcessing --> AppleRechargeOrderLimited
AppleRechargeOrderProcessing --> AppleRechargeOrderExpired
}
state AppleOrderItunesStatus {
[*] --> AppleRechargeItunesStatusSuccess
AppleRechargeItunesStatusSuccess --> AppleRechargeItunesRefund
AppleRechargeItunesStatusFail --> AppleRechargeItunesStatusFailWithWrongCode
AppleRechargeItunesStatusFail --> AppleRechargeItunesStatusFailWithRepeatCharge
AppleRechargeItunesStatusFail --> AppleRechargeItunesStatusWrongPassword
}

图源

本节来源

Apple配置管理分析

Apple配置管理系统提供了灵活的配置选项，支持动态调整系统行为。

配置管理流程

flowchart TD
Start([开始]) --> GetConfig["获取配置信息"]
GetConfig --> CheckSteal["检查偷卡模式"]
CheckSteal --> |开启| SetStealRule["设置偷卡规则"]
CheckSteal --> |关闭| ReturnNormal["返回正常模式"]
SetStealRule --> SaveConfig["保存配置"]
SaveConfig --> UpdateCache["更新缓存"]
UpdateCache --> End([结束])
ReturnNormal --> End

图源

本节来源

依赖分析

Apple集成系统依赖于多个内部和外部组件，形成了复杂的依赖关系网络。

graph TD
Controller[card_info_apple控制器] --> Service[AppleAccount服务]
Controller --> Service2[AppleOrder服务]
Controller --> Integration[Apple集成]
Service --> Model[card_apple_account模型]
Service2 --> Model2[card_apple_order模型]
Service --> Consts[card_apple常量]
Service2 --> Consts
Controller --> Auth[认证服务]
Controller --> Config[配置服务]
Integration --> HTTPClient[gclient]
style Controller fill:#e6f3ff,stroke:#333
style Service fill:#e6f3ff,stroke:#333
style Service2 fill:#e6f3ff,stroke:#333
style Model fill:#f0fff0,stroke:#333
style Model2 fill:#f0fff0,stroke:#333
style Consts fill:#fff0f0,stroke:#333
style Integration fill:#fff0f0,stroke:#333

图源

本节来源

性能考虑

Apple集成系统在设计时考虑了多种性能优化策略：

  1. 缓存机制：使用内存缓存存储频繁访问的数据，减少数据库查询
  2. 定时任务：使用gtimer和gcron处理异步任务，避免阻塞主线程
  3. 事务管理：合理使用数据库事务，确保数据一致性的同时优化性能
  4. 并发控制：使用gmutex进行并发控制，防止资源竞争
  5. 连接池：使用数据库连接池提高数据库访问效率

系统还实现了超时检测机制，对于长时间未处理的订单会自动重置状态，确保系统的健壮性。

故障排除指南

常见问题及解决方案

问题现象 可能原因 解决方案
订单长时间处于"等待充值"状态 超时检测未触发 检查定时任务是否正常运行
账户无法分配 账户状态异常 检查账户状态是否为正常可用
充值金额不一致 金额验证失败 使用手动修正金额功能
回调失败 网络问题或URL错误 检查回调URL配置和网络连接
偷卡功能未生效 配置未开启 检查偷卡模式是否已启用

调试工具

系统提供了多种调试工具：

  • 手动回调订单功能
  • 手动修正金额功能
  • 订单状态重置功能
  • 账户状态查询功能

本节来源

结论

Apple集成系统提供了一套完整的苹果卡密充值解决方案，具有以下特点：

  1. 功能完整：涵盖了账户管理、订单处理、状态跟踪等所有必要功能
  2. 架构清晰：采用分层架构，各组件职责分明
  3. 扩展性强：模块化设计，便于功能扩展
  4. 稳定性高：具备完善的错误处理和恢复机制
  5. 灵活性好：支持多种配置选项，适应不同业务需求

该系统能够有效支持多商户环境下的苹果卡密充值业务，为用户提供稳定可靠的服务。