# /logistics 文案↔实现一致性专项（text 专项）

**执行**: 2026-10-12 · 严格只读 · 基于当前代码（9-21 导入运单 / 9-26 KPI 实时化 / P0 附录空 ds 修复 / B批P2-4 幂等锁均已演进后版本）
**取证方式**: 代码行号 + 线上 API 实测（owner 登录，brand=空/onno 两轮）+ SQL 直算

**共核 44 处，⚠️ 9 处（实质不一致 1 处 · 措辞过时/歧义 8 处），✓ 35 处。**

---

## ⚠️ 发现（按严重度）

### ⚠️-1（实质）「历史累计 X 票」— 文案语义与实现错位

- **位置**: KPI 卡 2「累计签收」foot：`历史累计 {total} 票 · 截至 {as_of}`（page.tsx:101）
- **文案声称**: total = 历史累计发货票数
- **实际实现**: `logistics.py:160-171`（2026-09-26 B批P2-3）stats 已改为与明细同源**实时聚合**，total = `logistics_shipments` 当前**在册行数**；旧快照表 logistics_stats（total=316，真"历史累计"）已退役留档
- **实测**: API stats.total=**40**（在册 40 行，其中含 22 票未签收仍在册；历史签收快照语义下的 316 已不可见）
- **差异**: 文案说"历史累计"，实现是"当前在册总数"，且 40 ≠ 历史累计（旧口径 316）。用户读「历史累计 40 票」会以为累计只发过 40 票
- **建议**: foot 改「在册累计 {total} 票」或恢复历史口径

### ⚠️-2（过时）「本快照 X 票在册」— "快照"措辞残留

- **位置**: KPI 卡 3「阶段超时」foot（page.tsx:107）
- **实际实现**: by_badge 实时 GROUP BY 求和（logistics.py:172-176），无快照概念；快照表 9-26 起退役
- **实测**: 全品牌 foot=40（在册 ✓），值本身正确，仅"本快照"三字过时

### ⚠️-3（过时）底注「数据源：物流渠道快照」

- **位置**: page.tsx:243 Tracking 卡底注
- **实际实现**: 9-21 起同卡片上方已有「⬆ 导入运单」CSV 手动导入入口（logistics.py:72-139），KPI 已实时——"快照"描述不再完整；「采集管道接入后自动刷新」仍真（燕文 API 凭据未到位，import 端点注释自证）

### ⚠️-4（歧义）KPI 卡 1 label「在途 / 待起运」— 值单口径

- **位置**: page.tsx:94-96
- **实际实现**: k-value 只取 stats.transit（badge='TRANSIT'=17）；"待起运"(awaiting=2)、"清关中"(customs=1) 只在 foot 拆出
- **实测**: transit=17/awaiting=2/customs=1，foot 数值本身一致 ✓；仅 label 双口径 vs 值单口径的歧义

### ⚠️-5（不精确）「阶段超时 = 超过货代时效节点」— 未写明实际规则

- **位置**: page.tsx:244 底注
- **实际实现**: 两套口径并存——①表格「超时」徽章与 KPI 用 DB 列 `stage_overdue`（种子预置）；②抽屉 14 段 stepper「超期」= 前端固定 **>7 自然日未推进且未签收，运输中豁免**（logiSteps.ts:42 `OVERDUE_DAYS=7`, :95）
- **实测**: 当前数据两口径不冲突（DB overdue 3 行 CSS30129488/CSS30101146/CSA30021417 均停在"已离港"超 7 天，前端规则同样判超期），但文案未提"7 天"具体规则

### ⚠️-6（缺漏）底注状态流漏「待离港」

- **位置**: page.tsx:244「状态：已收件 → 运输中 → 清关中 → 已签收」
- **实际实现**: badge 全集 = INF/TRANSIT/CUSTOMS/**AWAITING**/DELIVERED 五态；实测 AWAITING 在册 2 票（CSS30191189/CSS30191180），文案四态漏一

### ⚠️-7（双叫法）筛选按钮「待起运」vs 徽章「Awaiting Departure 待离港」

- **位置**: page.tsx:28（BADGES）vs badge_label（DB）
- **实际实现**: 同一 badge=AWAITING，筛选按钮叫"待起运"，行内徽章显示"待离港"，两处叫法不统一

### ⚠️-8（不精确）Pricing 副标题「{265} 国家」

- **位置**: page.tsx:611「…· {Object.keys(data.codes).length} 国家」
- **实测**: codes 字典 = 265 键，其中含 7 个非国家码（`NULL`/`YT_n`/`YT_n1`/`MS_1`/`SRB`/`MNE`/`SGS`，api/data/yamwen_pricing.json 直查）；实为"报价字典代码数"，ISO 国家码上限 249
- **建议**: 措辞改「{n} 国家/地区代码」

### ⚠️-9（易误读）VAT 表列头「VAT税率 / 无IOSS税率」无单位提示

- **位置**: page.tsx:684 REF_COLS.vat
- **实测**: 数据为小数比例（奥地利 vat=0.2、no_ioss=0.22，=20%/22%）；列头无 % 或"小数"说明，0.2 易被误读为 0.2%

---

## ✓ 通过项（35 处，摘列关键证据）

