# 订单指标系统计算实现计划

## 项目目标
实现复杂的业务指标系统，包括24小时换单完成率、订单考核时间、标签率计算等指标。这些指标涉及多表关联、时间逻辑判断和复杂的业务规则。

---

## 时区说明

**重要**: 
- **到仓时间 (ReceiptTime)**: UTC-5 时区
- **标签推送时间 (LabelRetrievedAt)**: UTC+0 时区
- **扫描时间 (CreatedAt)**: UTC+0 时区
- **其他所有时间字段**: UTC+0 时区
- **数据拉取时间**: UTC-5 时区显示

时间比较时需进行时区转换。

---

## 核心业务逻辑分析

### 1. 标签率计算（Label Rate）

**定义**: 
- **第一阶段**（未开始扫描）: 标签率 = 当前有标签的订单数 / 该交接单关联的总订单数
- **第二阶段**（已开始扫描）: 标签率 = 在第一条扫描记录时间之前有标签的订单数 / 该交接单关联的总订单数（**固定不变**）

**计算逻辑**:
```
1. 获取交接单关联的所有订单
2. 检查是否存在该交接单的扫描记录
   - 如果不存在：标签率 = 当前有标签的订单数 / 总订单数
   - 如果存在：
     a. 找到第一条扫描记录的时间（任意结果）
     b. 统计在此时间点前 LabelRetrievedAt <= 第一扫描时间 的订单
     c. 标签率 = 满足条件的订单数 / 总订单数
3. 标签率一旦固定后就不再变化
```

**关键理解**:
- 标签率是交接单在**现场开始扫描时**的一个**时间切片快照**
- 此后即使新增了更多有标签的订单，标签率也不变
- 标签率 >= 80% 为"高标签率"，< 80% 为"低标签率"

**数据关系**:
- 交接单号 ← → BillOfLadingNumber / MasterPackageNumber （需要在订单表中查找）
- 订单中的 LabelRetrievedAt 与 第一条扫描记录的 CreatedAt 比较

---

### 2. 考核时间计算（Assessment Time）

**场景A：标签率 >= 80%**
- 前置条件：有到货时间（ReceiptTime），且标签率 >= 80%
- 规则：
  - 如果收货时间 <= 当天 16:00 → 考核时间 = 次日 16:00
  - 如果收货时间 > 当天 16:00 → 考核时间 = 次日 23:59

**场景B：标签率 < 80%**
- 前置条件：标签率 < 80%
- 规则：以包裹换单完成时间作为考核时间
  - 换单完成时间 = 该订单的第一条扫描成功记录（Result=0）的时间

**考核记录日期**: 哪天完成考核，记录在哪天

---

### 3. 24小时换单完成率（24H Label Exchange Completion Rate）

**分子**: 标签率 >= 80% 的订单中，在考核时间内有扫描成功记录（Result=0）的订单数

**分母**: 标签率 >= 80% 的订单总数

**公式**: 完成率 = (考核时间内成功扫描的订单数) / (标签率 >= 80% 的订单总数) * 100%

**时间判断**: 以 UTC 时间对比

---

### 4. 考核订单群体（Assessment Order Group）

**定义**: 有到货时间 AND 标签率 >= 80% 的那部分有标签订单

**包含条件**:
- ReceiptTime 不为 NULL（有收货时间）
- 标签率 >= 80%（或更严格的条件：订单有标签且标签率 >= 80%）

---

### 5. 额外指标定义

#### 5.1 当天新增换单数（Daily New Replace Count）

**定义**: 到仓时间是当天（UTC-5）的交接单中有标签的总订单数

**计算逻辑**:
```
1. 选取 ReceiptTime 在当天（UTC-5）的所有到货交接单（注意时区转换）
2. 获取这些交接单关联的所有订单（通过 BillOfLadingNumber 或 MasterPackageNumber）
3. 筛选其中 Label 不为 NULL 且非空的订单
4. 统计总数
```

