# 存储过程逻辑修复计划 - 修订版

## 关键业务规则（已确认）

**时间字段类型**：
- ✅ `arrival_handover_forms.ReceiptTime` = **已经是 UTC-5 时间**（美国东部时间）
- ✅ `label_replace_requests.CreatedAt` = **UTC+0 时间**（需要转换到 UTC-5）
- ✅ `label_scan_history.CreatedAt` = **UTC+0 时间**（需要转换到 UTC-5）

## 问题根因

之前的存储过程在 **ReceiptTime 上进行了不必要的 CONVERT_TZ 转换**，导致：
1. ReceiptTime 本已是 UTC-5，再转换一次就完全错了
2. 时间比较条件全部失效
3. 所有 JOIN 都返回空结果
4. 所有计数都是0

## 修复方案

### 关键修改点

#### 1. ReceiptTime 不需要转换
```sql
-- 错误（之前的做法）
WHERE DATE(CONVERT_TZ(ahf.ReceiptTime, '+00:00', '-05:00')) = p_date

-- 正确（新做法）
WHERE DATE(ahf.ReceiptTime) = p_date
```

#### 2. CreatedAt 需要转换到 UTC-5
```sql
-- 需要转换
WHERE DATE(CONVERT_TZ(r.CreatedAt, '+00:00', '-05:00')) = p_date
WHERE DATE(CONVERT_TZ(s.CreatedAt, '+00:00', '-05:00')) = p_date
```

#### 3. 时间比较逻辑修正

对于 BeforeNoonArrivedCount（16点前到仓）：
```sql
-- 之前错误的做法：
WHERE HOUR(CONVERT_TZ(tqa.ReceiptTime, '+00:00', '-05:00')) < 16
-- 改为（不转换，ReceiptTime已经是UTC-5）
WHERE HOUR(tqa.ReceiptTime) < 16
```

## 新的存储过程逻辑框架

```sql
CREATE PROCEDURE sp_GetDailyMetricsSummary(IN p_date DATE)
BEGIN
  -- 不需要转换 ReceiptTime，它已经是 UTC-5
  
  -- 1. DailyShouldReplaceCount：当日到仓的标签订单数
  SELECT COUNT(DISTINCT r.Id) INTO v_daily_should_replace_count
  FROM label_replace_requests r
  INNER JOIN arrival_handover_forms ahf ON 
    (r.BillOfLadingNumber = ahf.HandoverNumber OR r.MasterPackageNumber = ahf.HandoverNumber)
  WHERE r.Label IS NOT NULL
    AND DATE(ahf.ReceiptTime) = p_date;  -- 不转换！
  
  -- 2. DailySuccessCount：当日扫描成功数
  SELECT COUNT(DISTINCT s.NeutralWaybillNumber) INTO v_daily_success_count
  FROM label_scan_history s
  WHERE s.Result = 0
    AND DATE(CONVERT_TZ(s.CreatedAt, '+00:00', '-05:00')) = p_date;  -- 需要转换
  
  -- 3. BeforeNoonArrivedCount：16点前到仓数
  SELECT COUNT(DISTINCT r.Id) INTO v_before_noon_arrived_count
  FROM label_replace_requests r
  INNER JOIN arrival_handover_forms ahf ON 
    (r.BillOfLadingNumber = ahf.HandoverNumber OR r.MasterPackageNumber = ahf.HandoverNumber)
  WHERE r.Label IS NOT NULL
    AND DATE(ahf.ReceiptTime) = p_date  -- 不转换！
    AND HOUR(ahf.ReceiptTime) < 16;     -- 不转换！
  
  -- ... 其他指标类似修改
END
```

## 修复清单

- [ ] 移除 ReceiptTime 上的所有 CONVERT_TZ 转换
- [ ] 保留 CreatedAt 上的 CONVERT_TZ 转换（UTC+0 → UTC-5）
- [ ] 修复 HOUR() 函数调用 - 不转换 ReceiptTime
- [ ] 测试修复后的存储过程
- [ ] 验证各个指标是否返回正确的非零数据

## 执行步骤

### 第一步：修改存储过程

根据上述规则修改 `sp_GetDailyMetricsSummary` 存储过程，主要是：
- 移除 ReceiptTime 的 CONVERT_TZ
- 保留 CreatedAt 的 CONVERT_TZ
- 修正所有时间比较逻辑

### 第二步：数据库验证

```sql
-- 测试修改后的存储过程
CALL sp_GetDailyMetricsSummary('2026-04-03');

-- 验证各指标是否有数据
SELECT * FROM (
  CALL sp_GetDailyMetricsSummary('2026-04-03')
) result;
```

### 第三步：前端集成测试

启动后端，在仪表盘中查询同一日期，验证数据正确性

## 根本问题总结

**错误原因**：对 ReceiptTime（已是 UTC-5）进行了多余的时区转换，导致时间条件全部失效，从而所有 JOIN 和 WHERE 条件都返回空结果，最终所有计数都是0。

**修复关键**：理解每个表的时间字段类型，正确地只对需要转换的字段（CreatedAt）进行转换，不转换已是目标时区的字段（ReceiptTime）。