# 库存历史数据回填 — 2026-05-28 工作记录

## 目标
将 inventory_snapshot 表从 2023-01-01 补齐到 2026-05-20。

## ERP 接口发现

| 接口 | 用途 | 日期筛选 | 结果 |
|------|------|---------|------|
| `/inventory/summary` | 库存库位统计（快照） | ❌ 无效 | 始终返回当前库存，20天全一样 |
| `/inventory/ledger_cate` | 库存台帐分类统计 | ✅ 有效 | 按日期返回台账数据 |
| `/inventory/cate_summary` | 库存库位分类统计 | 未测试 | 返回0行 |
| `/inventory/ledger_cate_new` | 新版台账 | ✅ 有效 | 比旧版略快1.3s，数据一致 |

### ledger_cate 参数
- `end_date` + `zx_end_date`: 制单/录账截止日期，设同一天
- `mode=6`: 店铺+商品+颜色汇总（11列）
- `mode=7`: 店铺+商品+颜色+尺码汇总（含一类/品牌/年份/季节列，34列）
- `price_type=CKJJ`: 参考进价
- 分类筛选 (sxname1-4) 非必须，但可增加输出维度列

### 关键教训
- `/inventory/summary` 的 `end_date` 参数不生效，永远是当前库存 → 不能用
- `/inventory/ledger_cate` 的 `start_date` 参数被忽略，台账起点是系统固定的
- 不加分类筛选时 URL 很短(~100字符)，加了品牌全选后 URL 超长(3000+字符)→ HTTP 400
- 使用 mode=6 不加分类筛选即可得到按日期变化的数据
- mode=7 把所有品牌值放入 URL 会导致 GET 请求超长，需用 mode=6 替代

## 已完成的工作

### ✅ 2026年数据抓取 (139天)
- 范围: 2026-01-01 ~ 2026-05-19
- 接口: `/inventory/ledger_cate`, mode=6, 无分类筛选
- 脚本: `/home/ubuntu/backfill_2026_v5.py`
- 结果: 139/139 成功，1,335,339 行
- 遇到问题: session cookie 过期 (约15分钟)，已在 v5 加入自动重登录

### ✅ 2025年数据抓取 (365天)
- 范围: 2025-01-01 ~ 2025-12-31
- 脚本: `/home/ubuntu/backfill_2025.py`
- 结果: 365/365 成功，2,576,733 行

### ✅ 数据压缩 (full/delta)
- 脚本: `/home/ubuntu/compress_inventory.py`
- 规则: 周日 + 月初第一天 + 月末最后一天 = full；其他 = delta
- 2025-2026 合计: 101天 full, 403天 delta
- 压缩前: ~391万行, 680MB
- 压缩后: 237万行, 410MB (省40%)

### ✅ Pipeline 脚本更新
- 文件: `~/sietadata/pipeline/daily/import_inventory.py`
- 改动: full 判断从"仅周日"改为"周日+月初+月末"
- 逻辑: `is_full = is_sunday or is_first_of_month or is_last_of_month`

### ❌ 2023-2024 数据抓取（待ERP维护修复）

#### 5/28 下午 — 维护修复后
- 2023-2024 返回了数据（之前为0行）
- 使用 mode=6 + 一类/年份/季节全选（品牌因URL超长跳过）

#### 5/28 晚上 — 数据验证失败
- 大头哥导出 2023-03-15 正确数据 (storagecatedummy.xls): 4,521行, 15,078双, 全部正数
- ERP ledger_cate 同期返回: 4,832行, 仅613双, 大量正负抵消
- **根因: `/inventory/ledger_cate` 返回台账流水（有正有负），不是库存快照**
- 大头哥认为 ledger_cate 应该直接是当日库存，已反馈ERP维护，明天修复

#### 正确接口推测
- `/inventory/summary` (库存库位统计) — 当前库存快照，但日期筛选不生效
- 大头哥导出的xls对应这个接口的输出格式（全正数、高总量）
- 需要ERP维护修正日期筛选功能

## 待完成工作

### 2023-2024: 锚点+销售倒推
- 方案: 从 2025-01-07 的库存锚点开始，配合 sales_ledger 逐天反推
- 公式: `前一天库存 = 当天库存 + 当天销售`
- 全部在本地 SQLite 内完成，不需要调 ERP
- 等大头哥确认 ERP 数据问题后再执行

### 数据库状态
```
表: inventory_snapshot
├── 2025-01-01 ~ 2025-12-31: full/delta (257万行)
├── 2026-01-01 ~ 2026-05-19: full/delta (133万行)
├── 2026-05-20: full (pipeline原始, 6646行)
└── 2023-2024: 空白
总大小: 410MB
```

## 脚本清单

| 脚本 | 位置 | 用途 |
|------|------|------|
| backfill_2026_v5.py | /home/ubuntu/ | 抓2026(含自动重登录) |
| backfill_2025.py | /home/ubuntu/ | 抓2025 |
| backfill_2024.py | /home/ubuntu/ | 抓2024(空数据) |
| compress_inventory.py | /home/ubuntu/ | 全量→full/delta压缩 |
| import_inventory.py | ~/sietadata/pipeline/daily/ | pipeline入库(已更新) |

## 其他今日完成
- 品牌颜色修复: instant_sales_pc.html + instant_sales.html → 品牌名映射取色
- skill: test-before-modify (页面修改先出test)