**代码示例**:
```csharp
public async Task<int> GetDailyNewReplaceCountAsync(DateTime date)
{
    // date 是 UTC-5 格式的日期
    var dateStart = GetUtc5DateStart(date);  // 返回 UTC 时间表示
    var dateEnd = GetUtc5DateEnd(date);      // 返回 UTC 时间表示
    
    // 获取该日期内到仓的所有交接单（ReceiptTime 在 UTC-5 当天）
    var arrivalForms = await _arrivalHandoverFormService
        .GetArrivalHandoverFormsByDateRangeAsync(dateStart, dateEnd);
    
    if (arrivalForms.Count == 0)
        return 0;
    
    var handoverNumbers = arrivalForms.Select(f => f.HandoverNumber).ToList();
    
    // 获取这些交接单关联的所有订单
    var orders = await _labelReplaceRepository
        .GetOrdersByHandoverNumbersAsync(handoverNumbers);
    
    // 统计有标签的订单数（Label 不为 NULL 且非空）
    int count = orders.Count(o => !string.IsNullOrEmpty(o.Label));
    
    return count;
}
```

#### 5.2 累计要换的总单数（Cumulative Total Replace Count）

**定义**: 历史上所有有标签但是没有扫描完成记录的订单（不包含当天新增）

**计算逻辑**:
```
1. 获取所有 Label 不为 NULL 的订单
2. 排除当天新增的订单（ReceiptTime 是当天的）
3. 筛选这些订单中，没有成功扫描记录（Result=0）的
4. 统计数量
```

#### 5.3 当天应该换单数（Daily Should Replace Count）

**定义**: 标签率 >= 80% 且到仓时间是当天的订单总数

**计算逻辑**:
```
1. 选取 ReceiptTime 在当天（UTC-5）的所有到货交接单
2. 计算每个交接单的标签率
3. 筛选标签率 >= 80% 的交接单
4. 统计这些交接单关联的订单总数
```

#### 5.4 当日换单完成数（Daily Completion Count）

**定义**: 扫描完成时间是当日（UTC-5）的订单总数

**计算逻辑**:
```
1. 获取所有有成功扫描记录的订单（Result=0，即 ScanResult.ReturnedLabel）
2. 注意：CreatedAt 是 UTC+0，需要转换为 UTC-5 后判断是否在当日
3. 筛选其中扫描时间（转换后）对应当天（UTC-5）的订单
4. 去重统计（同一订单即使有多条成功扫描也只计算一次）
```

**代码示例**:
```csharp
public async Task<int> GetDailyCompletionCountAsync(DateTime date)
{
    // date 是 UTC-5 格式的日期
    var dateStart = GetUtc5DateStart(date);  // UTC 时间
    var dateEnd = GetUtc5DateEnd(date);      // UTC 时间
    
    // 获取该日期范围内有成功扫描记录的订单
    var successfulScans = await _labelScanService
        .GetScanRecordsByDateRangeAsync(dateStart, dateEnd, ScanResult.ReturnedLabel);
    
    if (successfulScans == null || successfulScans.Count == 0)
        return 0;
    
    // 去重统计订单数
    var uniqueWaybills = successfulScans
        .Select(s => s.NeutralWaybillNumber)
        .Distinct()
        .Count();
    
    return uniqueWaybills;
}
```

**重要**：在 Repository 层 GetScanRecordsByDateRangeAsync 方法中，对 CreatedAt（UTC+0）进行查询时，参数 dateStart 和 dateEnd 已是 UTC 时间，可直接作为 SQL WHERE 条件。

#### 5.5 当日STOP数（Daily STOP Count）

**定义**: 扫描结果是完成（Result=0）且描述包含"STOP"关键字的扫描记录，其创建时间是当日（UTC-5）的订单总数

**计算逻辑**:
```
1. 获取当日（UTC-5）所有成功扫描记录（Result=0，即 ScanResult.ReturnedLabel）
2. 筛选其中 Description 包含"STOP"关键字的记录
3. 去重统计对应的订单数
```

**代码示例**:
```csharp
public async Task<int> GetDailyStopCountAsync(DateTime date)
{
    // date 是 UTC-5 格式的日期
    var dateStart = GetUtc5DateStart(date);  // UTC 时间
    var dateEnd = GetUtc5DateEnd(date);      // UTC 时间
    
    // 获取该日期范围内所有成功扫描记录
    var successfulScans = await _labelScanService
        .GetScanRecordsByDateRangeAsync(dateStart, dateEnd, ScanResult.ReturnedLabel);
    
    if (successfulScans == null || successfulScans.Count == 0)
        return 0;
    
    // 筛选 Description 包含 "STOP" 的记录，去重统计
    var stopCount = successfulScans
        .Where(s => s.Description != null && s.Description.Contains("STOP", StringComparison.OrdinalIgnoreCase))
        .Select(s => s.NeutralWaybillNumber)
        .Distinct()
        .Count();
    
    return stopCount;
}
```

