上传源代码版本

.trae/documents/frontend_error_fix_plan.md

@@ -0,0 +1,175 @@
+# 前端数据显示错误 + 存储过程返回数据异常 - 修复计划
+
+## 问题诊断
+
+### 观察到的现象
+1. **后端API返回成功** (success: true)
+2. **数据内容异常**：
+   - dailyNewReplaceCount: 0
+   - dailyShouldReplaceCount: 0
+   - dailySuccessCount: 0
+   - dailyCompletionRate: "0.00%"
+   - rate24Hour: "0.00%"
+   - 其他指标也为0或无意义
+   - 仅有 cumulativeTotal: 106 有数据
+
+### 根本原因分析
+1. **存储过程可能未创建或版本错误**
+   - 可能用户尚未在数据库中执行创建脚本
+   - 或者执行脚本时出现语法错误，但未被察觉
+
+2. **存储过程返回空结果或默认值**
+   - 如果存储过程不存在，应该报错
+   - 但如果返回空结果集，应用层会返回默认值（全0）
+
+3. **应用层降级处理**
+   - MetricsCalculationService.GetDailySummaryAsync 中如果存储过程失败，自动降级到 GetDailySummaryAsync_Original
+   - 但降级方法查询的是当前日期，不是查询参数的日期
+
+4. **时区问题**
+   - 查询的日期与数据库中实际存在的日期可能不符
+
+5. **前端日期选择问题**
+   - 用户选择的日期可能数据库中不存在
+
+## 修复步骤
+
+### 步骤1：验证存储过程是否存在
+**目标**：确认存储过程是否正确创建
+
+**操作**：
+1. 在MySQL中执行：
+   ```sql
+   SHOW PROCEDURE STATUS WHERE Db = 'lr01mainusa' AND Name = 'sp_GetDailyMetricsSummary';
+   ```
+2. 如果没有返回结果，说明存储过程未创建
+3. 如果有返回结果，说明存储过程存在
+
+### 步骤2：直接测试存储过程
+**目标**：验证存储过程的输出数据
+
+**操作**：
+1. 执行：
+   ```sql
+   CALL sp_GetDailyMetricsSummary('2026-05-17');
+   ```
+2. 检查返回的数据：
+   - 是否返回一行结果
+   - 各列的值是否合理（不都是0）
+   - 特别检查 DailyShouldReplaceCount 和 DailySuccessCount
+
+### 步骤3：检查后端日期参数传递
+**文件**：`src/CONTROLLER/Controllers/MetricsController.cs` 中的 `GetDailyDashboard` 方法
+
+**检查内容**：
+1. API是否正确接收查询参数 date
+2. 是否正确传递给 MetricsCalculationService.GetDailySummaryAsync(date)
+3. 日期格式是否正确（应为 yyyy-MM-dd）
+
+### 步骤4：添加应用层日志调试
+**文件**：`src/BLL/Services/MetricsCalculationService.cs`
+
+**操作**：
+在 GetDailySummaryAsync 方法中添加详细日志：
+```csharp
+_logger.LogInformation("Executing stored procedure with date: {date:yyyy-MM-dd}", date);
+_logger.LogInformation("SQL query: {sql}", sql);
+// 执行后添加
+_logger.LogInformation("Stored procedure returned {count} rows", summaryList?.Count ?? 0);
+if (summaryList?.Count > 0)
+{
+    var firstRow = summaryList[0];
+    _logger.LogInformation("First row data: {data}", JsonConvert.SerializeObject(firstRow));
+}
+```
+
+### 步骤5：前端错误处理修复
+**文件**：`metrics-dashboard.html`
+
+**问题**：前端显示error，但实际data存在（success: true）
+
+**原因**：
+1. 前端可能在处理全0数据时抛出错误
+2. 或者在计算完成率时出现异常
+
+**修复**：
+1. 检查前端的数据验证逻辑
+2. 添加对零值的容错处理
+3. 显示友好的"暂无数据"提示而不是错误
+
+### 步骤6：排查数据问题
+**问题**：为什么只有 cumulativeTotal: 106，其他都是0？
+
+**可能原因**：
+1. 选择的日期（2026-05-17）在数据库中可能没有到仓记录（arrival_handover_forms）
+2. 或者到仓记录的时间不在UTC-5转换后的当天
+
+**验证SQL**：
+```sql
+-- 检查2026-05-17的到仓记录数
+SELECT COUNT(*) as arrival_count,
+       COUNT(DISTINCT HandoverNumber) as unique_handover_count
+FROM arrival_handover_forms
+WHERE DATE(CONVERT_TZ(ReceiptTime, '+00:00', '-05:00')) = '2026-05-17';
+
+-- 检查标签数据
+SELECT COUNT(*) as label_count
+FROM label_replace_requests
+WHERE DATE(CONVERT_TZ(CreatedAt, '+00:00', '-05:00')) = '2026-05-17' 
+  AND Label IS NOT NULL;
+
+-- 检查扫描数据
+SELECT COUNT(*) as scan_count
+FROM label_scan_history
+WHERE DATE(CONVERT_TZ(CreatedAt, '+00:00', '-05:00')) = '2026-05-17';
+```
+
+## 实现顺序
+
+1. **验证存储过程** → 确认是否存在和可执行
+2. **直接测试存储过程** → 验证输出数据
+3. **检查API参数传递** → 确保日期正确传递
+4. **添加应用层日志** → 调试返回的具体数据
+5. **验证源数据** → 确认数据库中2026-05-17的实际数据
+6. **修复前端错误处理** → 正确显示数据或提示
+
+## 关键文件
+
+### 需要检查的文件
+1. `src/BLL/Services/MetricsCalculationService.cs` - GetDailySummaryAsync方法
+2. `src/CONTROLLER/Controllers/MetricsController.cs` - GetDailyDashboard方法
+3. `metrics-dashboard.html` - 前端数据处理逻辑
+
+### 需要执行的SQL语句
+- 验证存储过程存在性
+- 直接调用存储过程测试
+- 验证源数据是否存在
+
+## 预期解决方案
+
+### 情景A：存储过程未创建
+1. 用户执行创建脚本
+2. 重新测试
+3. 问题解决
+
+### 情景B：存储过程返回全0
+1. 检查2026-05-17是否有实际数据
+2. 修正存储过程中的时区转换或JOIN逻辑
+3. 或选择有数据的日期重新测试
+
+### 情景C：API未正确传递日期
+1. 修改MetricsController中的参数传递逻辑
+2. 确保日期格式正确
+
+### 情景D：前端数据处理错误
+1. 修复前端的数据验证和显示逻辑
+2. 添加null/zero检查
+
+## 验收标准
+
+1. ✅ 存储过程成功创建并可执行
+2. ✅ 直接测试存储过程返回非零数据
+3. ✅ API返回合理的数据值（不都是0）
+4. ✅ 前端正确显示数据或友好的"暂无数据"提示
+5. ✅ 选择有数据的日期时，仪表盘显示完整指标
+