上传源代码版本

2026-06-01 16:30:29 +08:00
commit b2a9b7d3c2
462 changed files with 104365 additions and 0 deletions
--- a/.trae/documents/stored_procedure_logic_fix_plan.md
+++ b/.trae/documents/stored_procedure_logic_fix_plan.md
@@ -0,0 +1,120 @@
+# 存储过程逻辑修复计划 - 修订版
+
+## 关键业务规则（已确认）
+
+**时间字段类型**：
+- ✅ `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）。
+