96ed936079
- 新增API端点参考文档，涵盖权限、卡密、订单、商户、监控、限制等模块 - 详细说明Apple卡密充值处理流程，包括提交、查询、回调和轮询接口 - 描述充值订单状态机及生命周期，支持超时重试和状态迁移 - 介绍签名验证、幂等控制及重复卡密防刷单策略 - 增加商户配置管理、历史记录查询和错误处理机制说明 - 提供API使用示例代码及客户端实现指导 - 删除过时的.drone.yml.bak文件，清理无用配置 - 添加.dockerignore忽略指定目录和文件
12 KiB
京东卡密兑换处理
**本文档引用文件** - [order.go](file://api/card_redeem_jd/v1/order.go) - [card_redeem_jd_v1_place_order.go](file://internal/controller/card_redeem_jd/card_redeem_jd_v1_place_order.go) - [card_redeem_cookie.go](file://internal/service/card_redeem_cookie.go) - [order.go](file://internal/logic/card_redeem_cookie/order.go) - [card_redeem_cookie.go](file://internal/model/card_redeem_cookie.go) - [v_1_card_redeem_cookie_order.go](file://internal/dao/v_1_card_redeem_cookie_order.go) - [v_1_card_redeem_cookie_info.go](file://internal/dao/v_1_card_redeem_cookie_info.go) - [v_1_card_redeem_cookie_order_jd.go](file://internal/dao/v_1_card_redeem_cookie_order_jd.go) - [entity/v_1_card_redeem_cookie_order.go](file://internal/model/entity/v_1_card_redeem_cookie_order.go) - [entity/v_1_card_redeem_cookie_info.go](file://internal/model/entity/v_1_card_redeem_cookie_info.go) - [entity/v_1_card_redeem_cookie_order_jd.go](file://internal/model/entity/v_1_card_redeem_cookie_order_jd.go) - [card_redeem.go](file://internal/consts/card_redeem.go) - [card_redeem_cookie.go](file://internal/consts/card_redeem_cookie.go)目录
简介
本文档详细阐述了京东卡密兑换处理系统的核心功能，包括兑换订单的创建、状态管理、历史查询等关键流程。文档深入分析了订单生命周期、状态转换规则和持久化机制，详细说明了兑换请求的处理流程，涵盖参数验证、库存检查、交易执行等环节。同时，文档解释了订单与账户、支付系统的集成模式，记录了兑换处理中的异常处理策略、幂等性保障和数据一致性机制，并提供了性能优化建议和常见问题解决方案。
项目结构
京东卡密兑换处理功能主要集中在 api/card_redeem_jd 和 internal 目录下。API 接口定义在 api/card_redeem_jd/v1 中，核心业务逻辑位于 internal/logic/card_redeem_cookie，数据访问层在 internal/dao，服务接口在 internal/service，数据模型在 internal/model/entity。常量定义在 internal/consts 目录下，用于统一管理订单状态、账号状态等枚举值。
graph TB
subgraph "API层"
A[api/card_redeem_jd/v1/order.go]
end
subgraph "控制层"
B[internal/controller/card_redeem_jd]
end
subgraph "服务层"
C[internal/service/card_redeem_cookie.go]
end
subgraph "逻辑层"
D[internal/logic/card_redeem_cookie/order.go]
end
subgraph "数据访问层"
E[internal/dao/v_1_card_redeem_cookie_*.go]
end
subgraph "实体层"
F[internal/model/entity/v_1_card_redeem_cookie_*.go]
end
A --> B
B --> C
C --> D
D --> E
E --> F
图示来源
- order.go
- card_redeem_jd_v1_place_order.go
- card_redeem_cookie.go
- order.go
- v_1_card_redeem_cookie_order.go
- entity/v_1_card_redeem_cookie_order.go
本节来源
核心组件
京东卡密兑换处理的核心组件包括订单管理、账号管理、状态机和持久化层。订单管理负责处理兑换请求的创建、查询和状态更新；账号管理负责维护京东账号（Cookie）的状态和调度；状态机定义了订单和账号的完整生命周期；持久化层通过数据库表存储所有关键数据。系统通过 CardRedeemCookie 服务接口协调各组件，确保兑换流程的原子性和一致性。
本节来源
架构概览
系统采用分层架构，从上至下分为API层、控制层、服务层、逻辑层、数据访问层和实体层。API层定义了HTTP接口，控制层处理请求并调用服务，服务层提供统一的业务接口，逻辑层实现具体的业务规则，数据访问层与数据库交互，实体层映射数据库表结构。这种分层设计确保了代码的高内聚、低耦合，便于维护和扩展。
graph TD
A[客户端] --> B[API接口]
B --> C[控制器]
C --> D[服务接口]
D --> E[业务逻辑]
E --> F[数据访问对象]
F --> G[(数据库)]
style A fill:#f9f,stroke:#333
style G fill:#ccf,stroke:#333
图示来源
- order.go
- card_redeem_jd_v1_place_order.go
- card_redeem_cookie.go
- order.go
- v_1_card_redeem_cookie_order.go
详细组件分析
兑换订单处理分析
兑换订单处理是系统的核心功能，主要涉及订单创建、状态管理和查询。当用户发起兑换请求时，系统首先进行参数验证，然后创建或查找订单，最后调用京东接口完成兑换。
对象导向组件
classDiagram
class V1CardRedeemCookieOrder {
+int id
+string orderNo
+string bankOrderId
+float orderAmount
+string status
+string note
+int cookieId
+string jdOrderNo
+datetime createdAt
+datetime updatedAt
}
class V1CardRedeemCookieInfo {
+int id
+string name
+string cookie
+string status
+uint failCount
+datetime createdAt
+datetime updatedAt
}
class V1CardRedeemCookieOrderJd {
+uint id
+int cookieOrderId
+int cookieAccountId
+string responseData
+string status
+string payId
+string webPayLink
+string clientPayLink
+string orderNo
+string userAgent
+string userClient
+string note
+datetime createdAt
+datetime updatedAt
+string cardNo
+string cardPassword
+string category
}
V1CardRedeemCookieOrder --> V1CardReedemCookieInfo : "使用"
V1CardReedemCookieOrder --> V1CardReedemCookieOrderJd : "包含"
图示来源
- entity/v_1_card_redeem_cookie_order.go
- entity/v_1_card_redeem_cookie_info.go
- entity/v_1_card_redeem_cookie_order_jd.go
API/服务组件
sequenceDiagram
participant Client as "客户端"
participant Controller as "控制器"
participant Service as "服务层"
participant Logic as "逻辑层"
participant DB as "数据库"
Client->>Controller : POST /cookieInfo/jd/order/placeOrder
Controller->>Service : PlaceOrder(请求参数)
Service->>Logic : PlaceOrder(输入模型)
Logic->>Logic : 获取或创建订单
Logic->>Logic : 调度京东账号
Logic->>Logic : 调用京东接口下单
Logic->>DB : 更新订单状态
DB-->>Logic : 操作结果
Logic-->>Service : 返回订单信息
Service-->>Controller : 返回结果
Controller-->>Client : 返回支付链接
图示来源
复杂逻辑组件
flowchart TD
Start([开始下单]) --> ValidateInput["验证输入参数"]
ValidateInput --> CheckOrder{"订单是否存在?"}
CheckOrder --> |是| GetOrder["获取现有订单"]
CheckOrder --> |否| CreateOrder["创建新订单"]
CreateOrder --> InitOrder["初始化订单状态为init"]
GetOrder --> CheckStatus{"订单状态为success?"}
CheckStatus --> |是| ReturnSuccess["直接返回成功"]
CheckStatus --> |否| ScheduleAccount["调度京东账号"]
ScheduleAccount --> CallJdApi["调用京东接口下单"]
CallJdApi --> CheckResult{"下单成功?"}
CheckResult --> |是| UpdateStatusSuccess["更新状态为placeSuccess"]
CheckResult --> |否| UpdateStatusFail["更新状态为placeFail"]
UpdateStatusSuccess --> ReturnPayLink["返回支付链接"]
UpdateStatusFail --> ReturnError["返回错误信息"]
ReturnSuccess --> End([结束])
ReturnPayLink --> End
ReturnError --> End
图示来源
本节来源
依赖分析
系统内部组件之间存在明确的依赖关系。API层依赖于控制器，控制器依赖于服务接口，服务接口依赖于具体的逻辑实现，逻辑实现依赖于数据访问对象，数据访问对象依赖于数据库实体。外部依赖包括数据库（通过GORM操作）、京东API（通过integration包调用）和配置管理（通过utility/config）。系统通过接口隔离和依赖注入确保了组件间的松耦合。
graph LR
A[API] --> B[Controller]
B --> C[Service Interface]
C --> D[Logic Implementation]
D --> E[DAO]
E --> F[Entity]
F --> G[(Database)]
D --> H[External API]
D --> I[Config]
style A fill:#f96,stroke:#333
style G fill:#ccf,stroke:#333
style H fill:#6f9,stroke:#333
图示来源
- card_redeem_cookie.go
- order.go
- v_1_card_redeem_cookie_order.go
- entity/v_1_card_redeem_cookie_order.go
本节来源
性能考虑
系统在性能方面采取了多项优化措施。首先，通过 gmlock 实现了基于订单ID的分布式锁，防止同一订单被重复处理，保障了幂等性。其次，数据库查询使用了索引优化，如在 bank_order_id 和 created_at 字段上建立索引，确保查询效率。此外，系统采用了事务管理，确保订单创建和状态更新的原子性。对于高并发场景，建议引入缓存机制，如Redis，缓存热门商品信息和账号状态，减轻数据库压力。
故障排除指南
常见问题包括下单失败、支付链接为空、账号调度失败等。对于下单失败，应检查京东API返回的错误信息，通常记录在订单的 note 字段中。支付链接为空可能是由于京东接口未返回支付链接，需检查请求参数和账号状态。账号调度失败可能是因为所有账号都处于禁用或过期状态，需检查 v1_card_redeem_cookie_info 表中的账号状态。系统日志记录在 glog 中，可通过日志级别（Info、Error）快速定位问题。
本节来源
结论
京东卡密兑换处理系统设计合理，功能完整，具备良好的可维护性和扩展性。系统通过清晰的分层架构和严格的接口定义，实现了高内聚低耦合的设计目标。状态机和持久化机制确保了数据的一致性和可靠性。未来可考虑引入消息队列解耦订单处理流程，进一步提升系统的吞吐量和容错能力。