#### 5.6 当日标签推送数（Daily Label Push Count）

**定义**: 标签推送时间是当天（UTC-5）的订单数

**计算逻辑**:
```
1. 获取所有 LabelRetrievedAt 不为 NULL 的订单
2. 将 LabelRetrievedAt（UTC+0）转换为 UTC-5
3. 筛选时间在当天的订单
4. 统计数量
```

#### 5.7 当天换单完成率（Daily Completion Rate）

**定义**: 当日换单完成数 / 当天应该换单数

**计算逻辑**:
```
完成率 = (Daily Completion Count) / (Daily Should Replace Count) * 100%
```

#### 5.8 当日扫描数（Daily Scan Count）

**定义**: 扫描时间是当天（UTC-5）的扫描记录总数（不去重）

**计算逻辑**:
```
1. 获取当日（UTC-5）内所有扫描记录（任意结果）
2. 统计记录总数（不进行去重）
```

**代码示例**:
```csharp
public async Task<int> GetDailyScanCountAsync(DateTime date)
{
    // date 是 UTC-5 格式的日期
    var dateStart = GetUtc5DateStart(date);  // UTC 时间
    var dateEnd = GetUtc5DateEnd(date);      // UTC 时间
    
    // 获取该日期范围内的所有扫描记录
    var allScans = await _labelScanService
        .GetScanRecordsByDateRangeAsync(dateStart, dateEnd, resultFilter: null);
    
    return allScans?.Count ?? 0;
}
```

#### 5.9 16点前到仓包裹数（Before Noon Arrived Count）

**定义**: 到仓时间在当天 16:00 之前（UTC-5）的订单总数

**说明**：此指标用于统计分时段到仓的包裹数，用于后续分析和考核时间的关联。

**计算逻辑**:
```
1. 选取 ReceiptTime 在当天（UTC-5）且时间 <= 16:00 的订单
2. 统计数量
```

#### 5.10 16点后到仓包裹数（Afternoon Arrived Count）

**定义**: 到仓时间在当天 16:00 之后（UTC-5）的订单总数

**说明**：与 16点前到仓包裹数配套，用于分时段统计。

**计算逻辑**:
```
1. 选取 ReceiptTime 在当天（UTC-5）且时间 > 16:00 的订单
2. 统计数量
```

#### 5.11 16点前考核通过包裹数（Before Noon Passed Count）

**定义**: 16点前到仓且标签率 >= 80% 的订单中，在考核时间内完成的订单数

**说明**：配套 5.9 指标，统计早上到仓的订单中有多少在次日 16:00 前完成考核。

**计算逻辑**:
```
1. 获取当天 ReceiptTime <= 16:00 且标签率 >= 80% 的订单
2. 这些订单的考核时间为次日 16:00
3. 统计其中有成功扫描记录且时间 <= 次日 16:00 的订单
```

#### 5.12 16点后考核通过包裹数（Afternoon Passed Count）

**定义**: 16点后到仓且标签率 >= 80% 的订单中，在考核时间内完成的订单数

**说明**：配套 5.10 指标，统计下午到仓的订单中有多少在次日 23:59 前完成考核。

**计算逻辑**:
```
1. 获取当天 ReceiptTime > 16:00 且标签率 >= 80% 的订单
2. 这些订单的考核时间为次日 23:59
3. 统计其中有成功扫描记录且时间 <= 次日 23:59 的订单
```

---

## 实现方案

### 第一阶段：数据模型与DTO扩展

#### 1.1 新增DTO类

**MetricsCalculationDto.cs** - 存储中间计算结果
```
- NeutralWaybillNumber
- LabelRate (第一次扫描时的标签率)
- FirstScanTime (第一条扫描记录的时间)
- FirstScanResult (第一条扫描记录的结果)
- ReceiptTime (收货时间)
- AssessmentTime (考核时间)
- IsHighLabelRate (标签率 >= 80%)
- CompletedOnTime (是否在考核时间内完成)
- CompletionTime (实际完成时间)
- HandoverNumber (交接单号)
- ArrivalDate (到仓日期)
```

**LabelRateMetricsDto.cs** - 交接单级别的标签率
```
- HandoverNumber (交接单号)
- TotalOrderCount (总订单数)
- LabeledOrderCount (有标签的订单数)
- LabelRate (标签率百分比)
- FirstScanTime (现场首次扫描时间)
```

