# Fbo By Date

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

- Skill: `yulianggan/fbo-by-date` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add yulianggan/fbo-by-date`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yulianggan/fbo-by-date/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: yulianggan (https://skillmd.com/u/yulianggan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yulianggan/fbo-by-date

---


# 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`

## 用法

```bash
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
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 端点速查