上传源代码版本

2026-06-01 16:30:29 +08:00
commit b2a9b7d3c2
462 changed files with 104365 additions and 0 deletions
--- a/.trae/documents/frozen_label_rate_logic_clarification_v3.md
+++ b/.trae/documents/frozen_label_rate_logic_clarification_v3.md
@@ -0,0 +1,206 @@
+# 冻结标签率设计核心逻辑修正 - v3.0
+
+**更新日期**: 2026-05-16  
+**版本**: v3.0 - 关键考核规则澄清  
+**状态**: ✅ 编译通过，文档已更新
+
+---
+
+## 核心修正点
+
+### ⚠️ 发现的误区
+
+在 v2.0 中，对 `DailyHighLabelRateShould` 和 `DailyLowLabelRateShould` 两个 CTE 的理解有误。
+
+**错误理解**（v2.0）：
+- 这两个 CTE 是用来分别统计"标签推送时间与扫描时间关系"中的高/低标签率包裹数
+- 高标签率包裹单独处理，低标签率包裹单独处理
+
+**用户指正**：
+"如果冻结标签率是低于80%的，那么100个包裹都要按照完成即达标的规则处理，如果冻结标签率大于等于80%则按照到仓时间16点前后的规则处理"
+
+### ✅ 正确理解（v3.0）
+
+**冻结标签率的真实作用**：
+- 冻结标签率是对**整个交接单**的标签率水平的评估
+- 它决定了**这个交接单中的所有包裹**应该按什么规则处理
+- **不是分别处理包裹，而是整体规则应用**
+
+**考核规则的应用逻辑**：
+
+```
+IF 冻结标签率 >= 80% THEN
+    ├─ 所有包裹都按照"到仓时间16点前后分段"规则处理
+    └─ 高标签率应该换单数 += 这个交接单的全部包裹数
+ELSE IF 冻结标签率 < 80% THEN
+    ├─ 所有包裹都按照"完成即达标"规则处理
+    └─ 低标签率应该换单数 += 这个交接单的全部包裹数
+```
+
+---
+
+## 代码修正
+
+### DailyHighLabelRateShould CTE 修正
+
+**v2.0（错误）**：
+```sql
+WHERE earliest_times.earliest_scan_time > lrr.LabelRetrievedAt
+-- 这样是在分别统计包裹，而不是统计交接单
+```
+
+**v3.0（正确）**：
+```sql
+FROM ArrivalRequests ar
+INNER JOIN (
+    SELECT DISTINCT BillOfLadingNumber, MasterPackageNumber
+    FROM InterchangeUnitLabelRates
+    WHERE label_rate_percent >= 80
+) high_label_units ON ...
+-- 统计所有冻结标签率 >= 80% 的交接单中的全部包裹数
+```
+
+### DailyLowLabelRateShould CTE 修正
+
+**v2.0（错误）**：
+```sql
+WHERE earliest_times.earliest_scan_time <= lrr.LabelRetrievedAt
+-- 这样是在分别统计包裹，而不是统计交接单
+```
+
+**v3.0（正确）**：
+```sql
+FROM ArrivalRequests ar
+INNER JOIN (
+    SELECT DISTINCT BillOfLadingNumber, MasterPackageNumber
+    FROM InterchangeUnitLabelRates
+    WHERE label_rate_percent < 80
+) low_label_units ON ...
+-- 统计所有冻结标签率 < 80% 的交接单中的全部包裹数
+```
+
+---
+
+## 逻辑对比示例
+
+### 场景：100个订单在同一交接单
+
+**标签分布**：
+- 30个订单：标签推送于09:00-10:00（早于作业开始）
+- 50个订单：标签推送于10:00-11:00（同时作业开始）
+- 20个订单：标签推送于11:00-12:00（晚于作业开始）
+
+**冻结标签率**：`30/100 = 30%`
+
+### v2.0 的错误理解
+
+```
+高标签率应该换单数 = 30（推送时间 > 扫描时间的包裹）
+低标签率应该换单数 = 70（推送时间 <= 扫描时间的包裹）
+
+那么：
+- 30个包裹按高标签率规则处理（16点分段）
+- 70个包裹按低标签率规则处理（完成即达标）
+❌ 这样导致同一个交接单的包裹按不同规则处理！
+```
+
+### v3.0 的正确理解
+
+```
+冻结标签率 = 30% < 80%
+→ 整个交接单（所有100个包裹）都按低标签率规则处理（完成即达标）
+
+因此：
+高标签率应该换单数 = 0（没有标签率≥80%的交接单）
+低标签率应该换单数 = 100（整个交接单都按此规则处理）
+✅ 这样才符合业务逻辑：同一个交接单的包裹按相同规则处理
+```
+
+---
+
+## 关键原理
+
+### 为什么要用冻结标签率作为整体判断标准？
+
+1. **交接单是最小的考核单位**
+   - 每个交接单都有一个统一的标签率水平
+   - 不应该在同一个交接单内混合使用不同的考核规则
+
+2. **标签率会随时间变化**
+   - 某时刻的标签率可能低于80%，之后又升高
+   - 冻结标签率通过"最早扫描时间"这一关键时刻点来定位
+   - 代表"作业刚开始时的标签率情况"
+
+3. **现场实际情况**
+   - 作业人员在作业开始时面对的是一个固定的标签率
+   - 这个"时刻的标签率"决定了他们的考核规则
+   - 不会在作业过程中动态改变规则
+
+### InterchangeUnitLabelRates 的双重用途
+
+| 用途 | 含义 |
+|------|------|
+| 计算 `label_rate_percent` | 判断该交接单属于高还是低标签率 |
+| 用于分类 | 通过 ≥80% 或 <80% 来分类全部交接单 |
+
+---
+
+## 文件变更
+
+### 代码修改
+- ✅ `src/DAL/Repositories/LabelReplaceRepository.cs`
+  - DailyHighLabelRateShould CTE（第1048-1066行）
+  - DailyLowLabelRateShould CTE（第1069-1083行）
+  - 逻辑：从"分别统计包裹"改为"统计交接单中的全部包裹"
+
+### 文档更新
+- ✅ `frozen_label_rate_design.md`
+  - 设计逻辑第三步：完全重写，强调整体规则应用
+  - 验证场景：示例已更新
+  - 字段映射：说明已澄清
+
+- ✅ `frozen_label_rate_implementation_summary.md`
+  - DailyHighLabelRateShould 和 DailyLowLabelRateShould 功能说明
+  - 验证场景示例已更新
+
+---
+
+## 编译状态
+
+✅ **编译成功**
+- 命令：`dotnet build src/DAL/DAL.csproj --no-restore -v quiet`
+- 结果：exit code 0
+- 无编译错误
+
+---
+
+## 重要总结
+
+### 冻结标签率的三层含义
+
+| 层级 | 含义 | 用途 |
+|------|------|------|
+| 第1层 | 度量 | 测量特定时刻的标签率水平 |
+| 第2层 | 分类 | 将交接单分为两类（≥80% 或 <80%） |
+| 第3层 | 规则 | 决定整个交接单按什么考核规则处理 |
+
+### 核心原则
+
+✅ **DO**：
+- 计算每个交接单的冻结标签率
+- 根据冻结标签率对交接单分类
+- 同一交接单内的所有包裹按相同规则处理
+
+❌ **DON'T**：
+- 在同一交接单内混合使用不同考核规则
+- 对单个包裹分别应用高/低标签率规则
+- 将包裹的"标签状态"与"整体考核规则"混淆
+
+---
+
+## 后续验证
+
+1. ✅ 编译成功
+2. 在测试环境中验证新逻辑
+3. 对比新旧数据结果
+4. 验证"成功数 < 考核通过数"的矛盾是否消除