96ed936079
- 新增API端点参考文档，涵盖权限、卡密、订单、商户、监控、限制等模块 - 详细说明Apple卡密充值处理流程，包括提交、查询、回调和轮询接口 - 描述充值订单状态机及生命周期，支持超时重试和状态迁移 - 介绍签名验证、幂等控制及重复卡密防刷单策略 - 增加商户配置管理、历史记录查询和错误处理机制说明 - 提供API使用示例代码及客户端实现指导 - 删除过时的.drone.yml.bak文件，清理无用配置 - 添加.dockerignore忽略指定目录和文件
8.9 KiB
京东卡密数据汇总
**本文档引用文件** - [order_summary.go](file://api/order/v1/order_summary.go) - [card_info_jd_v1_order_summary_list.go](file://internal/controller/card_info_jd/card_info_jd_v1_order_summary_list.go) - [order_v1_order_summary_get_list.go](file://internal/controller/order/order_v1_order_summary_get_list.go) - [order-summary.go](file://internal/logic/merchant_order/order-summary.go) - [cache.go](file://utility/cache/cache.go) - [consts.go](file://utility/cache/consts.go) - [card_info_jd.go](file://api/card_info_jd/v1/order_summary.go)目录
简介
本文档详细说明了京东卡密数据汇总API的设计与实现，涵盖订单汇总、账户统计、交易分析等接口的HTTP方法、URL模式、请求/响应模式和认证机制。重点描述了数据汇总的计算逻辑、时间范围选择和数据精度控制，并提供实际使用示例，如日/月交易量统计、账户余额汇总、充值成功率分析等场景。同时解释了数据缓存策略、查询性能优化和大数据量处理机制，确保在高并发查询场景下的响应时间优化。
项目结构
本项目采用分层架构设计，主要分为API层、控制器层、服务层、逻辑层和数据访问层。京东卡密相关功能集中在api/card_info_jd和internal/controller/card_info_jd目录下，订单汇总功能则分布在api/order和internal/controller/order目录中。缓存机制由utility/cache模块统一管理，数据库操作通过internal/dao实现。
graph TB
subgraph "API层"
A[card_info_jd/v1/order_summary.go]
B[order/v1/order_summary.go]
end
subgraph "控制器层"
C[card_info_jd_v1_order_summary_list.go]
D[order_v1_order_summary_get_list.go]
end
subgraph "服务层"
E[merchant_order.go]
end
subgraph "逻辑层"
F[order-summary.go]
end
subgraph "数据访问层"
G[dao/V1OrderInfo.go]
end
subgraph "缓存层"
H[cache.go]
end
A --> C
B --> D
C --> E
D --> E
E --> F
F --> G
F --> H
Diagram sources
Section sources
核心组件
京东卡密数据汇总的核心组件包括订单汇总接口、数据计算逻辑和服务注册机制。订单汇总接口提供HTTP端点用于获取统计信息，数据计算逻辑负责从数据库中提取并聚合数据，服务注册机制确保订单汇总服务的正确初始化和调用。
Section sources
架构概述
系统采用典型的分层架构，从前端API到后端数据存储形成清晰的数据流。用户请求首先到达API层，经过控制器层处理后，调用服务层提供的接口。服务层协调逻辑层完成具体的业务处理，包括数据查询、聚合计算等。逻辑层通过DAO层与数据库交互，并利用缓存层提高查询性能。
graph LR
Client[客户端] --> API[API接口]
API --> Controller[控制器]
Controller --> Service[服务层]
Service --> Logic[逻辑层]
Logic --> Cache[缓存]
Logic --> Database[数据库]
Cache --> Logic
Database --> Logic
Diagram sources
详细组件分析
订单汇总接口分析
接口定义
classDiagram
class OrderSummaryListReq {
+string RoadUid
+CommonPageReq
}
class OrderSummaryListRes {
+CommonPageRes[OrderSummaryRecord]
}
class OrderSummaryRecord {
+string MerchantUid
+string MerchantName
+int64 SucceedCount
+float64 SucceedShowAmount
+float64 SucceedFactAmount
+int64 TotalCount
+float64 TotalShowAmount
+float64 TotalFactAmount
+float64 Rate
+string Date
+int64 FailedCount
+int64 WaitedCount
}
OrderSummaryListRes --> OrderSummaryRecord : "包含"
Diagram sources
请求处理流程
sequenceDiagram
participant Client as "客户端"
participant API as "API接口"
participant Controller as "控制器"
participant Service as "服务层"
participant Logic as "逻辑层"
participant Database as "数据库"
participant Cache as "缓存"
Client->>API : GET /cardInfo/JDCard/order/summary
API->>Controller : 转发请求
Controller->>Service : 调用OrderSummary()
Service->>Logic : 获取汇总数据
Logic->>Cache : 检查缓存
alt 缓存命中
Cache-->>Logic : 返回缓存数据
else 缓存未命中
Logic->>Database : 查询数据库
Database-->>Logic : 返回原始数据
Logic->>Logic : 聚合计算
Logic->>Cache : 存储计算结果
end
Logic-->>Service : 返回汇总结果
Service-->>Controller : 返回结果
Controller-->>API : 返回响应
API-->>Client : 返回JSON数据
Diagram sources
数据计算逻辑
flowchart TD
Start([开始]) --> ValidateInput["验证输入参数"]
ValidateInput --> CheckCache["检查缓存是否存在"]
CheckCache --> CacheHit{"缓存命中?"}
CacheHit --> |是| ReturnCache["返回缓存数据"]
CacheHit --> |否| QueryDB["查询数据库"]
QueryDB --> ProcessData["处理原始数据"]
ProcessData --> Aggregate["执行聚合计算"]
Aggregate --> FormatResult["格式化结果"]
FormatResult --> UpdateCache["更新缓存"]
UpdateCache --> ReturnResult["返回结果"]
ReturnCache --> End([结束])
ReturnResult --> End
Diagram sources
Section sources
- order_summary.go
- card_info_jd_v1_order_summary_list.go
- order_v1_order_summary_get_list.go
- order-summary.go
依赖分析
系统各组件之间存在明确的依赖关系，形成了稳定的服务调用链。API层依赖控制器层，控制器层依赖服务层，服务层依赖逻辑层，逻辑层依赖数据访问层和缓存层。
graph TD
A[API层] --> B[控制器层]
B --> C[服务层]
C --> D[逻辑层]
D --> E[DAO层]
D --> F[缓存层]
E --> G[数据库]
F --> G[数据库]
Diagram sources
Section sources
性能考虑
为确保系统在高并发场景下的性能表现，采用了多项优化措施。首先，通过Redis缓存频繁访问的数据，减少数据库压力。其次，使用分页查询避免一次性加载大量数据。最后，对关键路径进行性能监控，及时发现和解决瓶颈问题。
Section sources
故障排除指南
当遇到数据汇总接口响应缓慢或返回错误时，可按照以下步骤进行排查：
- 检查缓存服务是否正常运行
- 验证数据库连接是否稳定
- 查看日志中是否有SQL执行超时记录
- 确认请求参数是否符合规范
- 检查是否有大量并发请求导致资源竞争
Section sources
结论
京东卡密数据汇总API通过分层架构设计和缓存优化策略，实现了高效的数据统计功能。系统能够支持日/月交易量统计、账户余额汇总、充值成功率分析等多种业务场景，满足高并发查询的需求。未来可通过引入更精细的缓存策略和数据库索引优化进一步提升性能。