fbo-by-date

name	fbo-by-date
description	Ozon FBO 按 timeslot 日期生成对照表 + 合并箱唛 PDF (build_by_date.py). 当用户说 "按日期整理对照表"、"按发运日期分对照表"、"准备交货 tab 的对照表"、"按预约时间合并箱唛"、"按日期合并 PDF"、"打印发货清单"、"司机交货前出对照表" 时触发. 默认只取 READY_TO_SUPPLY 状态 (Ozon 后台 "准备交货" tab), 输出 by_date/YYYY-MM-DD/{对照表.xlsx, 箱唛合并.pdf}.

FBO 按日期对照表 + 箱唛合并

场景: 司机来取货前, 按 Ozon 后台 "准备交货" tab 的预约日期, 整理每日的发货清单 + 把同日的所有箱唛 PDF 合并成 1 个文件方便打印.

脚本: /Users/mac/Documents/ozns/丝绸生活/海外仓发货表/2026-04-23海外仓发货/build_by_date.py (~280 行)

触发场景

• "按发运日期整理对照表"
• "Ozon 后台准备交货 tab 的 supply 出对照表"
• "把 04-28 那批 supply 的箱唛合并成一个 PDF"
• "司机要来取货, 帮我整理今天/明天的清单"
• "按预约时间分文件夹"

工作流

1. 调 4182 /v1/supply-order/list 拿账号下符合 state 的 supply (默认 READY_TO_SUPPLY)
2. 对每个 order 调 /v3/supply-order/get + /v1/supply-order/bundle + /v1/cargoes/get
3. 按 timeslot.from 日期分组 (YYYY-MM-DD)
4. 对每个日期:
   • 写 22 列对照表 xlsx (跟 create_fbo_plan.py 输出同 schema)
   • 用 pypdf 合并该日所有 supply PDF 到 箱唛合并.pdf

用法

cd /Users/mac/Documents/ozns/丝绸生活/海外仓发货表/2026-04-23海外仓发货

# 默认: 丝绸生活账号, 只取 READY_TO_SUPPLY (Ozon "准备交货" tab)
python3 build_by_date.py

# 多账号
python3 build_by_date.py --account 个人之路

# 指定日期范围 (ISO 8601)
python3 build_by_date.py --since 2026-04-22T00:00:00Z --to 2026-04-30T00:00:00Z

# 多状态 (逗号分隔)
python3 build_by_date.py --states "READY_TO_SUPPLY,SHIPPING_PREPARED"

# 全状态 (含 CANCELLED 历史)
python3 build_by_date.py --states all

状态清单

--states 参数取值 (Ozon supply state 枚举):

值	Ozon 后台 Tab	含义
DRAFT / DATA_FILLING	"新的"	草稿/数据填充中
READY_TO_SUPPLY (默认)	"准备交货"	已切箱+箱唛, 等司机取货
SHIPPING_PREPARED / SUPPLY_PROCESSING	"在途商品和验收"	在途/到仓清点中
SUPPLIED / SUPPLIED_PARTIALLY	"报告单据确认"	已收货等确认
SUPPLY_REJECTED / CANCELLED	"档案"	拒收/取消 (历史)

输出结构

by_date/
├── 2026-04-28/
│   ├── 对照表.xlsx       # 22 列 (跟 create_fbo_plan.py 输出同)
│   └── 箱唛合并.pdf      # 同日所有 supply PDF 合并
├── 2026-05-06/
│   ├── 对照表.xlsx
│   └── 箱唛合并.pdf

22 列 schema (跟 create_fbo_plan.py 一致)

交货 ID | 供货 ID* | 状态 | 链路 | 集群 | macrolocal_cluster_id |
货位 ID* | 货位名称 | drop-off ID* | drop-off 名称 |
货号 (offer_id) | SKU | 条码 |
箱号 | cargo_id* | 该箱件数 |
总件数 | 总箱数 | 单箱装箱率 |
时段 | 箱唛 PDF 路径 | 备注/错误

* 标的 4 列 (供货 ID / 货位 ID / drop-off ID / cargo_id) 强制写成字符串 (number_format=@), 防 Excel 把 16 位长 ID 解析成科学计数法.

已知行为

1. 箱内容推算: /v1/cargoes/get 响应里 cargo 不含 items 嵌套, 只有 cargo_id. 脚本用 /supply-order/bundle 拿 sku 总件 + box_size = 总件 / cargo 数 推算每箱 (跟 create_fbo_plan.py rows_per_box 一致).
2. 集群名空: Ozon /supply-order/get.supplies[].cluster.name 在 READY_TO_SUPPLY 状态下不填. 用户需要可加 macrolocal_cluster_id → cluster_name 反查 (4182 /cluster/list, 未实现).
3. PDF 查找: 扫两个目录:
   • /Users/mac/Documents/ozns/github/ozon_fbo_shipment_service/labels/ (Docker mount)
   • <工作目录>/labels/ (本地 fallback)
   • 命名: <supply_id>.pdf 或 supply_<supply_id>.pdf, 兜底 substring 匹配

实测 (2026-04-26 丝绸生活)

日期           orders supplies  rows  pdfs pages
2026-04-28       12       12    41    12    41
2026-05-06        1        1     3     1     3

13 orders 全 READY_TO_SUPPLY, 41+3=44 箱 = 44 页合并 PDF.

关键 API 坑点 (实测)

• /v1/cargoes/get payload 字段是 supply_ids (list, minItems=1) — 单数 supply_id 422 Unprocessable. 详见 memory feedback_cargoes_get_supply_ids_list.md.
• /v1/supply-order/list 必传 sort_by:1 — 默认 0 会乱序, 翻页 last_id 失效.
• timeslot 在响应里嵌套两层: order.timeslot.timeslot.from (不是 order.timeslot.from).

同步 .py 到本 skill

bash /Users/mac/.claude/skills/sync_fbo_scripts.sh

相关 skill / memory

• /fbo-orchestrator — 端到端发货编排, 终态报告 step 调本 skill
• /fbo-status — build_shipment_overview.py 计划 vs 已发对照表 (按 cluster×SKU 聚合, 跟本 skill 按 date 分组互补)
• /fbo-fill-boxes — 单 order 填箱+箱唛
• memory reference_build_by_date.md — 实测数据 + 算法
• memory feedback_cargoes_get_supply_ids_list.md — /cargoes/get 字段坑
• memory reference_ozon_fbo_api.md — 4182 端点速查