**Daily24HCompletionRateDto.cs** - 日统计完成率
```
- Date (日期, UTC-5)
- DailyNewReplaceCount (当天新增换单数)
- CumulativeTotalReplaceCount (累计要换的总单数)
- UnfinishedFailureCount (换单失败未完结订单)
- DailyFailureCount (当日换单失败)
- DailySuccessCount (当日换单成功数)
- DailyStopCount (当日STOP数)
- DailyShouldReplaceCount (当天应该换单数)
- HighLabelRateOrderCount (标签率 >= 80% 的订单数)
- CompletedOnTimeCount (按时完成的订单数)
- Rate24Hour (24小时完成率百分比)
- DailyCompletionRate (当天换单完成率百分比)
- DailyLabelPushCount (当日标签推送数)
- DailyScanCount (当日扫描数)
- BeforeNoonArrivedCount (16点前到仓包裹数)
- AfternoonArrivedCount (16点后到仓包裹数)
- BeforeNoonPassedCount (16点前考核通过包裹数)
- AfternoonPassedCount (16点后考核通过包裹数)
- DataFetchTime (数据拉取时间, UTC-5)
```

#### 1.2 新增Entity（可选，如果需要持久化计算结果）

**MetricsCalculationResultEntity.cs** - 计算结果缓存表
```
- Id (主键)
- HandoverNumber
- NeutralWaybillNumber
- LabelRate
- AssessmentTime
- AssessmentDate
- CompletedOnTime
- CreatedAt
- CalculatedAt
```

---

### 第二阶段：Repository层扩展

在 `ILabelReplaceRepository` 中添加方法：

#### 2.1 LabelReplaceRepository 扩展方法

```csharp
// 获取指定交接单号对应的所有订单
Task<List<LabelReplaceEntity>> GetOrdersByHandoverNumberAsync(string handoverNumber)

// 获取指定交接单号列表对应的所有订单
Task<List<LabelReplaceEntity>> GetOrdersByHandoverNumbersAsync(List<string> handoverNumbers)

// 获取所有有标签的订单（不分页）
Task<List<LabelReplaceEntity>> GetAllOrdersWithLabelsAsync()

// 获取指定日期范围内有标签的订单
Task<List<LabelReplaceEntity>> GetOrdersWithLabelsByDateRangeAsync(
    DateTime startDate, DateTime endDate)
```

#### 2.2 LabelScanRepository 扩展方法

```csharp
// 获取指定日期范围内的扫描记录（指定结果）
Task<List<LabelScanEntity>> GetScanRecordsByDateRangeAsync(
    DateTime startDate, DateTime endDate, ScanResult? resultFilter = null)

// 获取指定中性面单号列表的所有扫描记录
Task<List<LabelScanEntity>> GetScanRecordsByNeutralWaybillNumbersAsync(
    List<string> neutralWaybillNumbers)

// 获取指定中性面单号的第一条扫描记录
Task<LabelScanEntity> GetFirstScanRecordByWaybillNumberAsync(string neutralWaybillNumber)

// 批量获取多个中性面单号的第一条扫描记录
Task<Dictionary<string, LabelScanEntity>> GetFirstScanRecordsByWaybillNumbersAsync(
    List<string> neutralWaybillNumbers)

// 检查指定时间前是否有成功扫描
Task<bool> HasSuccessScanBeforeAsync(string neutralWaybillNumber, DateTime beforeTime)

// 获取指定中性面单号的第一条成功扫描
Task<LabelScanEntity> GetFirstSuccessScanAsync(string neutralWaybillNumber)
```

#### 2.3 ArrivalHandoverFormRepository 扩展方法

```csharp
// 获取指定日期范围内的到货交接单
Task<List<ArrivalHandoverFormEntity>> GetArrivalHandoverFormsByDateRangeAsync(
    DateTime startDate, DateTime endDate)
```

---

#### 2.4 关键实现提示

**时区转换注意事项**:
- ReceiptTime（UTC-5）进行时间比较前，需转换为 UTC 再进行 SQL 比较
- LabelRetrievedAt（UTC+0）直接比较
- CreatedAt（UTC+0）直接比较
- 在应用层判断"16:00"时，需使用本地时间（UTC-5）进行判断

