库存确认契约

实现圣经。业务单确认如何写 stock_ledgers、如何更新 stocks，只在本文定义一次；各模块写「确认见本文 §矩阵」。

重量单位：库内 kg；界面可按斤展示（1 kg = 2 斤）。

真源

  1. 业务头表是业务真源（采购/订单/加工/调拨/降级/盘点，或精简 stock_documents）。
  2. 库存写入唯一路径：确认（或调拨发出/收货）→ 写 stock_ledgers → 同步 stocks。
  3. 流水必填：source_type、source_id、source_no。
  4. 禁止：绕过流水直接改 stocks；确认后静默改已入账流水。

流水类型（全集）

type direction 说明
opening_in in 期初
purchase_in in 采购入库
process_out out 加工投入出库
process_in in 加工产出入库
sale_out out 销售/买断出库
return_in in 退货/拒收入库
loss_out out 报损/加工损耗出库
transfer_out out 调拨发出
transfer_in in 调拨收货
downgrade_out out 降级源出
downgrade_in in 降级目标入
split 成对 in/out 同 SKU 拆包装
merge 成对 in/out 同 SKU 合包装
check_adjust in 或 out 盘点差异

不设 in_transit_out / in_transit_in。在途只体现在 stock_in_transits 行。

冲销时：写反向流水（原入则出、原出则入），type 仍用业务类型，用 source_* 指向冲销动作（建议 source_no 带原单号 + -R 或单独记 reversal_of_ledger_id）；禁止改旧流水行。

确认事件矩阵

事件 source 流水 结存
采购确认 purchases 每行 purchase_in 入库仓 +
销售/买断确认 orders（external/buyout） 每行 sale_out 出库仓 −
退货/拒收确认 orders（return/reject） 每行 return_in 入库仓 +
财务驳回采购 purchases 冲销该单全部 purchase_in（反向出） −
财务驳回销售/买断 orders 冲销该单全部 sale_out（反向入） +
财务驳回退货/拒收 orders 冲销该单全部 return_in（反向出） −
加工确认 process_orders process_out + process_in；可选 loss_out ±
调拨发出 / 收货 stock_transfers transfer_out / transfer_in + 在途行 ±
降级确认 stock_downgrades downgrade_out + downgrade_in 守恒
盘点确认 stock_checks check_adjust 调至实盘
期初 / 报损 / 拆合 stock_documents opening_in / loss_out / split/merge 对应

销售 V1：确认即 sale_out，不做销售在途。

谁拥有头表

场景 头表 stock_documents
采购 / 销售 / 加工 各自业务表 否
调拨 / 降级 / 盘点 各自头表 否
期初 / 报损 / 拆合 stock_documents 是

硬约束

  1. 幂等：同一业务单同一动作（确认 / 驳回冲销）只成功一次。
  2. 出库不得负库存（V1 默认禁止超卖）。
  3. 唯一结存键：stocks (warehouse_id, sku_id, unit)。
  4. 重量守恒：拆合、降级出入重量一致；加工投入 ≈ 产出 + 损耗（可配容差）。
  5. 冲销：禁止改旧流水。财务驳回采/销 = 本矩阵冲销行 + 单据回 draft。业务主动作废已确认单同样走冲销，不另开「静默取消」。
  6. 标称重量不可代替实重。

通用状态机

采购 / 销售（含退货拒收）

draft → confirmed     # 写矩阵确认行；归档，业务不可改
confirmed → draft     # 仅财务驳回：先冲销库存，再回草稿（必填意见）
draft → cancelled     # 从未入账
  • confirmed：不可改件数/重量/SKU/仓/金额等影响流水或归档口径的字段。
  • draft：可改；销售扣损、调整行、采购扣损结果均在此阶段完成后再确认。
  • 财务侧「结算完成」用 finance_settled_at 等标记，不是业务再改单的窗口。

调拨

draft → shipped → received；draft → cancelled。发出后不可直接 cancelled。

唯一约束（实现必建）

表 约束
stocks unique (warehouse_id, sku_id, unit)
sku_units unique (sku_id, unit) 未删除行；每 SKU 至多一个 is_base
product_user unique (product_id, user_id)
stock_snapshots unique (warehouse_id, sku_id, snapshot_date)
purchase_order_links unique (purchase_id, order_id)
单号 purchase_no / order_no / process_no / transfer_no / downgrade_no / check_no / document_no / claim_no / request_no / expense_no / invoice_no 各自全局唯一（含已软删）

成本口径（V1）

stocks 不存单位成本。盈亏按单据金额 + 已确认业务费用单（可负）+ 已批报销 + 报损等；见规则 17。费用按采购重量分摊只影响核算展示，不写存货成本层。

验收标准

  • [ ] 确认与财务驳回冲销均有明确流水动作；幂等。
  • [ ] 无 in_transit_* 流水。
  • [ ] 采/销 confirmed 后业务不可改；驳回后回 draft 可再确认。