LabelChange-server/.trae/specs/dashboard_refactor/modification_document.md

数据看板查询逻辑重构 - 修改说明文档

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. 总结

本次修改重构了数据看板的查询逻辑，从到货交接单的数据开始，以交接单号匹配提单号和主包号，从而更加准确地统计到货情况。修改保持了与前端的兼容性，同时提供了更好的性能和数据准确性。