2 Commits

Author	SHA1	Message	Date
yueli	f702a70fe5	fix(borrow): 借出只冻结可用数，不再扣减实物库存 ... 问题 ---- 上一轮库存预占改造（b57c21a）把借库执行改用了 restore_then_deduct()， 而该函数是按**出库语义**设计的（物品永久离开仓库），会同时扣减 available_quantity 与 stock_quantity。借库是可逆的，于是产生两个缺陷： 1) 借出再归还后，实物库存永久少一份 初始 (stock=20, avail=20) 借出5 (stock=15, avail=15) 归还5 (stock=15, avail=20) ← 实物没回来，丢了 5 2) 借出后转报废会重复扣减 scrap_borrow 的注释明确写着「扣减总库存（该物品确认损失）； 可用库存已在借出时冻结，无需重复扣」—— 它假设借出**没动实物**。 借出已扣 stock 后，转报废再扣一次： 借出5 stock=15 → 转报废 stock=10（正确应为 15） 修复 ---- restore_then_deduct 增加 deduct_stock 参数： 出库 deduct_stock=True （默认）—— 可用数、实物数同时扣 借库 deduct_stock=False —— 只冻结可用数，实物数不动 ★ 这是**恢复原有设计**，不是新设计。git 历史显示从最初的 04ee938 借库逻辑实现 起，历经 7ef22a3 / 83b3db6 / b79b0f9 / 2556b77 / 1527d55 六次提交，一直是： stock.available_quantity = float(stock.available_quantity) - qty （只减可用，不动实物）。b57c21a 把它替换掉了。 盘点的差异计算也印证了该口径的正确性： adjusted_stock_qty = stock_quantity - 借出未还 diff_qty = 实盘数 - adjusted_stock_qty 这段逻辑要求 stock_quantity **包含**借出未还的实物，否则会重复扣减。 最终语义 -------- stock_quantity = 账面实物总数（含借出未还） available_quantity = 实际可取用数 出库申请(预占) — available ↓ 出库执行 stock ↓ available ↓ 借库申请(预占) — available ↓ 借库执行 — available ↓ 借库归还 — available ↑ 借库转报废 stock ↓ — 实测（stock, available） ------------------------ 借还循环：初始(20,20) → 借出5(20,15) → 归还5(20,20) 完全可逆 出库： 预占4(20,16) → 执行(16,16) 实物确实减 转报废： 借出3(20,17) → 转报废(17,17) 实物减一次，不重复	2026-09-11 09:39:20 +08:00
yueli	b57c21a4cd	feat(inventory): 库存预占生命周期，消除出库/借库超卖 ... 问题：库存超卖 -------------- 改造前出库/借库申请只记录「要什么、要多少」，不绑定具体库存行， 真正的 available_quantity 扣减发生在执行阶段。于是多张申请可以同时 claim 同一批货，等到工人拿扫码枪时才发现货已被别人领走。 生命周期（三阶段） ------------------ 提交申请（预占） reserve_for_items() 用分配器把需求落到具体库存行，立即扣减 available_quantity， 并把 (stock_id, source_table, allocated_qty, reserved) 写回 items_json。 驳回（释放） release_reserved() 遍历 items_json 把预占量还回池子，避免货被永不执行的单永久占住。 扫码执行（覆盖） verify_scanned() + restore_then_deduct() 校验实扫身份/数量未超批准范围 → 释放全部预占 → 对实扫批次 同时扣减 available_quantity 与 stock_quantity。 身份键：base_id 主键 + SKU 兜底（重要设计决策） ----------------------------------------------- 本系统中 SKU 是**批次级**编号：同一 base_id 下每个入库批次各有不同的 SKU（实测 stock_buy 有 183 个物料是多批次的，如 base_id=2405 下有 0000001685 与 0000001974 两个 SKU）。 若以 SKU 作为身份主键，「申请时锁定 A 批、工人现场改扫 B 批」会被判为 身份不符而拒绝 —— 恰好否定了「物理覆盖」这个核心能力。 故改用 base_id（物料级、跨批次稳定，spec_model 由其唯一确定）， 历史数据无 base_id 时降级为 (name, spec_model)。 可用量校验按物料汇总，而非按单批次 ---------------------------------- 开发中修正的一处缺陷：若逐行要求「该批次可用量 >= 该批次扫码量」， 工人改扫小批次时会被误拒。例如本单预占 A 批 5 件，改扫 B 批 2 件 + C 批 3 件，B 批自身只有 2 件可用，逐行校验即失败。实际这 5 件都是本单 锁定的货，理应允许。现按物料汇总校验可用量，按行校验实物库存。 改动文件 -------- · 新增 app/services/inventory_reservation.py（通用服务层） · outbound_service.create_request —— Phase 1 预占 · outbound_service.approve(reject) —— Phase 2 释放 · outbound_service.create_outbound_batch —— Phase 3 覆盖（移除原逐行扣减） · borrow_service.submit_approval —— Phase 1 · borrow_service.approve(reject) —— Phase 2 · trans_service.execute_dispatch —— Phase 3，并用统一身份键替换 原有的 (name, spec_model) 字符串匹配 实测（真实 HTTP 全链路） ------------------------ 初始 available=10 ① 提交申请(需5) → 200，available 10→5 预占生效 ② 审批通过 → available 仍为 5 预占保留 ③ 扫码执行(改扫另一批次 4 件) → 200 原批次恢复满额、实扫批次扣减(0,0)，available=6, stock=6 单场景验证：预占 A 批改扫 B 批放行；驳回后可用量完全恢复； 扫其他物料被拒；批准 6 扫 8 被拒。	2026-09-10 14:59:10 +08:00