上传源代码版本

.trae/specs/dashboard_refactor/modification_document.md

@@ -0,0 +1,82 @@
+# 数据看板查询逻辑重构 - 修改说明文档
+
+## 1. 变更概述
+
+本次修改重构了数据看板的查询逻辑，从到货交接单的数据开始，以到货交接单的交接单号去匹配提单号和主包号，从而统计到货情况。
+
+## 2. 变更内容
+
+### 2.1 后端API修改
+
+修改了 `LabelReplaceService.cs` 中的 `GetDashboardDataAsync` 方法，具体变更如下：
+
+1. **查询逻辑起点变更**：从 `label_replace_requests` 表变更为 `arrival_handover_forms` 表
+2. **数据匹配方式**：以到货交接单的 `HandoverNumber` 去匹配 `label_replace_requests` 表中的 `BillOfLadingNumber` 或 `MasterPackageNumber`
+3. **保持兼容性**：保持现有的API接口不变，确保前端代码无需修改
+
+### 2.2 实现细节
+
+#### 2.2.1 提单号预报查询逻辑
+1. 获取所有符合条件的到货交接单
+2. 对于每个到货交接单，以其交接单号作为提单号，匹配 `label_replace_requests` 表中的 `BillOfLadingNumber`
+3. 按 `BillOfLadingNumber` 分组统计
+4. 计算各种统计指标
+
+#### 2.2.2 大箱号预报查询逻辑
+1. 获取所有符合条件的到货交接单
+2. 对于每个到货交接单，以其交接单号作为大箱号，匹配 `label_replace_requests` 表中的 `MasterPackageNumber`
+3. 按 `MasterPackageNumber` 分组统计
+4. 计算各种统计指标
+
+## 3. 性能优化
+
+### 3.1 索引优化建议
+- 为 `arrival_handover_forms` 表的 `HandoverNumber` 字段添加索引
+- 为 `label_replace_requests` 表的 `BillOfLadingNumber` 和 `MasterPackageNumber` 字段添加索引
+- 为 `label_replace_requests` 表的 `CustomerId` 字段添加索引
+
+### 3.2 查询优化
+- 使用批量查询减少数据库访问次数
+- 避免在循环中进行数据库查询
+- 合理使用内存缓存
+
+## 4. 使用说明
+
+### 4.1 前端使用
+
+前端代码无需修改，继续使用现有的API接口：
+
+- 提单号预报：`/api/dashboard/query?type=billOfLading&billOfLadingNumber=xxx&startDate=xxx&endDate=xxx&customerId=xxx`
+- 大箱号预报：`/api/dashboard/query?type=masterPackage&masterPackageNumber=xxx&startDate=xxx&endDate=xxx&customerId=xxx`
+
+### 4.2 后端配置
+
+1. 确保 `IArrivalHandoverFormService` 接口已正确实现
+2. 确保数据库表结构已正确创建
+3. 考虑添加必要的索引以提高查询性能
+
+## 5. 测试建议
+
+### 5.1 功能测试
+1. 测试提单号预报功能，验证数据是否正确统计
+2. 测试大箱号预报功能，验证数据是否正确统计
+3. 测试各种过滤条件，确保过滤功能正常工作
+
+### 5.2 性能测试
+1. 测试大数据量下的查询性能
+2. 测试响应时间，确保在可接受范围内（<5秒）
+
+### 5.3 数据准确性测试
+1. 使用测试数据验证统计结果的准确性
+2. 与手动计算结果进行比较
+
+## 6. 注意事项
+
+1. **数据一致性**：确保到货交接单与标签替换请求数据的一致性
+2. **性能监控**：监控查询性能，必要时进行进一步优化
+3. **错误处理**：确保错误处理机制完善，避免因数据异常导致查询失败
+4. **日志记录**：确保关键操作有充分的日志记录，便于排查问题
+
+## 7. 总结
+
+本次修改重构了数据看板的查询逻辑，从到货交接单的数据开始，以交接单号匹配提单号和主包号，从而更加准确地统计到货情况。修改保持了与前端的兼容性，同时提供了更好的性能和数据准确性。