InboundVerify/docs/2026-08-02-未到差缺统计逻辑现状梳理.md

未到（差缺）统计逻辑现状梳理

梳理日期：2026-08-02 分支：refactor/undelivered-by-expected 范围：顺心、中通、韵达、安能四站的"应到 / 实到 / 差缺"统计链路（百世为站点直供未到，单独处理） 目的：固定当前真实逻辑，为"改为基于应到数据统计差缺"的重构提供基线

---

一、系统总览与数据流

系统分三层：

1. 下载层（inbound_verify/sites/*.py）：用 Playwright / CDP 登录各物流站点，按目标日期导出「应到货物数据」「实到货物数据」Excel 到 downloads/。
2. 持久化层（store.py + PostgreSQL）：把 Excel 幂等 UPSERT 进 expected_record（应到，运单级）/ actual_record（实到，扫描件级）/ undelivered_record（百世直供未到，子单级）/ baishi_daily_stats（百世日聚合基数）。
3. 统计层（db_compare.py）：直接查 PostgreSQL，以实到扫描日期为锚点反推交接批次，展开批次全量应到后逐运单比对，产出差缺统计与明细，落盘 output/ 下 Excel，供前端下载。

flowchart LR
    subgraph 下载层["下载层 sites/*.py"]
        A1[定时任务<br/>fetch_schedule] --> D[Playwright/CDP 登录站点]
        A2[手动任务<br/>POST /tasks] --> D
        D --> E1[应到货物数据.xlsx]
        D --> E2[实到货物数据.xlsx]
    end

    subgraph 持久化层["持久化层 store.py + PG"]
        E1 --> F[ingest_task<br/>expected_record]
        E2 --> G[ingest_task<br/>actual_record]
    end

    subgraph 统计层["统计层 db_compare.py"]
        F --> H[compare_site_date<br/>实到锚点→反推批次→展开应到]
        G --> H
        H --> I[output/*-未到数据.xlsx]
        H --> J[output/应到未到数据.xlsx<br/>全站汇总]
    end

    I --> K[前端下载]
    J --> K

---

二、数据模型

2.1 PostgreSQL 业务表（schema.sql）

表	粒度	业务唯一键	关键列
expected_record	运单级，一运单一行	(site, waybill_no)	handover_no、handover_pieces（交接件数=应到口径）、order_pieces（录单件数）、business_date（属性，非唯一键）、raw JSONB
actual_record	扫描件级，一扫描一行	(site, piece_no)	waybill_no（运单基号）、piece_no（扫描/子单号）、scan_time、scan_site
undelivered_record	百世直供未到明细，子单级	(site, piece_no)	biz_type、last_scan
baishi_daily_stats	百世站级日聚合	(site, business_date)	expected_pieces（应扫）、arrived_pieces（已扫）、undelivered_pieces（未扫）

索引：expected_record 有 (site, business_date) 与 (site, handover_no) 索引；actual_record 有 (site, waybill_no) 与 (scan_time) 索引——差缺比对的主查询路径均命中。

2.2 SQLite 状态库（state.db）

• site_config：各站 expected_offset / actual_offset（0=今天，最大回溯 30 天）。
• fetch_schedule：周期抓取开关、激活时段、间隔（分钟）。
• task_history：任务记录（trigger、target_date、force）。
• ingest_state：最近一次入库健康状态（ok / count / error）。
• site_status：登录态 + 各 kind 的 *_ready 与 *_business_date（由 PG 派生，见 §4.4）。

---

三、当前差缺统计算法（核心）

3.1 一句话概括

以目标日期的实到扫描为锚点 → 反推这些运单所属的交接批次 → 展开批次全量应到 → 逐运单比对差缺。

即：先有实到，再找应到。这是本次重构要推翻的核心假设。

3.2 算法步骤（db_compare.compare_site_date）

flowchart TD
    S[compare_site_date site, target_date] --> S1
    S1["Step1 实到锚点<br/>SELECT DISTINCT waybill_no<br/>FROM actual_record<br/>WHERE site=? AND scan_time::date = target_date"]
    S1 -->|当天无实到| X[返回 None<br/>“当天无实到数据，无法比对”]
    S1 -->|有实到运单| S2
    S2["Step2 反推交接批次<br/>SELECT DISTINCT handover_no<br/>FROM expected_record<br/>WHERE waybill_no = ANY(锚点运单)"]
    S2 --> S3
    S3["Step3 展开批次全量应到<br/>SELECT waybill_no, handover_no, handover_pieces<br/>FROM expected_record<br/>WHERE handover_no = ANY(批次)"]
    S3 -->|无应到| X2[返回 None]
    S3 --> S4
    S4["Step4 取批次全量实到<br/>SELECT waybill_no, piece_no<br/>FROM actual_record<br/>WHERE waybill_no = ANY(展开的全部运单)"]
    S4 --> S5
    S5["Step5 逐运单比对 _do_compare"]
    S5 --> R[CompareResult<br/>stats + 差缺明细 rows]

3.3 逐运单比对口径（_do_compare）

对展开出的每一条应到运单：

判断	结论
handover_pieces <= 0	跳过，不计入应到
实到件数 >= 应到件数（handover_pieces）	足额到货（含溢到），不进差缺
实到件数 == 0	完全未到（full_miss++）
0 < 实到件数 < 应到件数	部分未到（part_miss++）

实到件数口径（SF / 非 SF 分支）：

• 非 SF（中通/韵达/安能）：COUNT(DISTINCT piece_no)，子单号去重。
• 顺心 SF 运单（waybill_no 以 SF 开头）：COUNT(*) 行计数，不去重（SF 子单号为随机号码，不能去重计数）。

3.4 统计指标定义（CompareStats）

指标	定义
waybill_count	应到运单数（handover_pieces>0 的展开运单）
expected_pieces	Σ handover_pieces（交接件数，非录单件数）
arrived_pieces	Σ 各运单实到件数（按上节口径）
undelivered_pieces	max(0, expected_pieces − arrived_pieces)
undelivered_wb	full_miss + part_miss（差缺运单数）
full_miss / part_miss	完全未到 / 部分未到运单数
sf_wb_count / sf_undelivered	顺心 SF 运单总数 / 其中差缺数

3.5 差缺明细（UndeliveredRow）

仅含短少运单：交接单号 | 运单号 | 总件数(交接件数) | 已到单号1 | 已到单号2 | ...。已到单号按实到记录顺序列出，不编造缺件子单号（扫描顺序号乱序，无法反推缺了哪个）。

3.6 另一个入口：按批次比对（compare_site_batch）

已知交接单号时可直接按 handover_no 精确比对，不依赖实到锚点。展开该批次全量应到 → 取全量实到 → 走同一 _do_compare。此入口当前未接入任务链路，主要用于调试/复核。

---

四、任务触发与执行链路

4.1 任务种类

kind	含义	四站行为	百世行为
expected	应到下载	下载应到 Excel → 入库	不支持
actual	实到下载	下载实到 Excel → 入库	不支持
undelivered	未到（差缺）	应到+实到 → 入库 → DB 比对 → 写单站未到 Excel	站点直供未到 → 入库
compare（__compare__）	全站跑比对	4 站 DB 比对 + 百世 PG → 全站汇总 Excel	同上

4.2 触发方式

• 定时：APScheduler IntervalTrigger 按 fetch_schedule 配置周期投递，激活时段内才投；任务空闲才投（create_task_if_idle）。
• 手动：POST /tasks {site, kind, force?, date?}，前端「获取未到数据」主按钮触发各站 primary kind，前端「跑比对」按钮触发 __compare__/compare。

任务执行统一走 dispatch_task（runtime.py）：登录态校验 → 调 handler → 成功后写业务日期（_record_business_date）→ 入库（_persist_to_db）。

4.3 目标日期（target_date）怎么定

state_store.resolve_target_date(site, kind, date)：

• 显式传 date → 用之（前端重试按钮会回放原 target_date）。
• 未传 → today − offset：expected 用 expected_offset、actual 用 actual_offset、四站 undelivered 跟随 expected_offset、百世恒当天。

4.4 就绪态与业务日期（ready / business_date）

• _ready_flags：直接查 PG，expected / actual 看对应 today − offset 日期是否有数据；四站 undelivered = expected ∧ actual；百世看 baishi_daily_stats 当天。
• _record_business_date：任务成功后在 SQLite 快照本次数据日期，供前端状态盘与报表「数据日期」列展示。
• 注意：expected_business_date / actual_business_date 是按偏移派生的目标日期，不是下载文件内的真实业务日期——expected_record.business_date 入库时取自状态库的 expected_business_date（store._read_business_dates），可能与交接单实际生成日不同（详见 §6 疑点）。

---

五、站点差异与配置

5.1 比对配置（db_compare.SITE_COMPARE_CONFIG）

站点	has_sf	备注
顺心	True	SF 运单走行计数
中通 / 韵达 / 安能	False	子单号去重计数

5.2 入库列映射（store.ACTUAL_COLMAP 与 domain.STATIONS）

站点	应到运单号列	实到运单基号列	实到单件列	扫描时间列
顺心	运单号	运单号	子单号	操作时间
中通	运单号	由子单号复合串 v[:-8] 推导	运单号（复合串）	扫描时间
韵达	运单号	主单号	子单号	扫描时间
安能	运单号	所属单号	扫描单号	扫描时间

5.3 入库清洗特例

• 韵达实到：只保留「交接单号为空」的行（到/接件扫描），丢弃非空行（派件/签收等重复数据）；再按子单号去重 keep-last。
• 中通实到：piece_no 为复合串 H+运单号(12)+总数(4)+顺序(4)，基号 = v[:-8]，每串计一件。

---

六、当前逻辑的特征与疑点（重构输入）

6.1 特征

1. 锚点=实到扫描日：某天实到为空 → 比对直接返回 None，不产出任何差缺（"先有实到才有结论"）。
2. 批次是反推出来的：只要当天有 1 个运单扫到，其所属整个交接批次都会被展开，把该批次的历史未到也一起统计进来（跨日旧账混入当天报表）。
3. 应到=批次全量：expected_pieces 是"被命中批次的全部应到"，不是"当天的应到交接单"；business_date 标签也可能滞后/漂移。
4. 溢到不抵消：undelivered_pieces = max(0, Σ应到 − Σ实到) 是全局差；单运单溢到（实到>应到）只会让该运单不进差缺，不会抵消他单未到。

6.2 疑点（来自 08-02 韵达实测）

• 08-02 实到 130 条/58 运单全部命中应到且件数一致，但差缺 9 单里有 7 单是 07-21 批次的历史未到——因为当天有 1 个运单（295468511）属于该批次被扫到，整批被展开。
• task_history 无记录却有 18:28 入库 130 条实到：入库链路与常规任务链路不一致（ingest_state 也未刷新），说明存在绕过任务系统的直入路径，需在重构时统一入口。

---

七、重构目标对照（待细化）

维度	现状（实到驱动）	重构方向（应到驱动）
统计起点	目标日期实到扫描运单	目标日期/批次的应到数据（expected_record）
批次来源	实到锚点反推	应到自身携带的 handover_no / business_date
无数据表现	实到空 → 不产出	应到空 → 明确"无应到"；应到有、实到空 → 全部记差缺
历史批次混入	会（1 单命中即整批展开）	应到锚定，天然按应到口径隔离
报表口径	批次全量	按应到日期/批次统计

重构后仍需保持：应到=交接件数、实到=子单号去重（SF 行计数）、未到=max(0, 应到−实到)、差缺明细含已到单号。

---

八、涉及文件清单

文件	职责
inbound_verify/db_compare.py	DB 差缺比对引擎 + 全站汇总（重构主战场）
inbound_verify/runtime.py	任务派发、未到 handler、入库钩子、就绪派生
inbound_verify/store.py	Excel → PG 入库（expected/actual/百世）
inbound_verify/state_store.py	SQLite 状态/配置/任务/偏移/目标日期
inbound_verify/domain.py	站点/文件/列映射单一配置源
inbound_verify/schema.sql	PG 表结构
inbound_verify/cli/server.py	FastAPI 端点（/tasks /compare /status /config /report）
dashboard/app/page.tsx	前端触发任务、状态盘、下载报表