上传源代码版本

2026-06-01 16:30:29 +08:00
commit b2a9b7d3c2
462 changed files with 104365 additions and 0 deletions
--- a/.trae/specs/dashboard_refactor/checklist.md
+++ b/.trae/specs/dashboard_refactor/checklist.md
@@ -0,0 +1,12 @@
+# 数据看板查询逻辑重构 - 验证清单
+
+- [ ] 验证当前查询逻辑的分析是否正确
+- [ ] 验证新查询逻辑的设计是否合理
+- [ ] 验证后端API修改是否完成
+- [ ] 验证提单号预报功能是否正常
+- [ ] 验证大箱号预报功能是否正常
+- [ ] 验证统计数据的准确性
+- [ ] 验证查询性能是否满足要求
+- [ ] 验证API接口是否与前端兼容
+- [ ] 验证文档是否完整且可读
+- [ ] 验证所有测试要求是否满足
--- a/.trae/specs/dashboard_refactor/modification_document.md
+++ b/.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. 总结
+
+本次修改重构了数据看板的查询逻辑，从到货交接单的数据开始，以交接单号匹配提单号和主包号，从而更加准确地统计到货情况。修改保持了与前端的兼容性，同时提供了更好的性能和数据准确性。
--- a/.trae/specs/dashboard_refactor/new_query_logic.md
+++ b/.trae/specs/dashboard_refactor/new_query_logic.md
@@ -0,0 +1,285 @@
+# 数据看板新查询逻辑设计
+
+## 1. 新查询逻辑概述
+
+### 1.1 基本思路
+- 从到货交接单（arrival_handover_forms）开始查询
+- 以到货交接单的交接单号（HandoverNumber）去匹配标签替换请求（label_replace_requests）表中的提单号（BillOfLadingNumber）或主包号（MasterPackageNumber）
+- 保持现有的两个模块：提单号预报和大箱号预报
+
+### 1.2 实现步骤
+1. 获取所有符合条件的到货交接单
+2. 对于每个到货交接单，根据其交接单号匹配标签替换请求
+3. 按提单号或大箱号分组统计
+4. 计算各种统计指标
+
+## 2. 具体实现逻辑
+
+### 2.1 提单号预报查询逻辑
+1. 获取所有符合条件的到货交接单
+2. 对于每个到货交接单，以其交接单号作为提单号，匹配 label_replace_requests 表中的 BillOfLadingNumber
+3. 按 BillOfLadingNumber 分组统计
+4. 计算统计指标
+
+### 2.2 大箱号预报查询逻辑
+1. 获取所有符合条件的到货交接单
+2. 对于每个到货交接单，以其交接单号作为大箱号，匹配 label_replace_requests 表中的 MasterPackageNumber
+3. 按 MasterPackageNumber 分组统计
+4. 计算统计指标
+
+## 3. 代码实现设计
+
+### 3.1 修改 LabelReplaceService.cs 中的 GetDashboardDataAsync 方法
+
+```csharp
+public async Task<List<DashboardDataDto>> GetDashboardDataAsync(string type, string billOfLadingNumber, string masterPackageNumber, string startDate, string endDate, int? customerId)
+{
+    try
+    {
+        _logger.LogInformation("Retrieving dashboard data. Type: {type}, BillOfLading: {billOfLading}, MasterPackage: {masterPackage}", 
+            type, billOfLadingNumber, masterPackageNumber);
+
+        // 1. 获取所有符合条件的到货交接单
+        var allArrivalForms = await _arrivalHandoverFormService.GetAllAsync();
+
+        // 2. 过滤到货交接单
+        var filteredArrivalForms = allArrivalForms.Where(form =>
+        {
+            // 按日期过滤
+            if (!string.IsNullOrEmpty(startDate))
+            {
+                var start = DateTime.Parse(startDate);
+                if (form.ReceiptTime < start)
+                    return false;
+            }
+
+            if (!string.IsNullOrEmpty(endDate))
+            {
+                var end = DateTime.Parse(endDate);
+                if (form.ReceiptTime > end)
+                    return false;
+            }
+
+            return true;
+        }).ToList();
+
+        // 3. 获取所有标签替换请求
+        var allRequests = await _labelReplaceRepository.GetAllAsync();
+
+        // 4. 按类型匹配数据
+        var matchedRequests = new List<LabelReplaceEntity>();
+        foreach (var form in filteredArrivalForms)
+        {
+            if (type == "billOfLading")
+            {
+                // 提单号预报：以交接单号匹配提单号
+                var requests = allRequests.Where(req => 
+                    req.BillOfLadingNumber == form.HandoverNumber &&
+                    (!customerId.HasValue || req.CustomerId == customerId.Value) &&
+                    (string.IsNullOrEmpty(billOfLadingNumber) || req.BillOfLadingNumber == billOfLadingNumber)
+                );
+                matchedRequests.AddRange(requests);
+            }
+            else
+            {
+                // 大箱号预报：以交接单号匹配主包号
+                var requests = allRequests.Where(req => 
+                    req.MasterPackageNumber == form.HandoverNumber &&
+                    (!customerId.HasValue || req.CustomerId == customerId.Value) &&
+                    (string.IsNullOrEmpty(masterPackageNumber) || req.MasterPackageNumber == masterPackageNumber)
+                );
+                matchedRequests.AddRange(requests);
+            }
+        }
+
+        // 5. 按提单号或大箱号分组
+        var groupedData = new Dictionary<string, List<LabelReplaceEntity>>();
+        foreach (var req in matchedRequests)
+        {
+            string key;
+            if (type == "billOfLading")
+            {
+                key = req.BillOfLadingNumber ?? "Unknown";
+            }
+            else
+            {
+                key = req.MasterPackageNumber ?? "Unknown";
+            }
+
+            if (!groupedData.ContainsKey(key))
+            {
+                groupedData[key] = new List<LabelReplaceEntity>();
+            }
+            groupedData[key].Add(req);
+        }
+
+        // 6. 处理每个分组的数据
+        var dashboardData = new List<DashboardDataDto>();
+        foreach (var group in groupedData)
+        {
+            var requests = group.Value;
+            if (requests.Count == 0)
+                continue;
+
+            var firstRequest = requests.First();
+
+            // 获取客户简称
+            string customerCode = "Unknown";
+            if (firstRequest.CustomerId.HasValue)
+            {
+                var customer = await _customerRepository.GetByIdAsync(firstRequest.CustomerId.Value);
+                if (customer != null)
+                {
+                    customerCode = customer.CustomerCode;
+                }
+            }
+
+            // 计算到货订单数量
+            int arrivalOrderCount = requests.Count;
+
+            // 计算无标签数据数量
+            int noLabelDataCount = requests.Count(req => string.IsNullOrEmpty(req.Label));
+
+            // 计算已有标签订单数
+            int labeledOrderCount = requests.Count(req => !string.IsNullOrEmpty(req.Label));
+
+            // 计算已有标签率
+            string labelRate = "0%";
+            if (arrivalOrderCount > 0)
+            {
+                double rate = (double)labeledOrderCount / arrivalOrderCount * 100;
+                labelRate = $"{rate:F2}%";
+            }
+
+            // 计算换单完成数量（根据扫描记录）
+            int replaceCompletedCount = 0;
+            try
+            {
+                // 收集所有需要查询的中性面单单号
+                var waybillNumbers = requests.Select(req => req.NeutralWaybillNumber).Where(num => !string.IsNullOrEmpty(num)).Distinct().ToList();
+                
+                if (waybillNumbers.Count > 0)
+                {
+                    // 一次性批量查询所有扫描记录
+                    var allScans = await _labelScanService.GetScanRecordsByNeutralWaybillNumbersAsync(waybillNumbers);
+                    
+                    // 在内存中处理结果
+                    var returnedLabelScans = allScans.Where(scan => scan.Result == ScanResult.ReturnedLabel).Select(scan => scan.NeutralWaybillNumber).ToHashSet();
+                    
+                    // 统计换单完成数量
+                    replaceCompletedCount = requests.Count(req => !string.IsNullOrEmpty(req.NeutralWaybillNumber) && returnedLabelScans.Contains(req.NeutralWaybillNumber));
+                }
+            }
+            catch (Exception ex)
+            {
+                _logger.LogError(ex, "Error calculating replace completed count");
+                // 如果批量查询失败，回退到单条查询
+                foreach (var req in requests)
+                {
+                    try
+                    {
+                        var scans = await _labelScanService.GetScanRecordsByNeutralWaybillNumberAsync(req.NeutralWaybillNumber);
+                        if (scans.Any(scan => scan.Result == ScanResult.ReturnedLabel))
+                        {
+                            replaceCompletedCount++;
+                        }
+                    }
+                    catch (Exception innerEx)
+                    {
+                        _logger.LogError(innerEx, "Error querying scan records for waybill: {WaybillNumber}", req.NeutralWaybillNumber);
+                    }
+                }
+            }
+
+            // 计算未换单完成数量
+            int replacePendingCount = arrivalOrderCount - replaceCompletedCount;
+
+            // 获取到货时间（从到货交接单表中获取）
+            DateTime? arrivalTime = null;
+            try
+            {
+                // 尝试从到货交接单表中获取到货时间
+                string handoverNumber = type == "billOfLading" ? firstRequest.BillOfLadingNumber : firstRequest.MasterPackageNumber;
+                if (!string.IsNullOrEmpty(handoverNumber))
+                {
+                    var arrivalForms = await _arrivalHandoverFormService.GetArrivalHandoverFormsByHandoverNumberAsync(handoverNumber);
+                    if (arrivalForms != null && arrivalForms.Count > 0)
+                    {
+                        arrivalTime = arrivalForms.Min(form => form.ReceiptTime);
+                    }
+                }
+            }
+            catch (Exception ex)
+            {
+                _logger.LogError(ex, "Error retrieving arrival time from handover forms");
+                // 如果出错，不显示到货时间
+                arrivalTime = null;
+            }
+
+            // 创建数据看板DTO
+            var dto = new DashboardDataDto
+            {
+                Key = group.Key,
+                CustomerCode = customerCode,
+                ArrivalOrderCount = arrivalOrderCount,
+                ReplaceCompletedCount = replaceCompletedCount,
+                ReplacePendingCount = replacePendingCount,
+                NoLabelDataCount = noLabelDataCount,
+                LabeledOrderCount = labeledOrderCount,
+                LabelRate = labelRate,
+                ArrivalTime = arrivalTime,
+                BillOfLadingNumber = firstRequest.BillOfLadingNumber,
+                MasterPackageNumber = firstRequest.MasterPackageNumber
+            };
+
+            dashboardData.Add(dto);
+        }
+
+        _logger.LogInformation("Retrieved {count} dashboard data items", dashboardData.Count);
+        return dashboardData;
+    }
+    catch (Exception ex)
+    {
+        _logger.LogError(ex, "Error retrieving dashboard data");
+        return new List<DashboardDataDto>();
+    }
+}
+```
+
+## 4. 性能优化考虑
+
+### 4.1 索引优化
+- 为 `arrival_handover_forms` 表的 `HandoverNumber` 字段添加索引
+- 为 `label_replace_requests` 表的 `BillOfLadingNumber` 和 `MasterPackageNumber` 字段添加索引
+- 为 `label_replace_requests` 表的 `CustomerId` 字段添加索引
+
+### 4.2 查询优化
+- 使用批量查询减少数据库访问次数
+- 避免在循环中进行数据库查询
+- 合理使用内存缓存
+
+### 4.3 数据量控制
+- 考虑添加分页功能
+- 对于历史数据，可以考虑归档策略
+
+## 5. 测试计划
+
+### 5.1 功能测试
+- 测试提单号预报功能
+- 测试大箱号预报功能
+- 测试各种过滤条件
+
+### 5.2 性能测试
+- 测试大数据量下的查询性能
+- 测试响应时间
+
+### 5.3 数据准确性测试
+- 使用测试数据验证统计结果的准确性
+- 与手动计算结果进行比较
+
+## 6. 注意事项
+
+- 处理一个到货交接单对应多个提单号或主包号的情况
+- 处理标签替换请求中没有提单号或主包号的情况
+- 确保与前端API接口兼容
+- 保持代码的可读性和可维护性
--- a/.trae/specs/dashboard_refactor/spec.md
+++ b/.trae/specs/dashboard_refactor/spec.md
@@ -0,0 +1,72 @@
+# 数据看板查询逻辑重构 - 产品需求文档
+
+## Overview
+- **Summary**: 重构 batch_query.html 中的数据看板查询逻辑，从到货交接单的数据开始，以到货交接单的交接单号去匹配提单号和主包号，从而统计到货情况
+- **Purpose**: 优化数据看板的查询逻辑，使其更加准确地反映到货情况
+- **Target Users**: 物流操作人员、数据分析师
+
+## Goals
+- 从到货交接单的数据开始，以交接单号匹配提单号和主包号
+- 保持现有的两个模块：提单号预报和大箱号预报
+- 确保统计数据的准确性
+- 优化查询性能
+
+## Non-Goals (Out of Scope)
+- 不修改现有的UI结构
+- 不修改其他模块的功能
+- 不涉及数据库结构变更
+
+## Background & Context
+当前数据看板的查询逻辑是从标签替换请求表开始，直接按提单号或大箱号分组统计。这种方式可能会导致统计结果不准确，因为它没有考虑到到货交接单的实际情况。
+
+## Functional Requirements
+- **FR-1**: 保持现有的两个模块结构（提单号预报和大箱号预报）
+- **FR-2**: 修改查询逻辑，从到货交接单的数据开始
+- **FR-3**: 以到货交接单的交接单号去匹配提单号和主包号
+- **FR-4**: 统计到货订单数量、无标签数据数量、已有标签率等指标
+- **FR-5**: 支持按客户ID、日期范围等条件过滤
+
+## Non-Functional Requirements
+- **NFR-1**: 性能优化，避免全表扫描
+- **NFR-2**: 代码可读性和可维护性
+- **NFR-3**: 数据准确性
+
+## Constraints
+- **Technical**: 使用现有的API架构
+- **Business**: 无特殊业务约束
+- **Dependencies**: 依赖 `arrival_handover_forms` 表和 `label_replace_requests` 表
+
+## Assumptions
+- 数据库表结构已正确创建
+- 所有必要的索引已添加
+- 数据量在合理范围内
+
+## Acceptance Criteria
+
+### AC-1: 基本查询功能
+- **Given**: 存在到货交接单记录
+- **When**: 执行提单号预报查询
+- **Then**: 从到货交接单开始，以交接单号匹配提单号统计
+- **Verification**: `programmatic`
+
+### AC-2: 大箱号查询功能
+- **Given**: 存在到货交接单记录
+- **When**: 执行大箱号预报查询
+- **Then**: 从到货交接单开始，以交接单号匹配主包号统计
+- **Verification**: `programmatic`
+
+### AC-3: 数据准确性
+- **Given**: 存在测试数据
+- **When**: 执行查询并与手动计算结果比较
+- **Then**: 统计数据与手动计算一致
+- **Verification**: `human-judgment`
+
+### AC-4: 性能优化
+- **Given**: 数据量较大（如10万条记录）
+- **When**: 执行查询
+- **Then**: 查询响应时间在可接受范围内（<5秒）
+- **Verification**: `programmatic`
+
+## Open Questions
+- [ ] 如何处理一个到货交接单对应多个提单号或主包号的情况？
+- [ ] 是否需要修改后端API，还是只需要修改前端逻辑？
--- a/.trae/specs/dashboard_refactor/tasks.md
+++ b/.trae/specs/dashboard_refactor/tasks.md
@@ -0,0 +1,67 @@
+# 数据看板查询逻辑重构 - 实现计划
+
+## [x] Task 1: 分析当前查询逻辑
+- **Priority**: P0
+- **Depends On**: None
+- **Description**:
+  - 分析当前数据看板的查询逻辑
+  - 了解现有的API接口
+  - 确定需要修改的部分
+- **Acceptance Criteria Addressed**: AC-1, AC-2
+- **Test Requirements**:
+  - `human-judgment` TR-1.1: 理解当前查询逻辑
+  - `human-judgment` TR-1.2: 识别需要修改的部分
+- **Notes**: 重点关注查询逻辑的起点和数据匹配方式
+
+## [x] Task 2: 设计新的查询逻辑
+- **Priority**: P0
+- **Depends On**: Task 1
+- **Description**:
+  - 设计从到货交接单开始的查询逻辑
+  - 确定如何以交接单号匹配提单号和主包号
+  - 设计统计计算方法
+- **Acceptance Criteria Addressed**: AC-1, AC-2, AC-3
+- **Test Requirements**:
+  - `human-judgment` TR-2.1: 验证查询逻辑设计
+  - `human-judgment` TR-2.2: 确保统计方法正确
+- **Notes**: 考虑如何处理一个交接单对应多个提单号或主包号的情况
+
+## [x] Task 3: 实现后端API修改
+- **Priority**: P0
+- **Depends On**: Task 2
+- **Description**:
+  - 修改后端API，实现从到货交接单开始的查询逻辑
+  - 确保API接口与前端兼容
+  - 优化查询性能
+- **Acceptance Criteria Addressed**: AC-1, AC-2, AC-4
+- **Test Requirements**:
+  - `programmatic` TR-3.1: 验证API功能
+  - `programmatic` TR-3.2: 测试性能
+- **Notes**: 考虑使用JOIN和索引优化查询
+
+## [x] Task 4: 测试修改后的功能
+- **Priority**: P1
+- **Depends On**: Task 3
+- **Description**:
+  - 测试提单号预报功能
+  - 测试大箱号预报功能
+  - 验证统计数据的准确性
+  - 测试性能
+- **Acceptance Criteria Addressed**: AC-1, AC-2, AC-3, AC-4
+- **Test Requirements**:
+  - `programmatic` TR-4.1: 功能测试
+  - `human-judgment` TR-4.2: 数据准确性验证
+- **Notes**: 使用测试数据验证功能
+
+## [x] Task 5: 编写文档
+- **Priority**: P1
+- **Depends On**: Task 4
+- **Description**:
+  - 编写修改说明文档
+  - 记录查询逻辑的变更
+  - 提供使用说明
+- **Acceptance Criteria Addressed**: AC-1, AC-2, AC-3, AC-4
+- **Test Requirements**:
+  - `human-judgment` TR-5.1: 文档完整性
+  - `human-judgment` TR-5.2: 文档可读性
+- **Notes**: 确保文档包含所有必要的信息