上传源代码版本

.trae/documents/frozen_label_rate_implementation_summary.md

@@ -0,0 +1,197 @@
+# 日级报表SQL修改总结 - 冻结标签率实现
+
+**更新日期**: 2026-05-16  
+**版本**: v3.0 - 冻结标签率设计  
+**状态**: ✅ 编译通过，待测试
+
+---
+
+## 核心问题分析
+
+### 用户发现的逻辑问题
+原SQL设计中存在矛盾：**当日换单成功数 < 当日考核通过数**
+
+这在数学上是不可能的，因为"考核通过的包裹"必定是"成功包裹"的子集。
+
+### 根本原因
+使用**最终标签率**（所有订单的完整快照）来判断考核时间，导致：
+- 时间维度混乱：统计维度不一致
+- 标签率动态变化：无法确定哪个时刻的标签率应该被采用
+
+### 解决方案
+引入**冻结标签率**概念：
+- 以**最早的扫描时间**为分割线
+- 最早扫描时间与标签推送时间的关系确定包裹的标签率类别
+- 自动分类，避免复杂的历史快照计算
+
+---
+
+## 实施的核心修改
+
+### 1. InterchangeUnitLabelRates CTE（改进）
+
+**变更**：从"最终标签率"改为"冻结标签率"
+
+**原逻辑**：
+```sql
+COUNT(CASE WHEN l.Label IS NOT NULL THEN l.Id END) / COUNT(l.Id)
+-- 统计所有有标签的包裹比例
+```
+
+**新逻辑**：
+```sql
+COUNT(CASE WHEN l.Label IS NOT NULL 
+       AND MIN(扫描时间) > l.LabelRetrievedAt 
+       THEN l.Id END) / COUNT(l.Id)
+-- 统计"在标签推送后才开始作业"的包裹比例
+```
+
+**含义**：
+- `最早扫描时间 > 标签推送时间` = 标签推送早于作业开始 = 高标签率
+- `最早扫描时间 ≤ 标签推送时间` = 标签推送晚于或同时作业开始 = 低标签率
+
+### 2. DailyHighLabelRateShould CTE（新增）
+
+**功能**：统计冻结标签率 ≥ 80% 的交接单中的全部包裹数
+
+**逻辑**：
+```sql
+WHERE 冻结标签率 >= 80%
+```
+
+统计所有高标签率交接单中的包裹，这些包裹将按照"到仓时间16点前后分段"规则处理
+
+### 3. DailyLowLabelRateShould CTE（新增）
+
+**功能**：统计冻结标签率 < 80% 的交接单中的全部包裹数
+
+**逻辑**：
+```sql
+WHERE 冻结标签率 < 80%
+```
+
+统计所有低标签率交接单中的包裹，这些包裹将按照"完成即达标"规则处理
+
+### 4. 最终SELECT的关键指标
+
+#### 考核通过总数
+```
+= 16点前高标签率通过 + 16点后高标签率通过 + 低标签率通过
+```
+
+#### 24小时换单率（修正）
+```
+分子 = 考核通过总数（实际完成并通过考核的包裹）
+分母 = 高标签率应该换单数（应该在高标签率下履约的包裹）
+```
+
+**含义**：客观反映在标签率≥80%情况下的实际履约完成情况
+
+---
+
+## 验证场景示例
+
+### 100个订单在同一交接单中
+
+**时间线**：
+- 最早扫描时间 = 2026-05-16 10:00:00
+
+**标签推送分布**：
+| 推送时间 | 包裹数 | 与最早扫描时间的关系 | 属性 |
+|---------|-------|------------------|------|
+| 09:00-10:00 | 30 | 扫描时间 > 推送时间 | 高标签率包裹 |
+| 10:00-11:00 | 50 | 扫描时间 = 推送时间 | 低标签率包裹 |
+| 11:00-12:00 | 20 | 扫描时间 < 推送时间 | 低标签率包裹 |
+
+**冻结标签率计算**：
+```
+冻结标签率 = (最早扫描时间 > 标签推送时间的包裹数) / 100
+          = (30个订单) / 100
+          = 30% < 80%
+```
+
+**考核规则应用**（整体规则）：
+```
+因为 冻结标签率 = 30% < 80%
+→ 整个交接单的100个包裹都执行"完成即达标"规则
+  （不再按照到仓时间16点前后分段）
+```
+
+**统计数据**：
+```
+高标签率应该换单数 = 0（因为冻结标签率<80%，没有符合条件的交接单）
+低标签率应该换单数 = 100（因为冻结标签率<80%，这100个包裹都在此类别）
+```
+
+**关键理解**：
+- 冻结标签率的作用：判断整个交接单是否属于"高标签率"或"低标签率"
+- 不是分别处理高低标签率的包裹，而是整体分类
+- 30个"高标签率包裹" + 70个"低标签率包裹" = 100个都按低标签率规则处理
+
+---
+
+## 文件变更清单
+
+### 修改的文件
+- ✅ `src/DAL/Repositories/LabelReplaceRepository.cs`
+  - 修改 `InterchangeUnitLabelRates` CTE（第735-765行）
+  - 新增 `DailyHighLabelRateShould` CTE（第1026-1055行）
+  - 新增 `DailyLowLabelRateShould` CTE（第1058-1089行）
+  - 修改最终SELECT的关键字段（第1114-1141行）
+
+- ✅ `src/MDL/DTOs/CustomerDailyLabelStatsDto.cs`
+  - 修正命名空间：从 `LabelReplaceServer.Models.DTOs` 改为 `MDL.DTOs`
+
+### 新增的文档
+- 📄 `.trae/documents/frozen_label_rate_design.md`
+  - 详细的冻结标签率设计文档
+  - 包含完整的业务逻辑、SQL实现、验证场景
+
+---
+
+## 编译验证
+
+✅ **DAL项目编译成功**
+- 无编译错误
+- 176条警告（既存问题，与本修改无关）
+
+✅ **CONTROLLER项目编译成功**
+- 所有依赖项编译通过
+- 系统已生成最新的DLL
+
+---
+
+## 下一步工作
+
+### 需要测试验证
+1. **冻结标签率计算准确性**
+   - 验证"最早完成时间"的确定
+   - 验证标签推送时间的比较逻辑
+
+2. **考核时间的正确性**
+   - 16点前/后的分段规则是否正确应用
+   - 完成即达标（低标签率）的场景
+
+3. **统计指标的合理性**
+   - 验证不再出现"成功数 < 考核通过数"
+   - 验证24小时换单率分母的正确性
+   - 验证各项汇总数据的一致性
+
+4. **数据对比**
+   - 与旧逻辑的数据对比
+   - 与现场实际情况的符合度
+
+### 预期改进
+- 📊 消除数据矛盾
+- 📈 更准确地反映标签供应情况
+- ✅ 实现100%的逻辑自洽性
+- 🎯 为客户提供更有说服力的数据
+
+---
+
+## 相关文档
+
+- 📄 [冻结标签率设计文档](./frozen_label_rate_design.md)
+- 📄 [考核时间设计分析](./assessment_time_design_analysis.md)
+- 📄 [SQL逻辑错误修复](./sql_logic_error_fix.md)
+