danial/kami_backend
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Files
96ed936079e5e9da79410aefaf8bd7728771eaff
kami_backend/.qoder/repowiki/zh/content/API端点参考/卡密信息管理API/京东卡密管理API/京东卡密账户管理.md
danial 96ed936079 docs(api): 添加详细Apple卡密管理API文档 
- 新增API端点参考文档，涵盖权限、卡密、订单、商户、监控、限制等模块
- 详细说明Apple卡密充值处理流程，包括提交、查询、回调和轮询接口
- 描述充值订单状态机及生命周期，支持超时重试和状态迁移
- 介绍签名验证、幂等控制及重复卡密防刷单策略
- 增加商户配置管理、历史记录查询和错误处理机制说明
- 提供API使用示例代码及客户端实现指导
- 删除过时的.drone.yml.bak文件，清理无用配置
- 添加.dockerignore忽略指定目录和文件
2025-10-08 20:13:40 +08:00

12 KiB
Raw Blame History

京东卡密账户管理

**本文档引用文件** - [account.go](file://api/card_redeem_jd/v1/account.go) - [card_info_jd_v1_jd_account_create.go](file://internal/controller/card_info_jd/card_info_jd_v1_jd_account_create.go) - [card_info_jd_v1_jd_account_update.go](file://internal/controller/card_info_jd/card_info_jd_v1_jd_account_update.go) - [card_info_jd_v1_jd_account_delete.go](file://internal/controller/card_info_jd/card_info_jd_v1_jd_account_delete.go) - [card_info_jd_v1_jd_account_cookie_batch_add.go](file://internal/controller/card_info_jd/card_info_jd_v1_jd_account_cookie_batch_add.go) - [card_info_jd_v1_jd_account_cookie_check.go](file://internal/controller/card_info_jd/card_info_jd_v1_jd_account_cookie_check.go) - [card_info_original_jd_v1_original_jd_account_cookie_batch_add.go](file://internal/controller/card_info_original_jd/card_info_original_jd_v1_original_jd_account_cookie_batch_add.go) - [card_redeem_jd_v1_account_add.go](file://internal/controller/card_redeem_jd/card_redeem_jd_v1_account_add.go) - [card_redeem_account.go](file://internal/service/card_redeem_account.go) - [card_redeem_cookie.go](file://internal/service/card_redeem_cookie.go) - [originalJd/index.go](file://utility/integration/originalJd/index.go) - [originalJd/model.go](file://utility/integration/originalJd/model.go) - [card_redeem_account/schdule.go](file://internal/logic/card_redeem_account/schdule.go) - [card_apple_account/status.go](file://internal/logic/card_apple_account/status.go)

目录

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

简介

本文档详细说明了京东卡密账户管理API的设计与实现，涵盖账户的创建、更新、删除和查询接口。重点描述了批量添加京东账户Cookie的实现机制，包括Cookie验证、状态检测和刷新策略。文档还提供了实际使用示例，如批量导入账户、账户状态监控和Cookie有效性验证等场景。同时解释了账户与京东平台的交互机制，包括登录状态管理、反爬虫策略应对和请求频率控制，并包含错误处理策略、安全考虑和性能优化建议。

项目结构

京东卡密账户管理功能主要分布在api/card_redeem_jd和internal/controller/card_info_jd目录下。核心API定义在api/card_redeem_jd/v1/account.go中，控制器实现位于internal/controller/card_info_jd/目录下。账户相关的业务逻辑由internal/service/card_redeem_account.go和internal/service/card_redeem_cookie.go提供服务接口。京东平台交互通过utility/integration/originalJd/中的客户端实现。

graph TB
subgraph "API层"
A[account.go]
end
subgraph "控制器层"
B[card_info_jd_v1_jd_account_create.go]
C[card_info_jd_v1_jd_account_update.go]
D[card_info_jd_v1_jd_account_delete.go]
E[card_info_jd_v1_jd_account_cookie_batch_add.go]
end
subgraph "服务层"
F[card_redeem_account.go]
G[card_redeem_cookie.go]
end
subgraph "集成层"
H[originalJd/index.go]
I[originalJd/model.go]
end
A --> B
B --> F
F --> H
H --> I

Diagram sources

Section sources

核心组件

京东卡密账户管理的核心组件包括账户管理API、批量Cookie处理、状态验证机制和京东平台集成。账户管理API提供标准的CRUD操作，支持通过HTTP接口进行账户的创建、更新、删除和查询。批量Cookie处理功能允许用户一次性导入多个京东账户的Cookie信息。状态验证机制确保账户的可用性，并定期刷新账户状态。京东平台集成组件负责与京东API进行通信，执行登录验证、余额查询等操作。

Section sources

架构概述

系统采用分层架构设计，从上到下分为API层、控制器层、服务层和集成层。API层定义了所有对外暴露的HTTP接口，使用GoFrame框架的元数据注解来配置路由、方法和参数。控制器层负责处理HTTP请求，进行权限验证和参数校验，然后调用相应的服务层方法。服务层封装了业务逻辑，提供统一的接口供控制器调用。集成层包含与京东平台交互的具体实现，通过HTTP客户端调用京东API。

graph TD
Client[客户端] --> API[API层]
API --> Controller[控制器层]
Controller --> Service[服务层]
Service --> Integration[集成层]
Integration --> JD[京东平台]
style Client fill:#f9f,stroke:#333
style JD fill:#bbf,stroke:#333

Diagram sources

详细组件分析

账户管理API分析

账户管理API提供了完整的CRUD操作接口，使用RESTful风格设计。所有接口都通过JWT进行认证，确保只有授权用户才能访问。接口设计遵循统一的响应格式，包含状态码、消息和数据体。

账户创建接口

classDiagram
class AccountAddReq {
+string name
+string cookie
+int status
+string notes
}
class AccountAddRes {
+string message
}
AccountAddReq --> AccountAddRes : "POST /cookieInfo/jd/account/add"

Diagram sources

账户操作序列图

sequenceDiagram
participant Client as "客户端"
participant API as "API网关"
participant Controller as "控制器"
participant Service as "服务层"
participant Database as "数据库"
Client->>API : POST /cookieInfo/jd/account/add
API->>Controller : 转发请求
Controller->>Controller : 权限验证
Controller->>Service : 调用Add方法
Service->>Database : 插入账户记录
Database-->>Service : 返回结果
Service-->>Controller : 返回成功
Controller-->>API : 返回响应
API-->>Client : 200 OK

Diagram sources

Section sources

批量Cookie处理分析

批量Cookie处理功能允许用户一次性导入多个京东账户的Cookie信息。系统会对每个Cookie进行验证，查询用户信息和余额，并将有效账户保存到数据库中。

批量添加流程图

flowchart TD
Start([开始]) --> ValidateAuth["验证用户权限"]
ValidateAuth --> LoopStart{遍历Cookie列表}
LoopStart --> TrimCookie["清理Cookie空白字符"]
TrimCookie --> GetClient["获取京东客户端"]
GetClient --> QueryUserInfo["查询用户信息"]
QueryUserInfo --> CheckUserValid{"用户信息有效?"}
CheckUserValid --> |否| NextCookie
CheckUserValid --> |是| QueryBalance["查询账户余额"]
QueryBalance --> SaveAccount["保存账户信息"]
SaveAccount --> NextCookie["处理下一个Cookie"]
NextCookie --> LoopEnd{是否还有Cookie?}
LoopEnd --> |是| LoopStart
LoopEnd --> |否| TriggerValidation["触发验证和消费"]
TriggerValidation --> End([结束])

Diagram sources

Section sources

状态检测与刷新分析

系统实现了定期的状态检测机制，确保京东账户的可用性。通过定时任务扫描所有正常状态的账户，调用京东API验证其有效性。

状态检测流程

flowchart TD
Start([定时任务启动]) --> GetTotal["获取账户总数"]
GetTotal --> LoopPages{分页处理}
LoopPages --> CreateSpan["创建追踪Span"]
CreateSpan --> QueryPage["查询一页账户"]
QueryPage --> LoopAccounts{遍历账户}
LoopAccounts --> ValidateCookie["验证Cookie有效性"]
ValidateCookie --> UpdateStatus["更新账户状态"]
UpdateStatus --> NextAccount["下一个账户"]
NextAccount --> LoopAccountsEnd{是否还有账户?}
LoopAccountsEnd --> |是| LoopAccounts
LoopAccountsEnd --> |否| NextPage["下一页"]
NextPage --> LoopPagesEnd{是否还有页?}
LoopPagesEnd --> |是| LoopPages
LoopPagesEnd --> |否| End([任务完成])

Diagram sources

Section sources

依赖分析

系统依赖于多个内部和外部组件。内部依赖包括GoFrame框架、数据库访问层和缓存系统。外部依赖主要是京东API，通过HTTP客户端进行通信。系统还依赖于配置管理、日志记录和分布式追踪等基础设施。

graph LR
A[京东卡密账户管理] --> B[GoFrame框架]
A --> C[MySQL数据库]
A --> D[Redis缓存]
A --> E[京东API]
A --> F[OpenTelemetry]
A --> G[JWT认证]
style A fill:#f96,stroke:#333

Diagram sources

Section sources

性能考虑

系统在设计时考虑了多个性能优化点。首先，使用了缓存机制来减少对京东API的频繁调用，特别是在用户信息和余额查询方面。其次，批量操作采用分页处理，避免一次性加载过多数据导致内存溢出。此外，系统实现了接口限流，防止恶意用户过度请求。数据库查询也进行了优化，使用了适当的索引和查询条件。

故障排除指南

常见问题包括Cookie验证失败、账户状态异常和接口调用频繁。对于Cookie验证失败，应检查Cookie格式是否正确，是否包含必要的登录信息。账户状态异常可能是由于京东安全策略导致，建议重新获取Cookie。接口调用频繁会触发限流机制，用户需要等待一段时间后再试。系统日志记录了详细的错误信息，可通过日志追踪问题根源。

Section sources

结论

京东卡密账户管理系统提供了一套完整的解决方案，用于管理京东账户的Cookie信息。系统设计合理，层次分明，具有良好的可维护性和扩展性。通过批量处理、状态检测和性能优化，系统能够高效地管理大量京东账户。未来可以考虑增加更多的京东API集成，如订单查询、优惠券管理等功能，进一步提升系统的实用价值。