库管

今天要做什么

按节拍守账实：每天过昨夜流水与红色预警，每周循环盘点 + 过期批次，每月全仓盘点配合财务月结。

每日（开班 ~15 分钟）

1. 打开库存总览，扫低于「补货点」的红标行，确认是否需要补货。
2. 翻库存流水：核对昨夜 / 早班的「入库」「出库」「调拨」「调整」四类记录，看每条引用的上游单据类型是否对得上。
3. 处理红色补货预警：点「生成采购单」转一张草稿采购单给采购。
4. 推进在途调拨：昨日发起、今日应到仓的「在途」调拨单点「完成入库」。
5. 扫销售预留池：状态为「可用」的预留对应订单该备货了就按 FIFO 分配批次。

每周

• 循环盘点：对高周转 / 贵重 SKU 新建「草稿」盘点单，录入实盘数后提交，系统自动生成差异调整流水。
• 过期预警：看 30 天内到期批次清单，批量走异常出库（「赠品」 / 「内部领用」 / 「过期报废」）。
• 序列号抽盘：核对在库序列号与实物一致，状态为「在库」才可出。

每月

• 全仓盘点：每仓一张盘点单，提交后在估值报表核对账面价值变动。
• 配合财务月结：冻结期内不再做库存调整，差异留到下月走反向流水。
• 账实差异报告：按仓 / 按品类出汇总，交财务。

权限红线（先看这 5 条）

• 不能跨账套调拨——源仓与目的仓必须同属一个账套，否则系统拦截。
• 盘点中的仓位锁定——同一仓不能同时存在两张「草稿」盘点单；状态为「已提交」的盘点不能改项，只能新建反向盘点。
• 库存为正的批次 / 已售的序列号不能删——批次可用数量 > 0 或序列号状态为「已售」时直接删会被拒，必须走异常出库。
• 月结冻结期内禁手工调整——冻结期间做库存调整会破坏上月账面，差异留到下月反向入账。
• 销售 / 采购 / 会计的写入权限不给——销售订单、采购订单、发票等单据库管只读；库存流水只能通过上游单据触发，不能直接写库存流水表。

Quickstart — 日常核心任务

2.1 采购到货入库核对

采购在收货模块确认到货后，系统自动生成一条「入库」流水；库管负责核对数量、批次与 QC 状态是否与实物一致。

1. 打开库存流水页，按类型筛选「入库」。（见图 ①）
2. 逐行核对：产品、数量、仓库是否与采购单 / 送货单一致。
3. 若仓库开启了「QC 冻结」，批次会自动进入「隔离中」——等 QC 放行前不可出库。
4. 批次物料点进批次列表，确认新批次的效期、单位成本、批号都已录入。（见图 ②）
5. 若数量对不上：先跟采购核实是否补发，再按差异走异常单（「损坏」 / 「质检不合格」），不手工调整。

何时不该做：对批次物料，在上游收货单未确认前不要先建批次——会出现批次和收货流水对不上的孤儿记录；对 QC 仓的货，未放行前别用「库存调整」绕过，「隔离中」状态存在就是让你等 QC 结论。

观测信号：

1. 流水页顶部出现新的「入库」行，引用对应收货单号。
2. 库存总览对应 SKU 的「账面库存」列数字增加。
3. 若 QC 开启，批次列表新批次状态显示「隔离中」徽标。

技术追溯：stock_movements.movement_type='receipt'、stock_movements.reference_type='goods_receipt'；stock.quantity 等额增加；若 qc_hold_enabled=true，stock_batches.status='hold'。

系统动作：getStockMovements、getBatches、createBatchAction、updateBatchAction

2.2 手工库存调整（单条盘盈 / 盘亏）

巡检发现账实不符、差异小（单条、数量 < 10）、不想开正式盘点单时用此入口。正式盘点见 2.4。

1. 库存总览定位到目标 SKU + 仓库行，右侧点「调整」图标打开弹窗。（见图 ①）
2. 选「增加」或「减少」；填数量（小数点后 3 位）；填调整原因（必填，审计要查）。（见图 ②）
3. 点「提交」——系统写一条「调整」流水，账面库存同步更新。
4. 差异 > 10 件或涉及多 SKU：关闭弹窗，改走 2.4 正式盘点。

