100 lines
4.7 KiB
Markdown
100 lines
4.7 KiB
Markdown
# 实到按「归属日当天扫描」提取修正 · 设计方案
|
||
|
||
> 日期：2026-08-04
|
||
> 分支：`refactor/undelivered-by-expected`
|
||
> 状态：待审核
|
||
> 目标：把差缺对比中的「实到货物数据」提取口径修正为「目标归属日当天实际扫描」，与业务口径对齐
|
||
|
||
---
|
||
|
||
## 一、业务口径（与业务部门对齐后的最终陈述）
|
||
|
||
差缺对比在**归属日期（业务日期）D** 这一维度上进行：
|
||
|
||
1. **应到货物数据**：取**归属日 = D** 的应到批次（批次归属日 = 出库大头日，已实现为 `expected_record.batch_out_date`）。
|
||
- 站点"提前下载"（韵达固定提前 1 天、个别站点偶发提前 1~2 天）不影响取数——提前提交的批次按其**出库日**自动归属到 D 日。
|
||
2. **实到货物数据**：取 **D 日当天实际扫描**的记录（`actual_record.scan_time::date = D`）。
|
||
- "当天实际扫描"指扫描行为发生在 D 日，与运单属于哪个批次无关。
|
||
3. 对取到的双方数据按运单号进行差缺对比。
|
||
|
||
**关键原则**：说"同一天"指的是**归属日期**，不是数据产生/下载的日期。
|
||
|
||
---
|
||
|
||
## 二、现状问题
|
||
|
||
| 环节 | 现状 | 问题 |
|
||
|------|------|------|
|
||
| 应到提取 | `WHERE batch_out_date = D`（应到驱动入口） | ✅ 已对齐 |
|
||
| 实到提取 | `WHERE waybill_no = ANY(批次运单)`，**无扫描日过滤** | ❌ 跨日扫描混入 |
|
||
|
||
**实证案例（安能 08-03）**：
|
||
- 08-03 实到下载文件 = 355 行，全部扫描于 08-03（获取层正确）；
|
||
- 今天 15:03 另有一次 08-04 实到下载（176 行），其中 **6 件扫描于 08-04、运单属于 08-03 批次**；
|
||
- 对比 SQL 按运单号取实到 → 08-03 实到 = 350（当天）+ 6（次日）= **356**，与"当天实际扫描"定义不符。
|
||
|
||
根因：`db_compare.py` 三处取实到的 SQL 只按运单号匹配，未按扫描日过滤。
|
||
|
||
---
|
||
|
||
## 三、修正方案
|
||
|
||
### 3.1 实到提取统一加扫描日过滤
|
||
|
||
| 函数 | 用途 | 改动 |
|
||
|------|------|------|
|
||
| `compare_site_outdate` | 汇总报表（应到驱动，主入口） | 实到 SQL 增加 `AND scan_time::date = %s`（D） |
|
||
| `compare_site_date` | 实到驱动对照模式 | 同上加过滤（Step 4；Step 1 锚点本已按当天扫描） |
|
||
| `compare_site_batch` | 单批次审计（无日期语境） | **保持全量**，docstring 注明"全批次全量实到，不受日期过滤" |
|
||
|
||
修正后统计口径：
|
||
|
||
```
|
||
应到 = 归属日 D 的批次全量应到（交接件数，不变）
|
||
实到 = 批次运单 ∩ 扫描日 = D 的扫描件数（非 SF 子单号去重 / SF 行计数，不变）
|
||
未到 = max(0, 应到 − 实到)
|
||
```
|
||
|
||
### 3.2 边界语义确认
|
||
|
||
| 场景 | 修正后行为 |
|
||
|------|-----------|
|
||
| 批次 D 的件扫描于 D+1（迟到件） | 不计入 D 日实到 → D 日计"未到"；该件属 D+1 日实到（其运单若在 D+1 批次内则正常核销） |
|
||
| 批次 D 的件提前扫描于 D−1 | 不计入 D 日实到 |
|
||
| 当天扫描但运单不在 D 日应到批次（孤儿） | 不入 D 日比对（属其他归属日批次，与现状一致） |
|
||
| 一件多扫（同日） | 非 SF 按子单号去重，SF 行计数（不变） |
|
||
|
||
### 3.3 不做的事（范围外）
|
||
|
||
- 下载层各站查询日期口径已验证正确（08-03 四站文件 100% 当天扫描），**不改下载层**。
|
||
- 获取层"日期回读校验"（韵达/中通/顺心选完日期后未校验输入框值）另立改进项，不阻塞本次。
|
||
- 百世为站级日聚合（已扫/应扫，固定当天），不涉及。
|
||
|
||
---
|
||
|
||
## 四、涉及改动清单
|
||
|
||
| 文件 | 改动 |
|
||
|------|------|
|
||
| `inbound_verify/db_compare.py` | `compare_site_outdate`、`compare_site_date` 两处实到 SQL 加 `AND scan_time::date = %s`；`compare_site_batch` docstring 注明口径 |
|
||
|
||
仅此一处文件、两处 SQL + 一处注释。
|
||
|
||
---
|
||
|
||
## 五、验证计划
|
||
|
||
1. **重跑 08-03 全站汇总**（`build_full_report("2026-08-03")`），核对：
|
||
- 安能实到 356 → **350**（= 355 当天 − 5 孤儿，或 350 匹配批次），未到件数相应变化；
|
||
- 顺心 / 中通 / 韵达先实查 DB 中是否有跨日扫描匹配各自 08-03 批次，预期无变化（各自文件全为 08-03 扫描）。
|
||
2. **明细抽查**：差缺明细表内各运单的"已到单号"扫描日全部 = 08-03。
|
||
3. **口径复核**：安能 6 件 08-04 扫描确认不再出现在 08-03 报表实到/已到明细中。
|
||
|
||
---
|
||
|
||
## 六、决策记录（待确认）
|
||
|
||
- ✅ 实到 = 归属日当天实际扫描（`scan_time::date = D`），跨日扫描不计入。
|
||
- ✅ `compare_site_batch` 保持全批次全量（审计工具语义，不按日过滤）。
|
||
- ⏳ 其余边界（迟到件计"未到"的呈现、获取层日期回读校验）按上表执行，如有异议请指出。
|