**标签率计算的核心逻辑**:
- 找到交接单关联的所有订单
- 检查是否存在该交接单的扫描记录
- 如果存在，找到第一条扫描记录的时间点，统计该时间点前有标签的订单数
- 如果不存在，统计当前有标签的订单数
- 标签率 = 满足条件的订单数 / 总数

---

### 第三阶段：Service层实现

#### 3.1 新建 `IMetricsCalculationService` 接口

```csharp
public interface IMetricsCalculationService
{
    // 时间转换辅助方法
    DateTime ConvertUtcToUtc5(DateTime utcTime);
    DateTime ConvertUtc5ToUtc(DateTime utc5Time);
    DateTime GetUtc5Today();
    DateTime GetUtc5DateStart(DateTime utc5Date);
    DateTime GetUtc5DateEnd(DateTime utc5Date);
    
    // 基础指标计算
    Task<LabelRateMetricsDto> GetLabelRateAsync(string handoverNumber);
    Task<MetricsCalculationDto> GetOrderMetricsAsync(string neutralWaybillNumber);
    
    // 当日指标计算
    Task<int> GetDailyNewReplaceCountAsync(DateTime date);
    Task<int> GetCumulativeTotalReplaceCountAsync(DateTime date);
    Task<int> GetDailyCompletionCountAsync(DateTime date);
    Task<int> GetDailyStopCountAsync(DateTime date);
    Task<int> GetDailyLabelPushCountAsync(DateTime date);
    Task<int> GetDailyUnfinishedFailureCountAsync();
    Task<int> GetDailyFailureCountAsync(DateTime date);
    Task<int> GetDailySuccessCountAsync(DateTime date);
    Task<int> GetDailyShouldReplaceCountAsync(DateTime date);
    Task<int> GetBeforeNoonArrivedCountAsync(DateTime date);
    Task<int> GetAfternoonArrivedCountAsync(DateTime date);
    Task<int> GetBeforeNoonPassedCountAsync(DateTime date);
    Task<int> GetAfternoonPassedCountAsync(DateTime date);
    Task<int> GetDailyScanCountAsync(DateTime date);
    
    // 24小时和每日完成率
    Task<double> Calculate24HCompletionRateAsync(DateTime date);
    Task<double> CalculateDailyCompletionRateAsync(DateTime date);
    
    // 完整日统计
    Task<Daily24HCompletionRateDto> GetDailySummaryAsync(DateTime date);
    
    // 批量计算多个订单的指标
    Task<List<MetricsCalculationDto>> GetBatchOrderMetricsAsync(List<string> neutralWaybillNumbers);
    
    // 获取指定日期范围的每日统计
    Task<List<Daily24HCompletionRateDto>> GetDailySummariesAsync(
        DateTime startDate, DateTime endDate);
    
    // 重新计算并缓存某个交接单的标签率
    Task<bool> RecalculateAndCacheLabelRateAsync(string handoverNumber);
}
```

#### 3.2 实现 `MetricsCalculationService`

**时区处理辅助方法**:

```csharp
private const int UTC_5_OFFSET = -5;

public DateTime ConvertUtcToUtc5(DateTime utcTime)
{
    return utcTime.AddHours(UTC_5_OFFSET);
}

public DateTime ConvertUtc5ToUtc(DateTime utc5Time)
{
    return utc5Time.AddHours(-UTC_5_OFFSET);
}

public DateTime GetUtc5Today()
{
    var now = DateTime.UtcNow;
    var utc5Now = ConvertUtcToUtc5(now);
    return utc5Now.Date;
}

public DateTime GetUtc5DateStart(DateTime utc5Date)
{
    // 返回 UTC-5 日期的开始时间（0:00:00），但以 UTC 时间表示
    var utc5Start = utc5Date.Date;
    return ConvertUtc5ToUtc(utc5Start);
}

public DateTime GetUtc5DateEnd(DateTime utc5Date)
{
    // 返回 UTC-5 日期的结束时间（23:59:59），但以 UTC 时间表示
    var utc5End = utc5Date.Date.AddDays(1).AddSeconds(-1);
    return ConvertUtc5ToUtc(utc5End);
}
```

**当日新增换单数计算**:

