# 订单汇总统计

<cite>
**本文档中引用的文件**  
- [order_summary.go](file://api/order/v1/order_summary.go)
- [order_v1_order_summary_get_list.go](file://internal/controller/order/order_v1_order_summary_get_list.go)
- [order_v1_order_summary_daily_get_list.go](file://internal/controller/order/order_v1_order_summary_daily_get_list.go)
- [order_info.go](file://internal/model/order_info.go)
- [merchant_order.go](file://internal/service/merchant_order.go)
- [handler.go](file://internal/errHandler/handler.go)
</cite>

## 目录
1. [简介](#简介)
2. [核心组件](#核心组件)
3. [API端点说明](#api端点说明)
4. [数据结构定义](#数据结构定义)
5. [查询条件与统计维度](#查询条件与统计维度)
6. [认证机制](#认证机制)
7. [使用示例](#使用示例)
8. [计算逻辑与数据一致性](#计算逻辑与数据一致性)
9. [性能优化建议](#性能优化建议)
10. [监控与业务分析作用](#监控与业务分析作用)

## 简介
本文档详细描述了订单汇总统计API的功能与使用方法，重点涵盖两个核心端点：`GET /api/v1/order/summary/get/list` 和 `GET /api/v1/order/summary/daily/get/list`。该API用于获取订单的总体统计信息和每日趋势数据，支持按商户、通道、日期等多维度进行聚合分析，广泛应用于业务报表生成、运营状况监控和财务对账等场景。

**Section sources**
- [order_summary.go](file://api/order/v1/order_summary.go#L1-L62)

## 核心组件
订单汇总统计功能由控制器、服务层和数据模型三层构成。控制器负责接收HTTP请求并进行参数校验，服务层实现具体的业务逻辑和数据库查询，数据模型定义了输入输出的数据结构。整个流程通过依赖注入机制解耦，确保代码的可维护性和可测试性。

```mermaid
graph TD
A[客户端] --> B[ControllerV1.OrderSummaryGetList]
B --> C[service.OrderSummary().GetList]
C --> D[model.OrderSummaryListInput]
C --> E[model.OrderSummaryListOutput]
F[客户端] --> G[ControllerV1.OrderSummaryDailyGetList]
G --> H[service.OrderSummary().GetDailyStats]
H --> I[model.OrderSummaryDailyListInput]
H --> J[model.OrderSummaryDailyListOutput]
style A fill:#f9f,stroke:#333
style B fill:#bbf,stroke:#333
style C fill:#bbf,stroke:#333
style D fill:#9f9,stroke:#333
style E fill:#9f9,stroke:#333
style F fill:#f9f,stroke:#333
style G fill:#bbf,stroke:#333
style H fill:#bbf,stroke:#333
style I fill:#9f9,stroke:#333
style J fill:#9f9,stroke:#333
```

**Diagram sources**
- [order_v1_order_summary_get_list.go](file://internal/controller/order/order_v1_order_summary_get_list.go#L1-L58)
- [order_v1_order_summary_daily_get_list.go](file://internal/controller/order/order_v1_order_summary_daily_get_list.go#L1-L61)
- [merchant_order.go](file://internal/service/merchant_order.go#L17-L26)

**Section sources**
- [order_v1_order_summary_get_list.go](file://internal/controller/order/order_v1_order_summary_get_list.go#L1-L58)
- [order_v1_order_summary_daily_get_list.go](file://internal/controller/order/order_v1_order_summary_daily_get_list.go#L1-L61)

## API端点说明

### 总体订单汇总端点
- **HTTP方法**: GET
- **URL模式**: `/api/v1/order/summary/get/list`
- **功能描述**: 获取订单的总体汇总数据，按商户维度聚合统计
- **认证要求**: 需要有效的用户会话和权限验证

### 每日订单汇总端点
- **HTTP方法**: GET
- **URL模式**: `/api/v1/order/summary/daily/get/list`
- **功能描述**: 获取订单的每日统计趋势数据，支持按日期范围查询
- **认证要求**: 需要有效的用户会话和权限验证

**Section sources**
- [order_summary.go](file://api/order/v1/order_summary.go#L1-L62)

## 数据结构定义

### 订单汇总记录（OrderSummaryRecord）
| 字段名 | 类型 | 描述 |
|--------|------|------|
| merchantUid | string | 商户唯一标识 |
| merchantName | string | 商户名称 |
| succeedCount | int64 | 成功订单数量 |
| totalCount | int64 | 订单总量 |
| failedCount | int64 | 失败订单数量 |
| waitedCount | int64 | 创建但未填写的订单数量 |
| succeedShowAmount | float64 | 成功订单展示金额 |
| totalShowAmount | float64 | 订单总展示金额 |
| succeedFactAmount | float64 | 成功订单实际金额 |
| totalFactAmount | float64 | 订单总实际金额 |
| rate | float64 | 成功率（百分比） |
| date | string | 统计日期 |

### 每日订单汇总记录（OrderSummaryDailyRecord）
在基础汇总记录的基础上，增加了通道信息：
- **roadUid**: 通道唯一标识
- **roadName**: 通道名称

**Section sources**
- [order_summary.go](file://api/order/v1/order_summary.go#L1-L62)
- [order_info.go](file://internal/model/order_info.go#L1-L24)

## 查询条件与统计维度

### 总体汇总查询参数
- **roadUid**: 按指定通道筛选
- **date**: 按指定日期查询
- **分页参数**: 支持标准分页（page, limit）

### 每日汇总查询参数
- **roadUid[]**: 按多个通道筛选（数组）
- **dateRange[]**: 按日期范围查询（起止时间数组）
- **merchantUid[]**: 按多个商户筛选（数组）

统计维度包括：
- 按商户聚合
- 按通道聚合
- 按日趋势分析
- 多维度交叉统计

**Section sources**
- [order_summary.go](file://api/order/v1/order_summary.go#L1-L62)

## 认证机制
API采用基于上下文的认证机制，通过`service.SysAuth().LoginWithEverything`和`LoginWithIFrameAndLogin`方法验证用户身份和权限。请求必须携带有效的认证令牌，系统会自动提取用户ID和登录类型，用于数据权限控制。未通过认证的请求将返回401状态码。

**Section sources**
- [order_v1_order_summary_get_list.go](file://internal/controller/order/order_v1_order_summary_get_list.go#L1-L58)
- [order_v1_order_summary_daily_get_list.go](file://internal/controller/order/order_v1_order_summary_daily_get_list.go#L1-L61)

## 使用示例

### 获取某商户的总体统计
```http
GET /api/v1/order/summary/get/list?merchantUid=MER123&date=2024-01-15
Authorization: Bearer <token>
```

### 获取多商户多通道的每日趋势
```http
GET /api/v1/order/summary/daily/get/list?roadUid[]=R1&roadUid[]=R2&merchantUid[]=M1&merchantUid[]=M2&dateRange[]=2024-01-01&dateRange[]=2024-01-31
Authorization: Bearer <token>
```

**Section sources**
- [order_summary.go](file://api/order/v1/order_summary.go#L1-L62)

## 计算逻辑与数据一致性
汇总数据基于订单状态实时计算，成功率通过`成功订单数/总订单数`公式得出，金额统计包含展示金额和实际金额两个维度。数据更新频率为实时，每次查询都会从数据库获取最新状态。系统通过事务机制保证数据一致性，避免统计过程中的脏读问题。错误处理采用统一的包装机制，确保异常信息的标准化输出。

```mermaid
flowchart TD
Start([开始]) --> Validate["验证请求参数"]
Validate --> Auth["认证用户权限"]
Auth --> Query["查询订单数据"]
Query --> Calc["计算统计指标"]
Calc --> Format["格式化输出结果"]
Format --> End([返回响应])
Query --> |失败| HandleError["处理数据库错误"]
HandleError --> WrapError["包装错误信息"]
WrapError --> End
```

**Diagram sources**
- [order_v1_order_summary_get_list.go](file://internal/controller/order/order_v1_order_summary_get_list.go#L1-L58)
- [order_v1_order_summary_daily_get_list.go](file://internal/controller/order/order_v1_order_summary_daily_get_list.go#L1-L61)
- [handler.go](file://internal/errHandler/handler.go#L1-L10)

**Section sources**
- [order_v1_order_summary_get_list.go](file://internal/controller/order/order_v1_order_summary_get_list.go#L1-L58)
- [order_v1_order_summary_daily_get_list.go](file://internal/controller/order/order_v1_order_summary_daily_get_list.go#L1-L61)

## 性能优化建议
1. **合理使用缓存**: 对于频繁查询但变化不频繁的数据，建议在客户端或中间层添加缓存
2. **避免高频查询**: 不要以过高频率调用汇总接口，建议最小间隔不低于5分钟
3. **精确查询条件**: 尽量指定具体的商户、通道和日期范围，减少数据扫描量
4. **分页处理**: 对于大量数据，使用分页参数避免单次返回过多记录
5. **批量查询**: 当需要多个维度数据时，优先使用支持数组参数的接口，减少请求数量

**Section sources**
- [order_summary.go](file://api/order/v1/order_summary.go#L1-L62)

## 监控与业务分析作用
该接口在系统监控和业务分析中扮演关键角色：
- **健康状况监控**: 通过每日趋势分析，及时发现订单量异常波动
- **业务运营分析**: 支持按商户、通道多维度分析交易表现
- **财务对账**: 提供准确的订单统计和金额汇总，便于财务核对
- **决策支持**: 基于历史数据趋势，为业务决策提供数据支持
- **问题排查**: 当出现交易异常时，可快速定位受影响的商户或通道

**Section sources**
- [order_summary.go](file://api/order/v1/order_summary.go#L1-L62)