冷链库存系统 核心数据表设计说明书
冷链库存系统 核心数据表设计说明书（业务职责+真相源+全链路数据演示）
0. 文档说明
0.1 文档目标
本文档用于规范冷链库存系统核心数据表定义，明确每张表的业务职责、数据真相源、可修改规则，完整还原「采购 → 收货入库 → 用户下单 → 支付 → 仓库出库 → 售后退货 → 退货质检」全业务链路的数据变更逻辑。
文档服务对象：后端开发、库存模块开发、数据库评审、测试用例编写、库存异常排查、库存对账、售后批次追溯。
0.2 核心阅读原则（全局通用）
库存系统所有数据分为六类，分工明确、无交叉冗余，是所有开发测试的核心依据：
| 数据分类 | 核心数据表 | 核心职责 | 是否业务真相源 |
|---|---|---|---|
| 采购事实数据 | purchase_order / purchase_order_item / purchase_receipt_item | 记录采购计划、SKU明细、实际到货与质检事实 | 是（采购链路唯一真相） |
| 库存批次溯源数据 | inventory_batch | 记录库存来源、效期、固化成本，支撑全链路批次追溯 | 是（批次&成本唯一真相） |
| 库存实时状态数据 | inventory_balance | 存储仓库、SKU、批次实时库存、冻结库存、库存状态 | 是（库存余额唯一真相） |
| 订单库存占用数据 | order_inventory_lock | 记录订单精准锁定的批次、数量、履约状态 | 是（订单占库唯一真相） |
| 库存变更流水数据 | inventory_flow | 记录每一次库存增减、冻结释放，用于审计对账 | 是（变更历史唯一真相） |
| 库存查询汇总数据 | inventory_stock_summary | 前台、后台快速查询展示，仅做加速视图 | 否（可随时重建） |
三大黄金判定规则（强制执行）
- 查当前真实库存：以 inventory_balance 为准；
- 查订单锁了哪些批次：以order_inventory_lock 为准；
- 查库存变更原因与轨迹：以 inventory_flow为准。
1. 核心数据表详细设计（含职责/真相源/可改规则）
本章每张表统一标准化输出：核心定位、业务职责、真相源属性、可修改规则、核心字段、关键业务规则，无混杂内容，可直接对照开发测试。
1.1 purchase_order 采购单头表
核心定位：采购单维度的头部计划数据
业务职责：存储单张采购单的供应商、目标仓库、商品总金额、冷链运费、杂费、单据状态等整体信息，仅代表采购计划。
真相源属性：采购单头部数据唯一真相源
可修改规则：未完结单据可更新状态、费用；单据完成/取消后禁止修改。
核心字段
| 字段名 | 字段说明 |
|---|---|
| po_no | 采购单号（主键） |
| warehouse_id | 目标入库仓库ID |
| goods_amount | 商品总金额（不含运费、杂费） |
| freight_amount | 冷链运输专属费用 |
| other_cost_amount | 装卸、仓储前置等其他杂费 |
| po_status | 单据状态：NEW新建、RECEIVING收货中、FINISHED完成、CANCEL取消 |
| create_time | 创建时间 |
关键业务规则
采购单仅为计划数据，单据取消不会产生任何库存、批次、流水数据。
1.2 purchase_order_item 采购单明细表
核心定位：采购单SKU维度计划明细
业务职责：记录采购单下每个SKU的计划采购数量、单位、单价，固化下单时刻的单位换算快照。
真相源属性：采购计划明细唯一真相源
可修改规则：开始收货后禁止任何修改，保证历史单据稳定。
核心字段
| 字段名 | 字段说明 |
|---|---|
| id | 明细主键 |
| po_no | 关联采购单号 |
| sku_id | 商品SKU |
| purchase_qty | 计划采购数量 |
| unit_code | 采购单位（BOX/BAG） |
| unit_ratio | 下单时刻单位换算快照（固化不变） |
| purchase_price | 对应单位采购单价 |
核心快照规则
商品主数据单位比例后续变更，不影响历史采购单，历史单据永远以自身unit_ratio快照为准，避免数据错乱。
1.3 purchase_receipt_item 采购收货明细表
核心定位：采购实际到货、质检结果明细
业务职责：记录真实到货数量、合格数量、拒收数量、供应商批次、效期信息，是库存入库的唯一前置依据。
真相源属性：采购到货&入库合规唯一真相源
可修改规则：生成库存批次后禁止修改。
核心字段
| 字段名 | 字段说明 |
|---|---|
| id | 明细主键 |
| po_no | 关联采购单号 |
| sku_id | 商品SKU |
| unit_code | 收货单位 |
| received_qty | 实际到货总数 |
| accepted_qty | 质检合格数量（可入库） |
| rejected_qty | 质检拒收数量（不入库） |
| supplier_batch_no | 供应商原始批次号 |
| production_date | 生产日期 |
| expire_date | 有效期截止时间 |
核心库存规则
- 数量公式：received_qty = accepted_qty + rejected_qty
- 仅合格数量 accepted_qty 可入库、生成批次；
- 拒收数量不产生任何库存数据。
1.4 inventory_batch 库存批次表
核心定位：库存批次溯源与成本固化中心
业务职责：记录每一批库存的来源、原始供应商批次、生产日期、有效期、基础单位固化成本，支撑全链路追溯与财务核算。
真相源属性：批次来源、批次成本、批次效期唯一历史真相源
可修改规则：批次创建后严禁修改，cost_per_base_unit 永久固化。
核心字段
| 字段名 | 字段说明 |
|---|---|
| batch_id | 库存批次唯一ID（主键） |
| sku_id | 商品SKU |
| source_type | 批次来源：PURCHASE采购、RETURN退货、TRANSFER调拨 |
| origin_batch_id | 原始批次ID（退货/调拨用于追溯上游批次） |
| supplier_batch_no | 供应商批次号 |
| production_date | 生产日期 |
| expire_date | 有效期 |
| cost_per_base_unit | 基础单位固化成本（永久不变） |
成本核算规则
批次总成本=商品采购金额+分摊冷链运费+分摊杂费，统一换算为系统基础单位成本固化存储，保证订单毛利、财务核算不被污染。
1.5 inventory_balance 库存余额明细表
核心定位：实时库存唯一底座
业务职责：按「仓库+SKU+批次+单位+库存状态」维度，存储当前实物库存、冻结库存，所有库存增减、冻结、扣减、恢复最终落地本表。
真相源属性：实时库存数量、库存状态唯一业务真相源
可修改规则：仅业务事务可更新，禁止人工改库、禁止业务绕过本表。
唯一维度
warehouse_id + sku_id + batch_id + unit_code + stock_status
核心字段
| 字段名 | 字段说明 |
|---|---|
| id | 主键 |
| warehouse_id | 仓库ID |
| sku_id | 商品SKU |
| batch_id | 库存批次ID |
| unit_code | 库存单位 |
| stock_status | 库存状态 |
| qty | 当前实物库存总量 |
| frozen_qty | 当前冻结库存数量 |
库存状态定义
| 状态 | 说明 | 是否可售 |
|---|---|---|
| NORMAL | 正常在库库存 | 是 |
| PENDING_QC | 退货待质检 | 否 |
| DAMAGED | 损坏/报废 | 否 |
可售库存公式
available_qty = qty - frozen_qty
备注：frozen_qty 仅为批次汇总值，无法定位订单，订单占用明细必须查 lock 表。
1.6 inventory_flow 库存流水表
核心定位：库存变更审计与追溯凭证
业务职责：记录每一次实物库存、冻结库存的变更记录，用于对账、排查问题、业务重放、审计留痕。
真相源属性：库存变更历史唯一真相源
可修改规则：只 INSERT，不 UPDATE、不 DELETE
核心字段
| 字段名 | 字段说明 |
|---|---|
| flow_id | 流水唯一ID |
| biz_no | 关联业务单据号 |
| flow_type | 变更类型 |
| warehouse_id | 仓库ID |
| sku_id | 商品SKU |
| batch_id | 关联批次 |
| unit_code | 变更单位 |
| qty_change | 实物库存变更（正负增减） |
| frozen_change | 冻结库存变更（正负增减） |
| cost_snapshot | 变更时刻成本快照 |
1.7 order_item 订单商品快照表
核心定位：下单时刻商品数据固化快照
业务职责：保存用户下单时的SKU、单位、换算比例、售价，保证历史订单数据永久不变。
真相源属性：历史订单商品明细唯一真相源
可修改规则：订单创建后禁止修改
核心字段
| 字段名 | 字段说明 |
|---|---|
| id | 明细主键 |
| order_no | 订单号 |
| sku_id | 商品SKU |
| sale_unit | 销售单位 |
| unit_ratio | 下单时刻单位换算快照 |
| sale_qty | 下单数量 |
| sale_price | 下单售价快照 |
1.8 order_inventory_lock 订单库存锁明细表
核心定位：订单与库存批次绑定关系唯一凭证
业务职责：精准记录每笔订单锁定的具体批次、锁定数量、已付/已发/已释数量，解决「只看汇总无法定位批次」的问题。
真相源属性：订单库存占用明细唯一真相源
可修改规则：仅可更新履约状态数量，锁定批次、原始锁定量不可改。
核心字段
| 字段名 | 字段说明 |
|---|---|
| lock_id | 锁定记录ID |
| order_no | 订单号 |
| batch_id | 被锁定批次ID |
| unit_code | 锁定单位 |
| locked_qty | 初始锁定总量 |
| paid_qty | 已支付锁定量 |
| shipped_qty | 已发货扣减量 |
| released_qty | 已释放库存量 |
1.9 inventory_stock_summary 库存汇总表
核心定位：查询加速视图
业务职责：为商城、后台列表提供快速库存展示，提升查询性能。
真相源属性：非业务真相源，数据完全依赖 inventory_balance
可修改规则：支持自动更新、支持全量重建
使用规范
✅ 允许：前台展示、后台查询、报表统计
❌ 禁止：冻结、扣库、出库、售后、并发控制（所有业务必须走 balance）
2. 全业务链路完整数据演示
2.1 前置条件
- 仓库：WH01
- 基础单位：BAG
- 换算规则：1 BOX = 10 BAG
- SKU001：冷链牛奶、SKU002：冷链酸奶
- 额外总成本：2000元（运费1500+杂费500），SKU001分摊1200、SKU002分摊800
阶段1：采购下单（仅计划、无库存）
采购单：PO-20260908-001，SKU001 100BOX、SKU002 50BOX
新增 purchase_order
| po_no | warehouse_id | goods_amount | freight_amount | other_cost_amount | po_status |
|---|---|---|---|---|---|
| PO-20260908-001 | WH01 | 20000 | 1500 | 500 | NEW |
新增 purchase_order_item
| id | po_no | sku_id | purchase_qty | unit_code | unit_ratio | purchase_price |
|---|---|---|---|---|---|---|
| 1 | PO-20260908-001 | SKU001 | 100 | BOX | 10 | 100 |
| 2 | PO-20260908-001 | SKU002 | 50 | BOX | 10 | 200 |
本阶段变更总结：仅新增采购头、采购明细，库存相关表无任何数据。
阶段2：采购收货入库（生成批次+正式入库）
实际收货：SKU001 100BOX全合格；SKU002 到货50BOX、合格48BOX、拒收2BOX
批次成本计算
SKU001：(100*100+1200) ÷ 1000BAG = 11.2元/BAG
SKU002：(48*200+800) ÷ 480BAG ≈ 21.667元/BAG
新增 purchase_receipt_item
| id | po_no | sku_id | unit_code | received_qty | accepted_qty | rejected_qty | supplier_batch_no | production_date | expire_date |
|---|---|---|---|---|---|---|---|---|---|
| 101 | PO-20260908-001 | SKU001 | BOX | 100 | 100 | 0 | S-M-001 | 2026-09-01 | 2026-12-01 |
| 102 | PO-20260908-001 | SKU002 | BOX | 50 | 48 | 2 | S-Y-001 | 2026-09-02 | 2026-11-30 |
新增 inventory_batch 批次
| batch_id | sku_id | source_type | origin_batch_id | supplier_batch_no | production_date | expire_date | cost_per_base_unit |
|---|---|---|---|---|---|---|---|
| B001 | SKU001 | PURCHASE | NULL | S-M-001 | 2026-09-01 | 2026-12-01 | 11.2 |
| B002 | SKU002 | PURCHASE | NULL | S-Y-001 | 2026-09-02 | 2026-11-30 | 21.667 |
新增 inventory_balance 库存余额
| id | warehouse_id | sku_id | batch_id | unit_code | stock_status | qty | frozen_qty |
|---|---|---|---|---|---|---|---|
| 201 | WH01 | SKU001 | B001 | BOX | NORMAL | 100 | 0 |
| 202 | WH01 | SKU002 | B002 | BOX | NORMAL | 48 | 0 |
新增 inventory_flow 入库流水
| flow_id | biz_no | flow_type | warehouse_id | sku_id | batch_id | unit_code | qty_change | frozen_change | cost_snapshot |
|---|---|---|---|---|---|---|---|---|---|
| F1 | PO-20260908-001 | PURCHASE_IN | WH01 | SKU001 | B001 | BOX | +100 | 0 | 11.2 |
| F2 | PO-20260908-001 | PURCHASE_IN | WH01 | SKU002 | B002 | BOX | +48 | 0 | 21.667 |
更新 inventory_stock_summary
| warehouse_id | sku_id | unit_code | normal_qty | frozen_qty | available_qty |
|---|---|---|---|---|---|
| WH01 | SKU001 | BOX | 100 | 0 | 100 |
| WH01 | SKU002 | BOX | 48 | 0 | 48 |
阶段3：用户下单（库存冻结、不减少实物）
订单O-20260908-001，购买：SKU001 10BOX、SKU002 5BOX，批次策略FEFO先到期先出
新增 order_item
| id | order_no | sku_id | sale_unit | unit_ratio | sale_qty | sale_price |
|---|---|---|---|---|---|---|
| 301 | O-20260908-001 | SKU001 | BOX | 10 | 10 | 120 |
| 302 | O-20260908-001 | SKU002 | BOX | 10 | 5 | 240 |
更新 inventory_balance（增加冻结量）
| id | warehouse_id | sku_id | batch_id | unit_code | stock_status | qty | frozen_qty |
|---|---|---|---|---|---|---|---|
| 201 | WH01 | SKU001 | B001 | BOX | NORMAL | 100 | 10 |
| 202 | WH01 | SKU002 | B002 | BOX | NORMAL | 48 | 43 |
新增订单商品快照 order_item
| lock_id | order_no | batch_id | unit_code | locked_qty | paid_qty | shipped_qty | released_qty |
|---|---|---|---|---|---|---|---|
| L001 | O-20260908-001 | B001 | BOX | 10 | 0 | 0 | 0 |
| L002 | O-20260908-001 | B002 | BOX | 5 | 0 | 0 | 0 |
新增库存冻结流水 inventory_flow
| flow_id | biz_no | flow_type | warehouse_id | sku_id | batch_id | unit_code | qty_change | frozen_change | cost_snapshot |
|---|---|---|---|---|---|---|---|---|---|
| F3 | O-20260908-001 | STOCK_FROZEN | WH01 | SKU001 | B001 | BOX | 0 | +10 | 11.2 |
| F4 | O-20260908-001 | STOCK_FROZEN | WH01 | SKU002 | B002 | BOX | 0 | +5 | 21.667 |
更新库存汇总表 inventory_stock_summary
| warehouse_id | sku_id | unit_code | normal_qty | frozen_qty | available_qty |
|---|---|---|---|---|---|
| WH01 | SKU001 | BOX | 100 | 10 | 90 |
| WH01 | SKU002 | BOX | 48 | 5 | 43 |
本阶段变更总结：生成订单商品快照、锁定对应批次库存，实物库存数量不变，冻结库存增加，可售库存减少，所有变更留痕库存流水。
阶段4：用户支付完成（锁定量确权）
用户完成订单支付，订单锁定库存正式确权，标记为已支付锁定量，库存冻结状态保持不变，仅更新锁单明细。
更新 order_inventory_lock 支付确权数据
| lock_id | order_no | batch_id | unit_code | locked_qty | paid_qty | shipped_qty | released_qty |
|---|---|---|---|---|---|---|---|
| L001 | O-20260908-001 | B001 | BOX | 10 | 10 | 0 | 0 |
| L002 | O-20260908-001 | B002 | BOX | 5 | 5 | 0 | 0 |
本阶段变更总结：仅更新订单库存锁明细表支付数量，库存余额、冻结量无变化，无新增库存流水，完成库存确权，锁定库存不可释放。
阶段5：仓库出库履约（实物库存扣减）
仓库根据订单履约，完成SKU001 10BOX、SKU002 5BOX商品出库，扣减实物库存、清空对应冻结库存，更新锁单履约数据。
更新 inventory_balance 库存余额
| id | warehouse_id | sku_id | batch_id | unit_code | stock_status | qty | frozen_qty |
|---|---|---|---|---|---|---|---|
| 201 | WH01 | SKU001 | B001 | BOX | NORMAL | 90 | 0 |
| 202 | WH01 | SKU002 | B002 | BOX | NORMAL | 43 | 0 |
更新 order_inventory_lock 出库履约数据
| lock_id | order_no | batch_id | unit_code | locked_qty | paid_qty | shipped_qty | released_qty |
|---|---|---|---|---|---|---|---|
| L001 | O-20260908-001 | B001 | BOX | 10 | 10 | 10 | 0 |
| L002 | O-20260908-001 | B002 | BOX | 5 | 5 | 5 | 0 |
新增出库库存流水 inventory_flow
| flow_id | biz_no | flow_type | warehouse_id | sku_id | batch_id | unit_code | qty_change | frozen_change | cost_snapshot |
|---|---|---|---|---|---|---|---|---|---|
| F5 | O-20260908-001 | STOCK_OUT | WH01 | SKU001 | B001 | BOX | -10 | -10 | 11.2 |
| F6 | O-20260908-001 | STOCK_OUT | WH01 | SKU002 | B002 | BOX | -5 | -5 | 21.667 |
更新库存汇总表 inventory_stock_summary
| warehouse_id | sku_id | unit_code | normal_qty | frozen_qty | available_qty |
|---|---|---|---|---|---|
| WH01 | SKU001 | BOX | 90 | 0 | 90 |
| WH01 | SKU002 | BOX | 43 | 0 | 43 |
本阶段变更总结：实物库存扣减、冻结库存清零，订单锁单标记完成履约，生成出库流水记录，库存数据与实际履约状态一致。
阶段6：售后退货+退货质检全流程
用户发起售后退货，退回已购买的SKU001 2BOX商品，退货入库后进入待质检状态，质检后2BOX全部合格，重新入库恢复可售库存。
6.1 退货待质检入库（状态变更、不恢复可售）
生成退货库存批次，库存状态变更为PENDING_QC（退货待质检），新增批次、更新库存余额、生成退货流水。
新增 inventory_batch 退货批次
| batch_id | sku_id | source_type | origin_batch_id | supplier_batch_no | production_date | expire_date | cost_per_base_unit |
|---|---|---|---|---|---|---|---|
| B003 | SKU001 | RETURN | B001 | S-M-001 | 2026-09-01 | 2026-12-01 | 11.2 |
更新 inventory_balance 待质检库存
| id | warehouse_id | sku_id | batch_id | unit_code | stock_status | qty | frozen_qty |
|---|---|---|---|---|---|---|---|
| 203 | WH01 | SKU001 | B003 | BOX | PENDING_QC | 2 | 0 |
新增退货待质检流水 inventory_flow
| flow_id | biz_no | flow_type | warehouse_id | sku_id | batch_id | unit_code | qty_change | frozen_change | cost_snapshot |
|---|---|---|---|---|---|---|---|---|---|
| F7 | RT-20260908-001 | RETURN_IN_PENDING | WH01 | SKU001 | B003 | BOX | +2 | 0 | 11.2 |
6.2 退货质检通过（转为可售库存）
质检完成，2BOX退货商品全部合格，库存状态由PENDING_QC变更为NORMAL，恢复可售权限。
更新 inventory_balance 库存状态
| id | warehouse_id | sku_id | batch_id | unit_code | stock_status | qty | frozen_qty |
|---|---|---|---|---|---|---|---|
| 203 | WH01 | SKU001 | B003 | BOX | NORMAL | 2 | 0 |
新增质检完成流水 inventory_flow
| flow_id | biz_no | flow_type | warehouse_id | sku_id | batch_id | unit_code | qty_change | frozen_change | cost_snapshot |
|---|---|---|---|---|---|---|---|---|---|
| F8 | RT-20260908-001 | QC_PASS | WH01 | SKU001 | B003 | BOX | 0 | 0 | 11.2 |
更新最终库存汇总表 inventory_stock_summary
| warehouse_id | sku_id | unit_code | normal_qty | frozen_qty | available_qty |
|---|---|---|---|---|---|
| WH01 | SKU001 | BOX | 92 | 0 | 92 |
| WH01 | SKU002 | BOX | 43 | 0 | 43 |