何时不该做：月结冻结期禁止调整——冻结期做库存调整会串上月账面，差异必须等解冻后走反向流水。差异数量大、涉及多 SKU 别走手工调整——无留痕的批量调整被审计会要求每条都找原因，走正式盘点才有盘点单号做审计轨迹。

观测信号：

1. 库存总览该行「账面库存」列数字更新。
2. 流水页最顶部出现一条「调整」记录（绿色为入、红色为出），原因字段有值。
3. 估值报表的账面价值按移动平均 / FIFO 重新计算。

技术追溯：stock_movements.movement_type='adjustment'，quantity 可正可负；stock.quantity 同步更新；触发 revalidatePath('/dashboard/inventory/valuation')。

系统动作：adjustStock、adjustStockById

2.3 多仓调拨（两步式在途）

总仓 → 展厅、跨城分仓补货。两步式：发起时源仓立即扣，货到目的仓再点「完成入库」；中间状态为「在途」。

1. 调拨列表右上点「新建调拨」。（见图 ①）
2. 弹窗选源仓 + 目的仓；两仓必须同一账套。（见图 ②）
3. 加行：每行选产品 + 数量（可选单位成本用于账面估值）。
4. 点「发起调拨」——源仓立即扣减，生成一条「出库」流水，状态变「在途」。
5. 货到目的仓后，回列表找该单点「完成入库」——再写一条「入库」流水，状态推到「已完成」。
6. 若途中货丢 / 单据作废，点「取消」回滚到源仓（仅「在途」可撤）。

何时不该做：同仓内移库别用此功能——两步式会多生成成对流水，污染账面；同仓移位走「库存调整」或库位管理（如启用）。跨账套调拨会被系统拦截——源仓与目的仓不在同一账套直接报错。已「已完成」的调拨不能撤——货已入目的仓，必须反向发一张新调拨。

观测信号：

1. 调拨列表顶部出现新行，状态徽标从「在途」推进到「已完成」。
2. 流水页按引用类型「调拨单」可查到成对的出 / 入流水。
3. 库存总览源仓对应 SKU 账面减少、目的仓等额增加（完成后）。

技术追溯：stock_transfers.status ∈ {in_transit,completed,cancelled}；stock_transfer_items.out_movement_id / in_movement_id 成对；stock_movements.movement_type='transfer'。

系统动作：initiateTransferAction、completeTransferAction、cancelTransferAction

2.4 循环 / 全仓盘点

每周对高周转 SKU 抽盘、每月对每仓全盘。流程：建「草稿」盘点单 → 录入实盘数 → 提交，系统把差异写入「调整」流水。

1. 盘点列表右上点「新建盘点」。（见图 ①）
2. 弹窗选仓库、盘点日、用途（如「月末全盘」）、备注。（见图 ②）
3. 提交后进盘点详情，按产品加行——系统自动带出账面数。（见图 ③）
4. 逐行录入实盘数；差异数自动算出。
5. 全部录完点「提交」——状态变「已提交」，每条差异行生成一条「调整」流水。
6. 录错想重来：仅「草稿」可「取消」或「删除」；「已提交」后只能新建反向盘点。

何时不该做：同仓已有「草稿」盘点时别再建——后端会拦截并提示「已有草稿」，先处理旧草稿再说。盘点未交完别点「提交」——提交后不可改行，漏盘的 SKU 只能新建反向盘点补差。

观测信号：

1. 盘点列表顶部出现新行，状态从「草稿」推到「已提交」。
2. 每条差异行在流水页生成一条「调整」记录，引用该盘点单号。
3. 估值报表的账面价值同步重算。

技术追溯：stock_reconciliations.status ∈ {draft,submitted,cancelled}；stock_reconciliation_items.differenceQty / differenceValue；stock_movements.movement_type='adjustment'。