```csharp
public async Task<int> GetDailyNewReplaceCountAsync(DateTime date)
{
    // date 是 UTC-5 格式的日期
    var dateStart = GetUtc5DateStart(date);
    var dateEnd = GetUtc5DateEnd(date);
    
    // 获取该日期内到仓的所有交接单
    var arrivalForms = await _arrivalHandoverFormService
        .GetArrivalHandoverFormsByDateRangeAsync(dateStart, dateEnd);
    
    if (arrivalForms.Count == 0)
        return 0;
    
    var handoverNumbers = arrivalForms.Select(f => f.HandoverNumber).ToList();
    
    // 获取这些交接单关联的所有订单
    var orders = await _labelReplaceRepository
        .GetOrdersByHandoverNumbersAsync(handoverNumbers);
    
    // 统计有标签的订单数
    int count = orders.Count(o => !string.IsNullOrEmpty(o.Label));
    
    return count;
}
```

**累计要换的总单数计算**:

```csharp
public async Task<int> GetCumulativeTotalReplaceCountAsync(DateTime date)
{
    // date 是 UTC-5 格式的日期
    var dateStart = GetUtc5DateStart(date);
    
    // 获取所有有标签的订单
    var labeledOrders = await _labelReplaceRepository
        .GetAllOrdersWithLabelsAsync();
    
    // 排除当天新增的订单
    var pastOrders = labeledOrders
        .Where(o => o.LabelRetrievedAt < dateStart)
        .ToList();
    
    // 获取所有这些订单的扫描记录
    var waybills = pastOrders.Select(o => o.NeutralWaybillNumber).ToList();
    var scans = await _labelScanService
        .GetScanRecordsByNeutralWaybillNumbersAsync(waybills);
    
    // 统计没有成功扫描记录的订单
    var successfulWaybills = scans
        .Where(s => s.Result == ScanResult.ReturnedLabel)
        .Select(s => s.NeutralWaybillNumber)
        .ToHashSet();
    
    int count = pastOrders.Count(o => !successfulWaybills.Contains(o.NeutralWaybillNumber));
    
    return count;
}
```

**标签率计算方法**:

```csharp
private async Task<double> CalculateLabelRateAtFirstScanAsync(string handoverNumber)
{
    // 获取该交接单关联的所有订单
    var orders = await _labelReplaceRepository.GetOrdersByHandoverNumberAsync(handoverNumber);
    
    if (orders.Count == 0)
        return 0;
    
    // 获取该交接单所有订单的扫描记录
    var waybills = orders.Select(o => o.NeutralWaybillNumber).ToList();
    var allScans = await _labelScanService.GetScanRecordsByNeutralWaybillNumbersAsync(waybills);
    
    // 情况1：交接单不存在任何扫描记录
    if (allScans == null || allScans.Count == 0)
    {
        // 返回当前标签率
        int labeledCount = orders.Count(o => !string.IsNullOrEmpty(o.Label));
        return (double)labeledCount / orders.Count;
    }
    
    // 情况2：交接单存在扫描记录，找到最早的扫描时间
    var earliestScanTime = allScans.Min(s => s.CreatedAt);
    
    // 统计在最早扫描时间之前有标签的订单数
    int labeledAtScanTime = 0;
    foreach (var order in orders)
    {
        if (!string.IsNullOrEmpty(order.Label))
        {
            // LabelRetrievedAt 可能为 null，如果为 null 则使用 CreatedAt
            var labelRetrievedAt = order.LabelRetrievedAt ?? order.CreatedAt;
            if (labelRetrievedAt <= earliestScanTime)
            {
                labeledAtScanTime++;
            }
        }
    }
    
    return (double)labeledAtScanTime / orders.Count;
}
```

**当天应该换单数计算**:

