Files

danial 96ed936079 docs(api): 添加详细Apple卡密管理API文档

- 新增API端点参考文档，涵盖权限、卡密、订单、商户、监控、限制等模块
- 详细说明Apple卡密充值处理流程，包括提交、查询、回调和轮询接口
- 描述充值订单状态机及生命周期，支持超时重试和状态迁移
- 介绍签名验证、幂等控制及重复卡密防刷单策略
- 增加商户配置管理、历史记录查询和错误处理机制说明
- 提供API使用示例代码及客户端实现指导
- 删除过时的.drone.yml.bak文件，清理无用配置
- 添加.dockerignore忽略指定目录和文件

2025-10-08 20:13:40 +08:00

15 KiB

Raw Blame History

沃尔玛卡密管理API

**本文档引用文件** - [card_info_walmart.go](file://api/card_info_walmart/card_info_walmart.go) - [account.go](file://api/card_info_walmart/v1/account.go) - [group.go](file://api/card_info_walmart/v1/group.go) - [order.go](file://api/card_info_walmart/v1/order.go) - [stats.go](file://api/card_info_walmart/v1/stats.go) - [card_info_walmart_v1_account_create.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_account_create.go) - [card_info_walmart_v1_account_list.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_account_list.go) - [card_info_walmart_v1_group_add.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_group_add.go) - [card_info_walmart_v1_submit.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_submit.go) - [card_redeem.go](file://internal/consts/card_redeem.go) - [card_redeem_cookie.go](file://internal/consts/card_redeem_cookie.go) - [v_1_card_redeem_account_info.go](file://internal/model/entity/v_1_card_redeem_account_info.go) - [v_1_card_redeem_order_info.go](file://internal/model/entity/v_1_card_redeem_order_info.go) - [v_1_card_redeem_account_group.go](file://internal/model/entity/v_1_card_redeem_account_group.go)

简介

沃尔玛卡密管理API提供了一套完整的接口，用于管理沃尔玛礼品卡账户、订单处理和分组管理。该系统支持账户创建、状态检测、订单提交、分组管理等功能，专为高效处理沃尔玛卡密兑换而设计。API具备批量验证、状态重置、分组统计等高级功能，确保账户状态与沃尔玛平台保持同步，并遵守平台的调用限制。

项目结构

沃尔玛卡密管理模块位于api/card_info_walmart目录下，采用分层架构设计。该模块包含v1版本的API定义和对应的控制器实现，分别位于v1子目录和internal/controller/card_info_walmart目录中。数据模型定义在internal/model/entity目录下，常量定义在internal/consts目录中。

graph TD
subgraph "API接口层"
A[card_info_walmart.go]
B[account.go]
C[group.go]
D[order.go]
E[stats.go]
end
subgraph "控制器层"
F[card_info_walmart_v1_account_create.go]
G[card_info_walmart_v1_account_list.go]
H[card_info_walmart_v1_group_add.go]
I[card_info_walmart_v1_submit.go]
end
subgraph "模型层"
J[v_1_card_redeem_account_info.go]
K[v_1_card_redeem_order_info.go]
L[v_1_card_redeem_account_group.go]
end
subgraph "常量层"
M[card_redeem.go]
N[card_redeem_cookie.go]
end
A --> F
B --> G
C --> H
D --> I
J --> F
K --> I
M --> F
N --> F

图示来源

节来源

核心组件

沃尔玛卡密管理API的核心组件包括账户管理、分组管理、订单处理和统计分析四大模块。账户管理模块负责沃尔玛账户的创建、更新、删除和状态检测；分组管理模块提供账户分组的增删改查和统计功能；订单处理模块处理卡密兑换请求和订单状态管理；统计分析模块提供账户和订单的汇总数据。

节来源

架构概览

沃尔玛卡密管理API采用典型的三层架构：API接口层、业务逻辑层和数据访问层。API接口层定义了所有对外暴露的HTTP端点；业务逻辑层（控制器）处理具体的业务逻辑；数据访问层通过实体模型与数据库交互。系统通过常量文件定义了各种状态码和枚举值，确保代码的一致性和可维护性。

graph TB
subgraph "表现层"
API[API接口]
end
subgraph "业务逻辑层"
Controller[控制器]
end
subgraph "数据层"
Service[服务]
Model[数据模型]
Const[常量]
end
API --> Controller
Controller --> Service
Service --> Model
Service --> Const

图示来源

详细组件分析

账户管理分析

账户管理组件提供了完整的沃尔玛账户生命周期管理功能，包括创建、更新、删除、状态检测和批量操作。

账户创建与更新

classDiagram
class AccountRecord {
+string Cookie
+string Name
+int GroupId
+int MaxAmountLimit
+int MaxCountLimit
+int Status
+string Remark
}
class AccountCreateReq {
+AccountRecord
}
class AccountUpdateReq {
+string Id
+AccountRecord
}
class AccountListRecord {
+V1CardRedeemAccountInfo
+UploadUser
}
AccountCreateReq --> AccountRecord : "包含"
AccountUpdateReq --> AccountRecord : "包含"
AccountListRecord --> V1CardRedeemAccountInfo : "扩展"

图示来源

账户状态检测流程

sequenceDiagram
participant Client as "客户端"
participant API as "API接口"
participant Controller as "控制器"
participant Service as "服务层"
participant Walmart as "沃尔玛平台"
Client->>API : GET /cardInfo/walmart/account/statusDetect?id=xxx
API->>Controller : 调用AccountStatusDetect
Controller->>Service : 查询账户信息
Service->>Walmart : 验证Cookie有效性
Walmart-->>Service : 返回账户状态
Service-->>Controller : 返回检测结果
Controller-->>API : 返回响应
API-->>Client : {status : true/false}

图示来源

批量账户验证流程

flowchart TD
Start([开始]) --> Upload["上传Excel文件"]
Upload --> Validate["验证文件格式"]
Validate --> Process["逐行处理账户"]
Process --> CheckCookie["调用沃尔玛API验证Cookie"]
CheckCookie --> IsValid{"Cookie有效?"}
IsValid --> |是| Success["标记为可用"]
IsValid --> |否| Fail["标记为不可用"]
Success --> Next
Fail --> Next
Next["处理下一个账户"] --> Process
Process --> EndLoop{"所有账户处理完毕?"}
EndLoop --> |否| Process
EndLoop --> |是| Generate["生成验证结果"]
Generate --> Return["返回验证结果列表"]
Return --> End([结束])

图示来源

节来源

分组管理分析

分组管理组件提供了对沃尔玛账户的分组管理功能，支持分组的创建、更新、删除和统计分析。

分组管理类图

classDiagram
class GroupRecord {
+string Name
+string Notes
}
class GroupAddReq {
+GroupRecord
}
class GroupUpdateReq {
+int Id
+GroupRecord
}
class V1CardRedeemAccountGroup {
+int Id
+string Name
+string Notes
+string Category
+string CreatedUserId
+datetime CreatedAt
+datetime UpdatedAt
+datetime DeletedAt
}
GroupAddReq --> GroupRecord : "包含"
GroupUpdateReq --> GroupRecord : "包含"
V1CardRedeemAccountGroup --> GroupRecord : "扩展"

图示来源

分组统计功能

sequenceDiagram
participant Client as "客户端"
participant API as "API接口"
participant Controller as "控制器"
participant Service as "服务层"
participant DB as "数据库"
Client->>API : GET /cardInfo/walmart/group/stat?date=2023-01-01
API->>Controller : 调用GroupStat
Controller->>Service : 获取分组统计输入
Service->>DB : 查询分组统计数据
DB-->>Service : 返回统计结果
Service-->>Controller : 处理账户状态统计
Controller-->>API : 返回分组统计
API-->>Client : 返回分组统计结果

图示来源

节来源

订单处理分析

订单处理组件负责沃尔玛卡密的兑换流程，包括订单提交、状态查询和回调处理。

订单提交流程

sequenceDiagram
participant Client as "客户端"
participant API as "API接口"
participant Controller as "控制器"
participant Service as "服务层"
participant Walmart as "沃尔玛平台"
Client->>API : POST /cardInfo/walmart/order/submit
API->>Controller : 调用Submit
Controller->>Service : 验证订单参数
Service->>Service : 分配可用账户
Service->>Walmart : 提交卡密兑换
Walmart-->>Service : 返回兑换结果
Service-->>Controller : 处理订单状态
Controller-->>API : 返回响应
API-->>Client : 返回订单结果

图示来源

订单状态重置

flowchart TD
Start([开始]) --> GetOrder["获取订单信息"]
GetOrder --> CheckStatus{"订单状态?"}
CheckStatus --> |失败| Reset["重置订单状态"]
CheckStatus --> |成功| End1([结束])
CheckStatus --> |处理中| CheckTimeout{"超时?"}
CheckTimeout --> |是| Reset
CheckTimeout --> |否| End2([结束])
Reset --> UpdateDB["更新数据库状态"]
UpdateDB --> Notify["通知相关系统"]
Notify --> End([结束])

图示来源

节来源

统计分析组件

统计分析组件提供沃尔玛卡密系统的整体运营数据，帮助管理员了解系统运行状况。

统计概览接口

classDiagram
class StatsOverviewReq {
+int64 GroupId
+datetime[] DateRange
+string AccountId
}
class StatsOverviewRes {
+int TotalActiveAccountCount
+int TotalAccountCount
+float TotalOrderAmount
+float TotalOrderAmountSuccess
+int TotalOrderCount
+int TotalOrderCountSuccess
}
class StatsOverviewDownloadReq {
+int64 GroupId
+string AccountId
}
StatsOverviewReq --> StatsOverviewDownloadReq : "继承"

图示来源

stats.go

节来源

依赖分析

沃尔玛卡密管理API的依赖关系清晰，各组件之间耦合度低，便于维护和扩展。

graph TD
API[API接口] --> Controller[控制器]
Controller --> Service[服务层]
Service --> Model[数据模型]
Service --> Const[常量]
Model --> DB[(数据库)]
Const --> Controller
Const --> Service
style API fill:#f9f,stroke:#333
style Controller fill:#bbf,stroke:#333
style Service fill:#f96,stroke:#333
style Model fill:#6f9,stroke:#333
style Const fill:#69f,stroke:#333
style DB fill:#9f9,stroke:#333

图示来源

节来源

性能考虑

沃尔玛卡密管理API在设计时充分考虑了性能因素。批量操作采用流式处理，避免内存溢出；数据库查询使用索引优化，提高查询效率；状态检测采用缓存机制，减少对沃尔玛平台的频繁调用。系统还实现了限流机制，防止对沃尔玛API的过度调用。

故障排除指南

当遇到问题时，可按照以下步骤进行排查：

检查账户Cookie是否有效，可通过状态检测接口验证
确认账户状态是否正常，禁用的账户无法处理订单
检查分组配置是否正确，确保账户分配到正确的分组
查看订单历史，分析失败订单的具体原因
检查系统日志，获取详细的错误信息

节来源

结论

沃尔玛卡密管理API提供了一套完整、高效的解决方案，用于管理沃尔玛礼品卡的兑换流程。系统设计合理，功能完善，具备良好的可扩展性和可维护性。通过合理的账户管理、分组策略和状态同步机制，确保了系统的稳定运行和高效处理能力。

15 KiB Raw Blame History Unescape Escape

沃尔玛卡密管理API

目录

简介

项目结构

核心组件

架构概览

详细组件分析

账户管理分析

账户创建与更新

账户状态检测流程

批量账户验证流程

分组管理分析

分组管理类图

分组统计功能

订单处理分析

订单提交流程

订单状态重置

统计分析组件

统计概览接口

依赖分析

性能考虑

故障排除指南

结论

15 KiB

Raw Blame History