系统动作：createReconciliationAction、addReconciliationItemAction、removeReconciliationItemAction、submitReconciliationAction、cancelReconciliationAction、deleteReconciliationAction

2.5 批次建档与过期清理

有效期敏感品类（板材、胶水、化工辅料）入库必须落批次，并定期扫 30 天内到期清单做异常出库。

1. 批次列表右上点「新建批次」。（见图 ①）
2. 弹窗选产品 + 仓库，填数量、生产日期、效期；批号留空则系统自动生成 BATCH-YYYYMM-NNNN。
3. 若有 QC 单关联，在批次详情关联对应的质检单。
4. 扫到期：切「即将过期」视图，看 30 天内到期批次。
5. 过期批次按用途分流：样品 → 走「样品出库」异常单、内部领用 → 走「内部领用」、作废 → 走「过期报废」；提交异常单走审批。

何时不该做：批次可用数量 > 0 时不能删——系统直接拒绝。删前先把库存走异常出库清零，再删；不然审计会找不到这批货去向。效期字段别漏填——漏填后过期预警扫不出来，实物过期客户退货才发现已晚。

观测信号：

1. 批次列表顶部出现新批次，批号 BATCH-YYYYMM- 前缀。
2. 「即将过期」视图把 30 天内到期项高亮。
3. 批次状态徽标按「可用 → 隔离中 → 已放行 → 已耗尽」推进。

技术追溯：stock_batches.batch_number、available_quantity、status ∈ {active,hold,released,depleted}；stock_batches.expiry_date。

系统动作：createBatchAction、updateBatchAction、updateBatchFromFormAction、deleteBatchAction、getExpiringBatchesAction

2.6 序列号批量录入 / 更新

贵重单件（家具成品、电子组件）需单件追溯——入库建序列号、出库标「已发货」、售后按序列号查保修期。

1. 序列号列表右上点「批量导入」。（见图 ①）
2. 弹窗选产品 + 仓库；粘贴多行序列号（每行一个或逗号分隔）。
3. 点提交——系统批量建为「在库」状态。
4. 改仓位或保修期：单行点编辑；售出时由销售发货流程自动标「已发货」。

何时不该做：序列号处于「已售」 / 「已发货」状态不能直接删——售后还要查保修，删了丢追溯。要作废已售单品走「客户退货」异常单回收，不硬删。

观测信号：

1. 序列号列表总数增加 N 条，状态全为「在库」。
2. 按产品筛选后每条序列号的仓库、保修期、关联批次字段都有值。
3. 销售发货后状态自动从「在库」→「已预留」→「已发货」。

技术追溯：serial_numbers.serial_no、serial_numbers.status ∈ {in_stock,reserved,sold,shipped,returned}；serial_numbers.warranty_until。

系统动作：createSerialNumberAction、createBulkSerialNumbersAction、updateSerialNumberAction、deleteSerialNumberAction

2.7 补货预警 → 生成采购单

早班看红色预警（账面库存 ≤ 补货点），按建议供应商一键生成草稿采购单交给采购。

1. 补货预警页按「高优先级」过滤，看红色清单。（见图 ①）
2. 勾选要补的多条预警——同供应商的可一次合单。
3. 点「生成采购单」。（见图 ②）
4. 弹窗里系统按产品→供应商映射推荐供应商，必要时改选。
5. 确认后生成一张来源标记「补货预警」的草稿采购单，交给采购继续下单流程。
6. 需求不急：保留预警不转单；AI 辅助决策点「预测」看下周 / 下月缺货趋势。

何时不该做：同一 SKU 已有未结采购单时别重复生成——采购方会拒单，白占库管时间；先去采购列表确认已有单的到货日再决定。低优先级预警可延后——按红 → 黄 → 绿排，每天最多处理 3-5 条红，不一股脑生成拉长付款周期。

观测信号：

1. 采购模块出现新草稿采购单，来源标记「补货预警」。
2. 被勾选的预警条目从清单消失（或标「已转单」）。
3. 采购收到企微 / 邮件推送「新补货采购单」。

