333 lines
12 KiB
Markdown
333 lines
12 KiB
Markdown
# 四站点差缺对比逻辑审查报告
|
||
|
||
> 审查日期：2026-07-31
|
||
> 审查范围：顺心、中通、韵达、安能 四个站点的应到 vs 实到差缺对比逻辑
|
||
> 排除：百世（站点直供未到明细，不参与四站比对）
|
||
|
||
---
|
||
|
||
## 一、比对算法总览（四站共用）
|
||
|
||
`compare.py:process()` 对四个站点执行**完全相同**的算法步骤。站点间的差异仅由 `domain.py:STATIONS` 配置注入——列名映射 + 实到单号解析器。
|
||
|
||
```
|
||
步骤1: 读应到Excel → 按运单号去重keep-first → 构建 {运单号 → (交接单号, 交接件数=n)}
|
||
步骤2: 读实到Excel → 站点专用解析器 → 构建 {运单基号 → {已到单号集合}}
|
||
步骤3: 逐运单比对
|
||
arrived_cnt >= n → 足额到货，跳过
|
||
arrived_cnt == 0 → 完全未到
|
||
0 < arrived < n → 部分未到
|
||
步骤4: 产出未到明细（交接单号 | 运单号 | 总件数 | 已到单号1 | 已到单号2 | ...）
|
||
```
|
||
|
||
### 核心口径
|
||
|
||
| 指标 | 口径 |
|
||
|------|------|
|
||
| 应到件数 | **交接件数**（非录单件数）；按运单号去重 keep-first |
|
||
| 实到件数 | 单号去重计数（每扫描一件=一个单号） |
|
||
| 未到件数 | max(0, 应到件数 − 实到件数) |
|
||
| 未到率 | 未到件数 ÷ 应到件数 |
|
||
|
||
### 未到明细输出约定
|
||
|
||
- 仅列出**短少运单**（实到 < 应到）
|
||
- 列出该运单**实际已到的单号**（已到单号1, 已到单号2, ...）
|
||
- **不编造缺件子单号**——实到扫描顺序号乱序，无法反推缺了哪个顺序号
|
||
|
||
### 统计指标
|
||
|
||
| 指标 | 含义 |
|
||
|------|------|
|
||
| 运单数 | 应到运单去重数 |
|
||
| 应到件 | Σ 交接件数 |
|
||
| 已到件 | Σ 实到单号去重数 |
|
||
| 未到件 | max(0, 应到件 − 已到件) |
|
||
| 涉及运单 | 存在短少的运单数 |
|
||
| 完全未到 | 整单零到货运单数 |
|
||
| 部分未到 | 部分缺件运单数 |
|
||
|
||
---
|
||
|
||
## 二、四站配置对照
|
||
|
||
`domain.py:STATIONS` — 所有差异集中于此配置表，比对核心代码不感知站点差异。
|
||
|
||
| 维度 | 中通 | 顺心 | 韵达 | 安能 |
|
||
|------|------|------|------|------|
|
||
| 应到文件 | `中通-应到货物数据.xlsx` | `顺心-应到货物数据.xlsx` | `韵达-应到货物数据.xlsx` | `安能-应到货物数据.xlsx` |
|
||
| 实到文件 | `中通-实到货物数据.xlsx` | `顺心-实到货物数据.xlsx` | `韵达-实到货物数据.xlsx` | `安能-实到货物数据.xlsx` |
|
||
| 应到-运单号列 | `运单号` | `运单号` | `运单号` | `运单号` |
|
||
| 应到-件数列 | `交接件数` | `交接件数` | `交接件数` | `交接件数` |
|
||
| 应到-交接单号列 | `交接单号` | `交接单号` | `交接单号` | `交接单号` |
|
||
| 实到-基号列 | —（从复合串推导） | `运单号` | **`主单号`** | **`所属单号`** |
|
||
| 实到-单号列 | `运单号`（复合串） | `子单号` | `子单号` | `扫描单号` |
|
||
| 解析器 | `arrived_pieces_zhongtong` | `arrived_pieces_by_cols` | `arrived_pieces_by_cols` | `arrived_pieces_by_cols` |
|
||
|
||
---
|
||
|
||
## 三、逐站点详细分析
|
||
|
||
### 3.1 中通（ZTO）
|
||
|
||
#### 业务逻辑
|
||
|
||
实到货物数据中的「运单号」为复合串，由三部分构成：
|
||
|
||
```
|
||
┌──────────┬────────────┬──────────┐
|
||
│ 运单号 │ 录单件数 │ 顺序号 │
|
||
│ (12位) │ (4位) │ (4位) │
|
||
└──────────┴────────────┴──────────┘
|
||
总长 20 位
|
||
|
||
示例: 330953527953 0001 0001
|
||
├─ 运单号 ─┤├录单┤├顺序┤
|
||
```
|
||
|
||
- **运单号(12位)**: 与应到货物数据中的运单号对齐
|
||
- **录单件数(4位)**: 该运单在系统中的录单总件数，0占位
|
||
- **顺序号(4位)**: 0占位，如 `0001`, `0002`, `0003`, `0004`
|
||
|
||
对比逻辑：
|
||
1. 从应到数据取运单号 + 交接件数（**非录单件数**）
|
||
2. 从实到数据取复合串，掐尾8位得运单基号，完整串为子运单号
|
||
3. 按运单基号分组，子运单号去重得实到件数
|
||
4. 实到件数 < 交接件数 → 差缺
|
||
|
||
> **重要**: 录单件数仅作参考。举例：某运单录单件数=4、交接件数=2，实到最多出现2条数据。如果只出现了1条，我们只知道差缺了，但**无法判断具体差缺了哪一件**（顺序号乱序）。
|
||
|
||
#### 代码实现
|
||
|
||
`domain.py:17-26` — 实到解析器：
|
||
|
||
```python
|
||
def arrived_pieces_zhongtong(df):
|
||
res = defaultdict(set)
|
||
for v in df["运单号"]:
|
||
v = str(v).strip()
|
||
if len(v) > 8 and v[-4:].isdigit():
|
||
res[v[:-8]].add(v) # 基号=前12位, 已到单号=完整20位复合串
|
||
return res
|
||
```
|
||
|
||
`domain.py:48-56` — 站点配置：
|
||
|
||
```python
|
||
{
|
||
"name": "中通",
|
||
"exp_qty": "交接件数", # 应到件数口径：交接件数（非录单件数）
|
||
"exp_wb": "运单号",
|
||
"exp_jd": "交接单号",
|
||
"arrived_pieces": arrived_pieces_zhongtong,
|
||
"columns": ["交接单号", "运单号", "总件数"],
|
||
}
|
||
```
|
||
|
||
#### 对齐情况：✅ 对齐
|
||
|
||
代码实现与业务逻辑一致。`v[:-8]` 掐尾8位得12位运单基号，保留完整复合串作为已到单号——不解析、不推断录单件数和顺序号的具体含义。
|
||
|
||
---
|
||
|
||
### 3.2 安能（Anneng）
|
||
|
||
#### 业务逻辑
|
||
|
||
与中通相同的差缺对比逻辑。
|
||
|
||
安能实到数据同样为复合串，结构：`运单号(12位) + 录单件数(4位) + 顺序号(4位)`（20位）。
|
||
|
||
与中通的关键区别：安能实到表有**独立的「所属单号」列**（干净运单基号），无需像中通那样从复合串掐尾8位推导基号。
|
||
|
||
#### 代码实现
|
||
|
||
`domain.py:76-86`：
|
||
|
||
```python
|
||
{
|
||
"name": "安能",
|
||
"arrived_pieces": arrived_pieces_by_cols("所属单号", "扫描单号"),
|
||
...
|
||
}
|
||
```
|
||
|
||
安能使用 `arrived_pieces_by_cols` 而非 `arrived_pieces_zhongtong`——直接从「所属单号」列读基号、从「扫描单号」列读完整单号，效果等价。
|
||
|
||
| 差异点 | 中通 | 安能 |
|
||
|--------|------|------|
|
||
| 实到基号来源 | 从复合串解析（`v[:-8]`） | 直接读「所属单号」列 |
|
||
| 实到单号来源 | 复合串本身（「运单号」列） | 「扫描单号」列 |
|
||
| 解析器 | `arrived_pieces_zhongtong` | `arrived_pieces_by_cols` |
|
||
| 最终产出 | `{基号 → {完整单号集合}}` | 相同 |
|
||
|
||
#### 数据库验证
|
||
|
||
```
|
||
piece_no=61003282264500140014 → waybill_no=610032822645 (12位), total=0014, seq=0014
|
||
```
|
||
|
||
#### 对齐情况：✅ 对齐
|
||
|
||
---
|
||
|
||
### 3.3 顺心（Shunxin）⚠️
|
||
|
||
#### 业务逻辑
|
||
|
||
顺心站点需区分两类运单：
|
||
|
||
**A. 非SF开头运单（占 97%）:**
|
||
|
||
实到「子单号」结构为两部分：
|
||
|
||
```
|
||
┌──────────┬──────────┐
|
||
│ 运单号 │ 顺序号 │
|
||
│ (不定长) │ (3位) │
|
||
└──────────┴──────────┘
|
||
|
||
示例: S71623721115 001
|
||
├─ 运单号 ──┤├顺序┤
|
||
|
||
注意：顺心子单号无录单件数部分（仅两部分）
|
||
```
|
||
|
||
对比时从实到取「子单号」列，按「运单号」分组，子单号去重得实到件数。
|
||
|
||
**B. SF开头运单（占 3%）:**
|
||
|
||
SF订单的「子单号」为**随机号码**（非由运单号衍生），不能用于差缺推导。
|
||
|
||
对比逻辑：
|
||
1. 在实到数据中按「运单号」字段查找，统计出现次数
|
||
2. 出现次数 < 交接件数 → 差缺
|
||
3. 将找到的子单号（虽随机但可以列出来）填入「已到单号」列
|
||
|
||
SF订单的差缺判定：**只基于交接件数与实到运单号出现次数的比较**，不依赖子单号的结构解析。
|
||
|
||
#### 代码实现
|
||
|
||
`domain.py:57-65`：
|
||
|
||
```python
|
||
{
|
||
"name": "顺心",
|
||
"arrived_pieces": arrived_pieces_by_cols("运单号", "子单号"),
|
||
}
|
||
```
|
||
|
||
**SF 与非 SF 没有任何区分处理。** 所有运单走同一条路径。
|
||
|
||
#### 数据库验证
|
||
|
||
**非SF（正常）:**
|
||
```
|
||
子单号=S71623721115001 → 运单号=S71623721115 + 后缀=001 ✅
|
||
子单号=S71934073996002 → 运单号=S71934073996 + 后缀=002 ✅
|
||
```
|
||
|
||
**SF（异常）:**
|
||
```
|
||
运单号=SF1225002296515 的两条实到记录:
|
||
子单号=SF2025318183224 (随机SF号码)
|
||
子单号=SF1225002296515 (与运单号相同)
|
||
```
|
||
数据中有 10 个SF运单存在多条实到记录。
|
||
|
||
#### 对齐情况：⚠️ 部分对齐，SF特殊逻辑缺失
|
||
|
||
| 检查项 | 代码现状 | 业务要求 |
|
||
|--------|----------|----------|
|
||
| 非SF处理 | ✅ `arrived_pieces_by_cols("运单号", "子单号")` | 一致 |
|
||
| 非SF子单号结构 | ✅ 运单号 + 顺序号（两部分） | 一致 |
|
||
| SF处理 | ❌ 与非SF完全一致，使用子单号去重 | **不能**使用子单号，只按运单号行数计数 |
|
||
| 功能影响 | 子单号虽随机但值唯一，按目前逻辑也能正确去重计数 | 但语义不正确——SF子单号不由运单号衍生 |
|
||
|
||
---
|
||
|
||
### 3.4 韵达（Yunda）❌
|
||
|
||
#### 业务逻辑
|
||
|
||
**去重规则:** 韵达实到数据存在重复行（同一子单号出现两次）。去重依据为「交接单号」字段：
|
||
- **保留**交接单号为**空**的行
|
||
- **丢弃**交接单号**非空**的行
|
||
|
||
**子单号结构:** 两部分——单号 + 顺序号（无录单件数部分）。
|
||
|
||
```
|
||
┌──────────┬──────────┐
|
||
│ 主单号 │ 顺序号 │
|
||
│ (不定长) │ (4位) │
|
||
└──────────┴──────────┘
|
||
|
||
示例: 713326603 0003
|
||
├─主单号─┤├顺序┤
|
||
```
|
||
|
||
**对比方式:** 与中通/安能同——按「主单号」分组，「子单号」去重得实到件数，与交接件数比对。
|
||
|
||
#### 代码实现
|
||
|
||
`store.py:316-320`（入库过滤）:
|
||
|
||
```python
|
||
if site == "韵达":
|
||
# 韵达业务清洗：抛弃「交接单号」为空的行（派件/签收等其他扫描无交接单号），
|
||
# 再按子单号去重（一件多扫只留一条；清洗后子单号已天然唯一，drop 为保险）。
|
||
df = df[df["交接单号"].astype(str).str.strip() != ""] # ← 保留非空
|
||
df = df.drop_duplicates(subset=[cm["piece"]], keep="last")
|
||
```
|
||
|
||
`domain.py:67-75`（比对配置）:
|
||
|
||
```python
|
||
{
|
||
"name": "韵达",
|
||
"exp_wb": "运单号",
|
||
"arrived_pieces": arrived_pieces_by_cols("主单号", "子单号"),
|
||
}
|
||
```
|
||
|
||
#### 对齐情况：❌ 交接单号过滤逻辑完全相反
|
||
|
||
| 检查项 | 代码现状 | 业务要求 |
|
||
|--------|----------|----------|
|
||
| 交接单号过滤 | 保留 `!= ""`（**非空**） | 保留 `== ""`（**空**） |
|
||
| 子单号结构 | ✅ `7133266030003` = wb`713326603` + seq`0003` | 一致 |
|
||
| 实到解析 | ✅ `arrived_pieces_by_cols("主单号", "子单号")` | 一致 |
|
||
| compare.py 过滤 | ❌ **无过滤**，所有行参与比对 | 需要过滤 |
|
||
|
||
**影响分析:**
|
||
|
||
1. `store.py` 过滤反了——入库时留下了错误的数据集
|
||
2. `compare.py` 完全没有交接单号过滤——如果原始 Excel 中同时存在空和非空行，比对阶段会全部读入导致重复计数
|
||
3. 当前数据库中韵达 3483 条记录全部为非空交接单号——说明当前 Excel 数据中空交接单号行偏少或不存在，但这不改变逻辑错误
|
||
|
||
---
|
||
|
||
## 四、差异汇总
|
||
|
||
| # | 站点 | 问题 | 严重程度 | 影响范围 |
|
||
|---|------|------|----------|----------|
|
||
| 1 | **韵达** | 交接单号过滤反了：`!= ""` 应改为 `== ""` | ❌ 严重 | `store.py:319` + `compare.py` 需新增过滤 |
|
||
| 2 | **顺心** | SF运单无特殊处理，与非SF混用子单号 | ⚠️ 中等 | `domain.py` 需新增SF判断分支 |
|
||
| 3 | **中通** | 录单件数0占位描述与实际数据完全一致 | ✅ 无影响 | 代码不依赖此区分 |
|
||
|
||
---
|
||
|
||
## 五、代码位置索引
|
||
|
||
| 逻辑 | 文件 | 行号 |
|
||
|------|------|------|
|
||
| 单站比对 `process()` | `compare.py` | 61-143 |
|
||
| 站点配置 `STATIONS` | `domain.py` | 46-87 |
|
||
| 中通实到解析器 | `domain.py` | 17-26 |
|
||
| 通用实到解析器 | `domain.py` | 29-42 |
|
||
| 单站未到文件写入 | `compare.py` | 258-273 |
|
||
| 全量汇总报告 | `compare.py` | 293-324 |
|
||
| 未到触发编排 | `runtime.py` | 478-497 |
|
||
| 韵达入库过滤（需修） | `store.py` | 316-320 |
|
||
| 顺心实到配置（需修） | `domain.py` | 57-65 |
|