f61f52bcbe
Update README tree (compare.py + domain.py), CLAUDE.md module refs, and the three docs/ deep-dives to the current inbound_verify package (compare/domain/sites/cli). Correct the statistics review report's methodology to the current 口径 (应到=交接件数, 实到=直接数单号去重, 未到=应到−实到) per compare.py docstring; remove ghost-script references in the CDP guide. Co-Authored-By: Claude <noreply@anthropic.com>
7.0 KiB
7.0 KiB
韵达 / 安能 应到未到计算逻辑梳理（基于 inbound_verify/compare.py 重构版代码）
用途：供审核两站「应到件数 / 实到件数 / 未到件数」的实现逻辑与关联键。 代码基准：
InboundVerify/inbound_verify/compare.py（重构版）。
〇、两站共用的计算骨架（process 函数）
无论韵达还是安能，最终都走同一个 process(name)：
- 读应到表 + 实到表（第 148–149 行）。
- 应到表按关联键列去重、保留首条（第 152–153 行）。
- 应到件数 = 应到表「交接件数」之和（第 158–168 行）。
- 实到件数 = 实到表单件号列的全局去重数（第 176–177 行，
act_pieces = sum(len(s) for s in arrived.values())）。 - 逐运单比较：实到扫到数
<应到件数 的运单，才进未到明细（第 183–201 行）。 - 未到件数 =
max(0, 应到件数 − 实到件数)（第 210 行）。
两站差异只在配置（关联键列、单件号列不同），算法完全一致。
一、韵达
1.1 配置（STATIONS 第 106–115 行）
| 配置项 | 值 | 含义 |
|---|---|---|
| exp（应到文件） | 韵达-应到货物数据.xlsx |
源 |
| act（实到文件） | 韵达-实到货物数据.xlsx |
源 |
| exp_qty | 交接件数 |
应到件数的取值列 |
| exp_wb | 运单号 |
应到表去重键 + 关联键 |
| exp_jd | 交接单号 |
未到明细展示字段 |
| arrived_pieces | arrived_pieces_by_cols("主单号", "子单号") |
实到解析 |
| ├ wb_col | 主单号（实到表） |
实到侧关联基号列 |
| └ piece_col | 子单号（实到表） |
实到侧单件号列 |
1.2 两套表的字段角色
- 应到表：
运单号（去重+关联）、交接件数（该单应到件数）、交接单号（展示）。 - 实到表：
主单号（关联基号，须与应到运单号同值域）、子单号（每件货物的单号，一个单号=一件）。
1.3 关联（Join）条件
应到表.运单号 == 实到表.主单号
机制：arrived_pieces_by_cols 以「主单号」为 key 建 dict（第 76–81 行）；process 第 185 行 arrived.get(wb) 用应到运单号 wb 去查该 dict。两列值必须相等才对得上。
1.4 计算口径
- 应到件数 = Σ 交接件数（按运单号去重后）。
- 实到件数 = 实到表「子单号」全局去重数（不同主单号下即使子单号文本相同也只计一次）。
- 未到件数 =
max(0, 应到 − 实到)。 - 未到明细（每行一个短少运单）：
交接单号 | 运单号 | 总件数(=应到件数) | 已到单号1..k； 「已到单号1..k」= 该主单号下所有子单号（排序后填入），k = 实际扫到件数（第 199–200 行）。 仅当「实到扫到数 < 应到件数」才列入（第 187–188 行arrived_cnt >= n跳过）。
1.5 当前数据状态（实测，2026-07-19 10:50）
- 应到运单数 57，实到基号数 58，交集命中 57 ✅
- 应到件数 = 140，实到单号去重 = 141
- 样本：
应到 617936212==实到主单号 617936212，完全对齐 - 结论：韵达关联键现已对齐，逻辑可正确产出结果。（此前 2/57 为旧数据，已失效）
二、安能
2.1 配置（STATIONS 第 116–125 行）
| 配置项 | 值 | 含义 |
|---|---|---|
| exp（应到文件） | 安能-应到货物数据.xlsx |
源 |
| act（实到文件） | 安能-实到货物数据.xlsx |
源 |
| exp_qty | 交接件数 |
应到件数取值列 |
| exp_wb | 运单号 |
应到表去重键 + 关联键 |
| exp_jd | 交接单号 |
未到明细展示字段 |
| arrived_pieces | arrived_pieces_by_cols("所属单号", "扫描单号") |
实到解析 |
| ├ wb_col | 所属单号（实到表） |
实到侧关联基号列 |
| └ piece_col | 扫描单号（实到表） |
实到侧单件号列 |
2.2 两套表的字段角色
- 应到表：
运单号（去重+关联）、交接件数（应到件数）、交接单号（展示）。 - 实到表：
所属单号（关联基号，须与应到运单号同值域）、扫描单号（每件单号，格式=所属单号+总数4位+顺序4位，一个=一件）。
2.3 关联（Join）条件
应到表.运单号 == 实到表.所属单号
机制同韵达：arrived_pieces_by_cols 以「所属单号」建 key dict；process 用应到运单号去查。
2.4 计算口径（与韵达结构完全一致）
- 应到件数 = Σ 交接件数。
- 实到件数 = 实到表「扫描单号」全局去重数。
- 未到件数 =
max(0, 应到 − 实到)。 - 未到明细：
交接单号 | 运单号 | 总件数 | 已到单号1..k（k=该所属单号下扫描单号数）。
2.5 当前数据状态（实测，2026-07-19 10:50）
- 应到运单数 97，实到基号数 140，交集命中 4 ❌
- 应到件数 = 236，实到单号去重 = 279
- 样本：
应到 750101236894vs实到所属单号 760237639793—— 两套不同编号体系 - 后果：实到 279 件几乎全无法对应到任何应到运单 → 明细把 93 个运单列「完全未到」，但汇总层
实到=279 > 应到=236→ 未到净额被max(0,…)截断为 0，于是「明细列 96 行短少」与「汇总未到=0」自相矛盾。 - 结论：安能关联键未对齐，当前产出不可信。
三、两站逻辑差异对照
| 维度 | 韵达 | 安能 |
|---|---|---|
| 应到关联键列 | 运单号 |
运单号 |
| 实到关联基号列 | 主单号 |
所属单号 |
| 实到单件号列 | 子单号 |
扫描单号 |
| 单件号是否带后缀 | 是（主单号+顺序号） | 是（所属单号+总数+顺序） |
| 关联键是否对齐（当前数据） | ✅ 57/57 | ❌ 4/97 |
| 计算结果是否可信 | 可信 | 不可信（自相矛盾） |
两站算法完全相同，唯一区别是实到侧的「基号列 / 单件号列」列名不同。因此问题不在代码逻辑，而在安能的关联键取值域对不上。
四、审核要点（请你判断）
- 韵达：关联键
应到.运单号 == 实到.主单号是否符合业务实际？当前数据已对齐，似乎正确；若你确认，韵达逻辑可定稿。 - 安能：关联键
应到.运单号 == 实到.所属单号是否正确？实测两套编号不重合（97 个应到运单仅 4 个能在实到找到）。可能的方向：- (a) 实到表存在另一列能与应到
运单号对应（需确认列名，可能改wb_col）； - (b) 应到/实到文件是按不同条件/批次拉的，需要按同一天、同线路重新拉取；
- (c) 暂时把安能排除（同百世），等数据对齐再加回。
- (a) 实到表存在另一列能与应到
- 共同结构问题：汇总「未到件数」用净额
max(0, 应到−实到)，而明细按「逐运单短少」列——当关联键断裂时二者会矛盾（安能现例）。关联键对齐后此矛盾自然消失；是否需要在代码里对「净额 vs 明细」做一致性校验/告警，也请你定。