技术追溯：purchase_orders.source='reorder_alert'；stock.quantity ≤ stock.reorder_point（客户端过滤，PostgREST 不支持列比较）。

系统动作：fetchReorderAlerts、fetchSuppliersForAlerts、createPurchaseOrderAction、getForecastAction、getAIForecastAction、getReorderRecommendationsAction、getInventoryHealthAction

2.8 库存异常单（损坏 / 赠品 / 报废 / 客退）

客诉退货、展厅样品、生产报废、搬运损坏、盘盈 —— 凡走审批的非正常出入库都开异常单，留完整审计链。

1. 异常单列表右上点「新建异常」。（见图 ①）
2. 弹窗选异常类型（损坏 / 客户退货 / 内部领用 等）；系统按类型自动推断方向（盘盈 / 客户退货 → 入库，其余默认出库）。
3. 选仓库、填备注，提交后进详情页加明细行：产品、数量、批次（可选）。
4. 点「提交」→ 审批人「批准」或「驳回」→ 批准后点「完成」真实扣减 / 入库。
5. 草稿态发现填错：直接「删除」；已提交用「撤销」；已完成不可撤。

何时不该做：未审批通过别点「完成」——完成就真实扣库存，绕过审批会让财务的报废 / 赠品成本无法归集。已「已完成」不可改——要纠正只能反向再开一张（用「盘盈」类型做回补）。

观测信号：

1. 异常单列表顶部出现新行，状态徽标按「草稿 → 已提交 → 已批准 → 已完成」推进。
2. 完成后流水页生成一条「调整」（或对应方向的流水），引用异常单号。
3. 库存总览对应 SKU 账面按入库 / 出库方向加 / 减。

技术追溯：stock_exceptions.status ∈ {draft,submitted,approved,rejected,completed,cancelled}；exception_type ∈ {damage,theft,found,sample,return_to_supplier,customer_return,production_scrap,quality_reject,gift,internal_use,expired,other}；direction ∈ {in,out}。

系统动作：createExceptionAction、addExceptionItemAction、removeExceptionItemAction、submitExceptionAction、approveExceptionAction、rejectExceptionAction、completeExceptionAction、cancelExceptionAction、deleteExceptionAction

上下游交接契约

库管是账实一致的最后关口。每笔上游动作要核、每笔下游动作要对——字段缺失的后果都落在库管台账上。

异常回滚

误操作不要直接改 DB。按下表选对应入口按业务规则回滚——库存流水留审计轨迹比「干净账面」重要。

进阶功能

估值报表（Moving Average / FIFO 切换） ▸

月末全盘后在估值报表核对账面价值。可按仓 / 按品类汇总，配合财务月结取数；估值法切换影响下月成本结转，必须与财务同步。

入口：/dashboard/inventory/valuation。系统动作：getValuationReport、getWarehouseValuation、getCategoryValuation、updateValuationMethodAction、getCurrentValuationMethod、getLowValueProducts、getHighValueProducts。

仓库 CRUD 与默认仓设置 ▸

新建 / 停用仓库、切换默认仓（影响新建流水、预留、发货默认值）。仅管理员或库管主管执行，新仓上线前必须确认库位 / QC 配置。

入口：/dashboard/inventory/warehouses。系统动作：createWarehouse、updateWarehouse、updateWarehouseFromForm、deleteWarehouse、setDefaultWarehouseAction。

相关业务场景

库管参与 6 大场景中的 5 条——是销售 / 采购 / 生产 / 财务的账实接口；「报销审批流」作为申请人。

1. 标准成单流（询盘 → 报价 → 订单 → 发货 → 开票）： 库管在订单确认后管预留；销售创建发货单时按预留扣减；序列号 / 批次按 FIFO 分配。 → 场景详解
2. 定制家具项目流： 库管管原料入库（板材 / 五金的批次建档），生产领料走 internal_use；成品入库再做序列号建档。 → 场景详解
3. 回款流：库管不参与——由销售 / 出纳处理。库管只关心销售侧的预留与发货扣减是否按时完成。 → 场景（了解即可）
4. 采购付款流（收货入库侧）： 库管验收 + 触发「入库」流水，异常走「损坏」 / 「质检不合格」类型异常单；收货数量与采购单对不上要通知采购。 → 场景详解
5. 月结流： 库管牵头全仓盘点 + 估值报表，把账实差异报告交财务；冻结期内禁手工调整，差异留下月反向。 → 场景详解
6. 报销审批流：库管作为申请人走 /dashboard/expenses（搬运费 / 仓库杂支报销），非库管核心动作——不在 Quickstart 范围。 → 场景（作为申请人）