```csharp
public async Task<int> GetDailyShouldReplaceCountAsync(DateTime date)
{
    // date 是 UTC-5 格式的日期
    var dateStart = GetUtc5DateStart(date);
    var dateEnd = GetUtc5DateEnd(date);
    
    // 获取该日期内到仓的所有交接单
    var arrivalForms = await _arrivalHandoverFormService
        .GetArrivalHandoverFormsByDateRangeAsync(dateStart, dateEnd);
    
    if (arrivalForms.Count == 0)
        return 0;
    
    int totalCount = 0;
    
    // 计算每个交接单的标签率
    foreach (var form in arrivalForms)
    {
        var labelRate = await CalculateLabelRateAtFirstScanAsync(form.HandoverNumber);
        
        // 只统计标签率 >= 80% 的交接单关联的订单
        if (labelRate >= 0.80)
        {
            var orders = await _labelReplaceRepository
                .GetOrdersByHandoverNumberAsync(form.HandoverNumber);
            totalCount += orders.Count;
        }
    }
    
    return totalCount;
}

**当日换单完成数计算**:

```csharp
public async Task<int> GetDailyCompletionCountAsync(DateTime date)
{
    // date 是 UTC-5 格式的日期
    var dateStart = GetUtc5DateStart(date);
    var dateEnd = GetUtc5DateEnd(date);
    
    // 获取该日期内有成功扫描记录的订单
    var successfulScans = await _labelScanService
        .GetScanRecordsByDateRangeAsync(dateStart, dateEnd, ScanResult.ReturnedLabel);
    
    // 去重订单，统计数量
    var uniqueWaybills = successfulScans
        .Select(s => s.NeutralWaybillNumber)
        .Distinct()
        .Count();
    
    return uniqueWaybills;
}
```

**当日STOP数计算**:

```csharp
public async Task<int> GetDailyStopCountAsync(DateTime date)
{
    // date 是 UTC-5 格式的日期
    var dateStart = GetUtc5DateStart(date);
    var dateEnd = GetUtc5DateEnd(date);
    
    // 获取该日期内所有成功扫描记录
    var successfulScans = await _labelScanService
        .GetScanRecordsByDateRangeAsync(dateStart, dateEnd, ScanResult.ReturnedLabel);
    
    // 筛选 Description 包含 "STOP" 的记录
    var stopScans = successfulScans
        .Where(s => s.Description != null && s.Description.Contains("STOP"))
        .Select(s => s.NeutralWaybillNumber)
        .Distinct()
        .Count();
    
    return stopScans;
}
```

**当日标签推送数计算**:

```csharp
public async Task<int> GetDailyLabelPushCountAsync(DateTime date)
{
    // date 是 UTC-5 格式的日期
    var dateStart = GetUtc5DateStart(date);
    var dateEnd = GetUtc5DateEnd(date);
    
    // 获取所有有标签推送时间的订单
    var allOrders = await _labelReplaceRepository.GetAllOrdersWithLabelsAsync();
    
    // 筛选推送时间在该日期内的订单
    int count = allOrders.Count(o => 
        o.LabelRetrievedAt.HasValue && 
        o.LabelRetrievedAt >= dateStart && 
        o.LabelRetrievedAt <= dateEnd
    );
    
    return count;
}
```

**完整日统计计算**:

```csharp
public async Task<Daily24HCompletionRateDto> GetDailySummaryAsync(DateTime date)
{
    // 并行计算所有指标
    var newReplaceCountTask = GetDailyNewReplaceCountAsync(date);
    var cumulativeCountTask = GetCumulativeTotalReplaceCountAsync(date);
    var completionCountTask = GetDailyCompletionCountAsync(date);
    var stopCountTask = GetDailyStopCountAsync(date);
    var labelPushCountTask = GetDailyLabelPushCountAsync(date);
    var shouldReplaceCountTask = GetDailyShouldReplaceCountAsync(date);
    var scanCountTask = GetDailyScanCountAsync(date);
    var beforeNoonCountTask = GetBeforeNoonArrivedCountAsync(date);
    var afternoonCountTask = GetAfternoonArrivedCountAsync(date);
    var beforeNoonPassedTask = GetBeforeNoonPassedCountAsync(date);
    var afternoonPassedTask = GetAfternoonPassedCountAsync(date);
    
    await Task.WhenAll(
        newReplaceCountTask, cumulativeCountTask, completionCountTask,
        stopCountTask, labelPushCountTask, shouldReplaceCountTask, scanCountTask,
        beforeNoonCountTask, afternoonCountTask, beforeNoonPassedTask, afternoonPassedTask
    );
    
    int newReplaceCount = await newReplaceCountTask;
    int cumulativeCount = await cumulativeCountTask;
    int completionCount = await completionCountTask;
    int stopCount = await stopCountTask;
    int labelPushCount = await labelPushCountTask;
    int shouldReplaceCount = await shouldReplaceCountTask;
    int scanCount = await scanCountTask;
    int beforeNoonCount = await beforeNoonCountTask;
    int afternoonCount = await afternoonCountTask;
    int beforeNoonPassed = await beforeNoonPassedTask;
    int afternoonPassed = await afternoonPassedTask;
    
    // 计算完成率
    double dailyCompletionRate = shouldReplaceCount > 0
        ? (double)completionCount / shouldReplaceCount * 100
        : 0;
    
    double rate24Hour = shouldReplaceCount > 0
        ? (double)completionCount / shouldReplaceCount * 100
        : 0;
    
    int unfinishedFailureCount = cumulativeCount;
    int dailyFailureCount = shouldReplaceCount - completionCount;
    int dailySuccessCount = completionCount;
    
    return new Daily24HCompletionRateDto
    {
        Date = date,
        DailyNewReplaceCount = newReplaceCount,
        CumulativeTotalReplaceCount = cumulativeCount,
        UnfinishedFailureCount = unfinishedFailureCount,
        DailyFailureCount = dailyFailureCount,
        DailySuccessCount = dailySuccessCount,
        DailyStopCount = stopCount,
        DailyShouldReplaceCount = shouldReplaceCount,
        DailyCompletionRate = $"{dailyCompletionRate:F2}%",
        Rate24Hour = $"{rate24Hour:F2}%",
        DailyLabelPushCount = labelPushCount,
        DailyScanCount = scanCount,
        BeforeNoonArrivedCount = beforeNoonCount,
        AfternoonArrivedCount = afternoonCount,
        BeforeNoonPassedCount = beforeNoonPassed,
        AfternoonPassedCount = afternoonPassed,
        DataFetchTime = ConvertUtcToUtc5(DateTime.UtcNow)
    };
}
```

---

### 第四阶段：Controller层扩展

新增 `MetricsController` 端点：

```csharp
[ApiController]
[Route("api/[controller]")]
public class MetricsController : ControllerBase
{
    private readonly IMetricsCalculationService _metricsService;

