库存台账系统设计文档

来源：大头哥前期研究成果
整合日期：2026-05-16
用途：SietaData 数据分析系统的库存模块底层数据模型

1. 系统目标

• 能够查询任意一天的库存明细（库存台账）。
• 保留每日的销售、到货、退货、调整等变动记录。
• 使用 SQLite 数据库，在 2 核 4GB、20GB 剩余空间的 Ubuntu 服务器上运行。
• 维护简单，数据量精简，长期运行无压力。

2. 数据来源与生成频率

2.1 周快照

• 频率：每周日 24:00 生成一次。
• 内容：该时刻所有 SKU 的全量库存数据（约 3000 条）。
• 用途：作为查询的"起点锚点"，减少查询时需要累加的流水天数，同时可兼作周度分析基础。

2.2 日报表

• 频率：每天 24:00 生成一张表。
• 内容：
• 当天结束时的全量库存（每个 SKU 的当前库存数）。
• 当天的销售汇总（每个 SKU 的销售出库数量）。
• 用途：作为每日变动计算的原材料，不会直接整表存入数据库（只提取变化部分）。

2.3 其他业务数据（可选）

• 目前系统没有独立的"到货单""退货单""调整单"。
• 可通过手动补充或未来对接系统获得，用于进一步细化变动类型。

3. 数据库设计

3.1 商品表（product）

3.2 库存快照表（inventory_snapshot）

主键：(snapshot_week, sku_id) 唯一确定某周某商品的快照库存

• 每周日生成一次，每年约 52 周 × 3000 SKU ≈ 15.6 万行。

3.3 库存变动流水表（inventory_ledger）

索引：(change_date, sku_id) 加速按日期和商品查询

变动类型枚举：

• 只记录当天发生变化的 SKU，无变化则不产生流水。
• 每天新增行数取决于发生变动的 SKU 数量，估计远小于 3000 行。

4. 每日数据处理逻辑

4.1 数据准备

• 获取昨天的全量库存（通过最近一周快照 + 快照之后到昨天的所有流水累加得出）。
• 获取今天的日报表：包含今天全量库存、今日销售汇总。
• 可选：手工标记的已知变动（如确切的到货、退货数据）。

4.2 计算步骤

1. 写入销售流水：遍历每个 SKU，若今日销售数量 > 0，则插入一条 sale 记录，delta_qty 为负。
2. 计算非销售净变动：
3. 净变化 = 今日库存 - 昨日库存
4. 非销售净变动 = 净变化 + |销售出库|
5. 处理非销售净变动：
6. 若为非零正数：说明库存因"非销售"原因增加（可能是到货、退货或盘盈）。默认记为 adjustment_in（或根据业务习惯记为 purchase，后续可修正）。
7. 若为非零负数：说明库存因"非销售"原因减少，记为 adjustment_out。
8. 若有额外信息可在此步骤中将对应的 adjustment_in 手动修改为 purchase 或 return。

4.3 周快照生成

• 当执行日期为周日时，将当天的全量库存存入 inventory_snapshot 表，记录该周的结束状态，同时作为下一周的起点。

5. 查询任意一天库存的方法

1. 找到目标日期 T 之前的最近一个周日快照日期 S（S <= T 且为周日）。
2. 计算该 SKU 在 T 日的库存： T日库存 = 快照中该SKU的数量 + Σ(从 S+1 到 T 所有该SKU的 delta_qty 之和)
3. 可使用 SQL 直接聚合得出，索引加持下查询极快。

6. 服务器资源评估

• 服务器配置：2 核 CPU，4GB 内存，剩余约 20GB 磁盘。
• 数据量预估：
• 周快照：约 15.6 万行/年，占用空间极小。
• 流水表：假设平均每天 1000~2000 行变动，年增约 36~70 万行。
• 10 年数据总量在千万行级别，SQLite 轻松应对。
• 性能表现：
• 千万行数据下，索引查询任一日期的库存为毫秒级。
• 每日写入几千行在秒级完成，无需担忧性能瓶颈。
• 数据库文件大小在数 GB 以内，备份恢复快速。

7. 维护与扩展建议

• 初始化：第一个周日存入初始快照，即可开始运行。
• 自动化：将每日处理脚本部署为定时任务（cron），在每天凌晨执行，读取日报表，更新流水。
• 数据修正：如果发现某天数据有误，可直接修改流水记录，然后重新生成受影响的周快照。
• 未来扩展：
• 若后期对接了采购/退货系统，可直接插入准确的 purchase、return 流水，并将之前同一天的 adjustment_in 记录合并或删除。
• 可按月或按年归档旧数据，但通常无必要。

8. 术语说明

• 周快照：每周日 24:00 的全量库存数据，作为快速查询的起点。
• 日报表：每日 24:00 生成的包含当日全量库存和销售汇总的数据文件。
• 推算入库/推算出库：通过库存变化反推的非销售变动量，因暂时无法区分到货、退货、调整而统称。

与 SietaData 系统的关系

此设计是整个数据分析系统的数据基座：

ERP 邮件 xlsx → 日报表/周快照 → inventory_ledger → 库存台账查询
                                                    ↓
                                             销售分析、经营建议

设计要点： - 数据源是 oupu 每天 24:00 自动生成的全量库存 + 销售汇总 xlsx - 通过邮件接收（himalaya），跑 pipeline 脚本入库 - 库存台账是底层数据服务，上层分析报表（日报/周报/月报）依赖它获取任意日期库存 - 销售分析直接依赖 inventory_ledger 中的 sale 记录 - 数据分析阶段先走 ana 大模型分析产出洞察，稳定后转纯脚本