外部协作入口

• /dashboard/purchasing/goods-receipts — 采购收货单，库管验收入口上游。
• /dashboard/sales/delivery-notes — 销售发货单，按预留扣减库存的下游。
• /dashboard/export/shipments — 物流装箱与报关，出货后接力。
• /dashboard/accounting — 会计月结 / 存货估值取数。
• /dashboard/wecom — 企微推送（红色预警、盘点提醒、异常审批）配置。
• /dashboard/reports — 库存 / 周转 / 账龄报表，月会用。
• /dashboard/manual — 系统内置使用手册（补充参考）。

权限与范围

看得到什么（RLS 边界）

• 当前 organization_id 下的所有 stock / stock_movements / stock_batches / stock_transfers / stock_reconciliations / stock_exceptions / stock_reservations / serial_numbers / warehouses。
• 当前 book_id 下的库存数据——多账套下账本隔离，切账套后数据变；调拨不允许跨账套。
• 补货预警（reorder_alerts）按仓 + SKU 维度，客户端过滤 stock.quantity ≤ stock.reorder_point（PostgREST 不支持列比较）。
• 采购 PO / 销售订单 / 发票 只读——写入权限分别由采购 / 销售角色持有。

核心概念

• book_id — 账套隔离键。所有库存相关表都带 book_id，切账套后数据完全隔离；调拨源 / 目的仓必须同账套。
• organization_id — 租户隔离键。多租户场景下跨组织数据通过 RLS 隔离。
• 库存原子 RPC：adjust_stock_atomic、transfer_stock_atomic —— 所有 mutation 必经这两个 RPC，保证并发下数据一致。
• 库存状态机：stock_movements.movement_type ∈ {receipt, shipment, adjustment, transfer, receipt_reversal}；流水只增不改、不删。
• 估值法：组织级配置 moving_average（移动平均）/ fifo（先进先出），影响月末成本结转，切换必须与财务同步。

术语表

账面库存 book_qty

stock.quantity（系统记录的数量）

可用库存 available_qty

stock.quantity - stock.reserved_qty（前端计算列）

预留库存 reserved_qty

stock.reserved_qty（销售订单 / 调拨锁定）

在途 in_transit

stock_transfers.status='in_transit'（源仓已扣、目的仓未加）

补货点 reorder_point

stock.reorder_point（触发红色预警阈值）

库存流水

stock_movements.movement_type（receipt | shipment | adjustment | transfer | receipt_reversal）

调拨单号

stock_transfers.transfer_reference

盘点单号

stock_reconciliations.reconciliation_no；状态 draft | submitted | cancelled

异常单 enum

damage | theft | found | sample | return_to_supplier | customer_return | production_scrap | quality_reject | gift | internal_use | expired | other

异常状态机

draft → submitted → approved / rejected → completed（或 cancelled）

批次 batch

stock_batches.batch_number（BATCH-YYYYMM-NNNN）；状态 active | hold | released | depleted

序列号 serial_no

serial_numbers.serial_no；状态 in_stock → reserved → sold / shipped → returned

库位 warehouse

warehouses.id（当前仅支持仓库级，无库位细分字段）

估值法 valuation_method

moving_average | fifo（组织级配置）

QC 冻结 qc_hold_enabled

warehouses.qc_hold_enabled；开启后批次入库默认 status='hold'

预留状态

stock_reservations.status ∈ {active, fulfilled, released}

账套隔离键

book_id（所有库存表）

原子 RPC

adjust_stock_atomic、transfer_stock_atomic（所有库存 mutation 必经）

常见问题