    [HttpGet("label-rate")]
    public async Task<IActionResult> GetLabelRate([FromQuery] string handoverNumber)
    
    [HttpGet("order-assessment")]
    public async Task<IActionResult> GetOrderAssessmentMetrics([FromQuery] string neutralWaybillNumber)
    
    [HttpGet("daily-summary")]
    public async Task<IActionResult> GetDailySummary([FromQuery] string date = null)
    
    [HttpGet("daily-summaries")]
    public async Task<IActionResult> GetDailySummaries([FromQuery] string startDate, [FromQuery] string endDate)
    
    [HttpPost("recalculate-label-rate")]
    public async Task<IActionResult> RecalculateLabelRate([FromBody] RecalculateLabelRateRequest request)
}
```

或扩展现有 `DashboardController`:

```csharp
[HttpGet("daily-metrics")]
public async Task<IActionResult> GetDailyMetrics([FromQuery] string date = null)

[HttpGet("date-range-metrics")]  
public async Task<IActionResult> GetDateRangeMetrics([FromQuery] string startDate, [FromQuery] string endDate)
```

---

## 第五阶段：测试与验证

### 5.1 单元测试

- 测试标签率计算（边界情况：0个订单、全有标签、全无标签、未扫描状态）
- 测试各项指标计算（多种时区场景）
- 测试边界时间（UTC vs UTC-5 转换）

### 5.2 集成测试

- 端到端的完整流程测试
- 使用真实数据验证结果的准确性
- 性能测试（大数据量的计算速度）

---

## 第六阶段：异步处理与优化

### 6.1 异步任务处理

- 大批量指标计算可使用后台任务
- 定期（如每小时）更新一次统计数据

### 6.2 查询优化

- 优化 Repository 层的 SQL 查询，避免 N+1 问题
- 使用预加载（Include）优化关联查询性能

---

## 实现步骤（优先级排序）

1. **第一步**: 创建DTO和接口定义
2. **第二步**: Repository层方法实现
3. **第三步**: Service层核心算法实现
4. **第四步**: Controller端点实现
5. **第五步**: 测试与验证
6. **第六步**: 异步处理与性能优化
7. **第七步**: 文档完善和代码审查

---

## 关键注意事项

1. **时区处理**: 确保所有时间比较都使用 UTC，再根据需要转换为特定时区
2. **Null处理**: ReceiptTime可能为NULL，需要特殊处理
3. **多次重复**: 同一个订单可能有多条扫描记录，需要去重和排序
4. **性能**: 涉及多表JOIN和复杂计算，需要优化SQL查询
5. **数据一致性**: 计算过程中数据可能变化，需要事务保证

---

## 依赖关系

- 现有的 `LabelReplaceService`
- 现有的 `LabelScanService`
- 现有的 `ArrivalHandoverFormService`
- 可能需要新增 `ILabelScanRepository` 的扫描查询方法