| 位置 | 文案 | 实现证据 | 一致? |
|------|------|----------|-------|
| 表 h2 | 「在册船票 · 按发货日期倒序 · 超时优先」 | logistics.py:185 `ORDER BY stage_overdue DESC, ship_date DESC`（超时第一级✓日期倒序第二级✓） | ✓ |
| 列头×8 | 产品名/型号 · AWB提单号 · 路线 · 重量kg · 发货日 · 状态 · 载货 · 最新轨迹 | SELECT 列一一对应（logistics.py:179-183）；weight 为 numeric kg，toFixed(1) ✓ | ✓ |
| 搜索 placeholder | 「搜索 AWB / 备注 / 产品 / 城市」 | logistics.py:151-153 ILIKE 六字段（超集，"产品"涵盖产品名/型号） | ✓ |
| 分页 | 「共 X 行 · 第 Y/Z 页」 | total=40, pages=ceil(40/20)=2 实测吻合 | ✓ |
| 导入 tooltip | 「列名中英文均可…按 运单号+品牌 幂等去重」 | `_SHIP_COL_MAP` 中英别名（logistics.py:36-53）+ `ON CONFLICT (brand, awb)`（:124） | ✓ |
| 抽屉 | 「全流程节点…状态机口径同旧系统」 | logiSteps.ts:1 注释"移植自旧系统 logistics_data.py 的权威映射表" | ✓ |
| 抽屉 | 「原始轨迹（新→旧）」 | page.tsx:226 sort time desc | ✓ |
| Create h2 | 「选产品 + 数量 → 调 Vnlin B2B 下单」 | POST /api/logistics/create → oms.vnlin.com doubleClearance 两步（logistics.py:455-482） | ✓ |
| Create 汇总条 | 「HS … · 申报 $ {value} · 合计 $」 | 前端 product.value*qty 与 API box_body price/totalAmount 同源（:474-475） | ✓ |
| Create 重量 | `{weight} kg` = weight×qty | API `round(weight*qty,2)`（:425）同公式 | ✓ |
| Create 警示 | 「真实下单会调 Vnlin OMS 外部 API…谨慎点击」 | 属实；另有 10 分钟幂等锁（:449-454，文案未提，非不一致） | ✓ |
| Params h2 | 「下单时自动套用, 可被 Create 表单覆盖」 | create 端点合并 saved params + 地址覆盖（:394-415） | ✓ |
| Params「默认地址」单选 | 勾一剔余 | page.tsx:423-425 `is_default: j===i && checked` | ✓ |
| 计算器 hint | 「体积重=长×宽×高÷泡比 · 计费重=max(实重,体积重) · 全渠道比价」 | page.tsx:491-493 `vol=l*w*h*qty/divisor; charged0=max(actual,vol)`；遍历全 106 渠道 | ✓ |
| 计算器列头 | 数量/长L cm/宽W cm/高H cm/实重 kg/件/体积重/行 | 输入字段与每行 `l*w*h*qty/divisor` 一致（:540） | ✓ |
| 结果列头 | 「计费重 Charged kg」「渠道运费 Freight (¥)」 | A: `max(charged0,min_kg)×per_kg+fee`；B: `first+续重+fee+trunk×charged0`（:503-509）；¥=人民币（燕文深圳报价源） | ✓ |
| 计算器脚注 | 「最低 ¥X（绿色高亮）」 | 按运费升序取首行 + ok-soft 底色（:513,554） | ✓ |
| 报价表 A 列头 | 重量段/公斤运费¥/kg/处理费¥/件/最小计费Min(kg) | band/per_kg/fee/min_kg 字段直映（:647） | ✓ |
| 报价表 B 列头 | 首重(kg)/首重价¥/续重(kg)/续重价¥/处理费¥/干线费¥/kg | first_wt/first_price/add_wt/add_price/fee/trunk 直映 | ✓ |
| 报价脚注 | 「共 X 行报价 · Y 国家」 | items.length 与 continent||country 分组数 order.length | ✓ |
| Reference h2 | 「…· {12} 类参考」 | appendix meta 实测 sections=12 ✓（空 ds 400 bug 已修，logistics.py:319-320 注释自证） | ✓ |
| REF_COLS 9 组列头 | state_city/uk_postcode/ca_postcode/aus_postcode/reachable/remote_reach/remote_unreach/prohibited/hpra | rowToArr（page.tsx:747-758）键名逐一对应数据结构 | ✓ |
| plastic_ce/packaging | 无列定义 → 「内容」 | fallback 单列渲染，packaging 实测占位行不破版 | ✓ |
| 品牌隔离 | 底注「归母账号品牌隔离」 | `brand=onno` 实测 stats=null/表 0 行空态（KPI 显"—"，fmt.ts:17-18 null→"—" 非 0）；SQL 仅 zipforce 40 行 | ✓ |
| 搜索框联动 | （同上） | （同上） | ✓ |

---

## 附：实测快照（2026-10-12）

- 全品牌: stats={total:40, transit:17, delivered:18, customs:1, awaiting:2, stage_overdue:3, as_of:"2026-09-04T16:25:38+08:00"}；by_badge 五态求和=40 ✓ 与 SQL 直算逐项吻合
- brand=onno: stats=null · by_badge=[] · total=0（空态 ✓ 符合"无数据=空态"铁律）
- pricing: channels=106 ✓ · codes=265（含 7 非国家码 → ⚠️-8）
- appendix: sections=12，vat 行={vat:'0.2',country:'奥地利',no_ioss:'0.22'}（→ ⚠️-9）

**状态**: 完成，停住等主窗口（zipforce-hub）指令。
