简介
本文件面向DouPHP电商系统的库存管理模块，聚焦于库存主表、库存变动记录表、仓库表、供应商表等核心数据模型与业务逻辑的表结构设计说明。结合现有代码与数据库脚本，梳理多仓库管理、库存预警、采购入库、销售出库、库存锁定释放、批次与保质期管理、库存盘点等高级功能的实现方案，并给出库存数据一致性保证、并发控制与性能优化建议，为电商平台开发者提供完整的库存数据模型参考。
项目结构
围绕库存相关的数据与流程，当前仓库中与库存直接相关的核心位置包括：
- 产品模块：商品主表包含库存字段，作为库存扣减的目标维度之一。
- 订单模块：订单及订单项包含“是否锁定库存”等字段，体现下单到支付的库存占用与释放机制。
- 系统表结构：汇总了全库表定义，便于检索与核对库存相关字段。
- 结账服务：在创建订单时根据配置决定是否锁定库存，体现库存锁定的触发点。
graph TB
A["产品模块<br/>dou_product"] --> B["订单模块<br/>dou_order / dou_order_item"]
B --> C["结账服务<br/>CheckoutService"]
C --> D["库存锁定/释放<br/>业务规则"]
D --> E["库存主表/明细表<br/>设计建议"]
D --> F["库存变动日志表<br/>设计建议"]
D --> G["仓库/供应商表<br/>设计建议"]核心组件
- 库存主表（设计建议）：用于按“仓库+商品+规格/批次”维度维护可用库存、锁定库存、安全库存等，支撑多仓库与精细化库存管理。
- 库存变动记录表（设计建议）：记录每次库存增减的来源、方向、数量、关联单号、操作人、时间戳等，确保可追溯与对账。
- 仓库表（设计建议）：管理仓库基础信息、地址、状态、归属等，支持多仓发货与分仓库存。
- 供应商表（设计建议）：管理供应商基础信息、结算方式、供货范围等，支撑采购入库与溯源。
- 产品表（现有）：dou_product 包含 stock 字段，作为商品维度的库存快照或默认仓库存；需与多仓库存表协同使用。
- 订单与订单项（现有）：dou_order_item 包含 stock_lock 字段，表示该订单项是否占用库存；结账流程中依据配置决定是否锁定。
架构总览
库存管理的整体架构以“订单驱动”为核心：下单时根据配置锁定库存，支付成功后扣减可用库存并生成变动日志；取消或超时未支付则释放锁定库存。多仓库场景下，库存锁定与扣减需精确到仓库维度，并结合批次与保质期进行先进先出或指定批次出库。
sequenceDiagram
participant U as "用户"
participant O as "订单服务"
participant C as "结账服务"
participant I as "库存服务(建议)"
participant DB as "数据库"
U->>O : 提交订单
O->>C : 调用结账流程
C->>DB : 写入订单/订单项
C->>I : 请求锁定库存(按仓库/批次)
I->>DB : 更新锁定库存/写变动日志
I-->>C : 返回锁定结果
C-->>U : 返回订单创建成功
Note over C,I : 若配置关闭库存锁定，则跳过锁定步骤详细组件分析
库存主表（设计建议）
- 目标：按仓库、商品、规格、批次维度维护可用库存、锁定库存、安全库存、过期库存等，支撑多仓管理与库存预警。
- 关键字段建议：
- 主键：id
- 仓库ID：warehouse_id
- 商品ID：item_id
- 规格ID：attr_id（可选，用于SKU粒度）
- 批次号：batch_no（可选，用于批次管理）
- 生产日期：produce_date（可选，用于保质期管理）
- 有效期至：expire_date（可选，用于保质期管理）
- 可用库存：available_qty
- 锁定库存：locked_qty
- 安全库存：safety_qty
- 在途库存：in_transit_qty（可选）
- 残次库存：damaged_qty（可选）
- 更新时间：updated_at
- 索引建议：
- (warehouse_id, item_id, attr_id, batch_no) 唯一索引，避免重复行
- (expire_date) 用于临期预警
- (warehouse_id, updated_at) 用于统计与审计
classDiagram
class Inventory {
+int id
+int warehouse_id
+int item_id
+int attr_id
+string batch_no
+date produce_date
+date expire_date
+int available_qty
+int locked_qty
+int safety_qty
+int in_transit_qty
+int damaged_qty
+datetime updated_at
}库存变动记录表（设计建议）
- 目标：记录所有库存变动的来源、方向、数量、关联单号、操作人、时间戳，确保可追溯与对账。
- 关键字段建议：
- 主键：id
- 仓库ID：warehouse_id
- 商品ID：item_id
- 规格ID：attr_id（可选）
- 批次号：batch_no（可选）
- 变动类型：type（如：purchase_in、sales_out、adjust、transfer、lock、unlock、expiry）
- 变动方向：direction（IN/OUT）
- 变动数量：qty
- 关联单号：ref_no（如采购单、销售单、调拨单、盘点单）
- 关联ID：ref_id（对应业务单ID）
- 操作人类型：operator_type（admin/work/system）
- 操作人ID：operator_id
- IP：ip
- 时间：created_at
- 索引建议：
- (warehouse_id, item_id, created_at) 查询常用
- (ref_no, ref_id) 快速定位来源
- (type, created_at) 审计与分析
flowchart TD
Start(["开始"]) --> CheckType{"变动类型"}
CheckType --> |采购入库| PurchaseIn["增加可用库存"]
CheckType --> |销售出库| SalesOut["减少可用库存"]
CheckType --> |锁定/释放| LockUnlock["调整锁定库存"]
CheckType --> |调拨| Transfer["跨仓移动库存"]
CheckType --> |盘点| Adjust["修正可用库存"]
CheckType --> |过期报废| Expiry["减少可用/转为残次"]
PurchaseIn --> Log["写入变动日志"]
SalesOut --> Log
LockUnlock --> Log
Transfer --> Log
Adjust --> Log
Expiry --> Log
Log --> End(["结束"])仓库表（设计建议）
- 目标：管理仓库基础信息与状态，支持多仓发货与分仓库存。
- 关键字段建议：
- 主键：id
- 名称：name
- 编码：code
- 地址：address
- 联系人：contact
- 电话：phone
- 状态：status（启用/禁用）
- 排序：sort
- 创建/更新时间：created_at/updated_at
- 索引建议：
- (code) 唯一索引
- (status) 筛选常用
classDiagram
class Warehouse {
+int id
+string name
+string code
+string address
+string contact
+string phone
+tinyint status
+int sort
+datetime created_at
+datetime updated_at
}供应商表（设计建议）
- 目标：管理供应商基础信息、结算方式、供货范围，支撑采购入库与溯源。
- 关键字段建议：
- 主键：id
- 名称：name
- 编码：code
- 联系人：contact
- 电话：phone
- 邮箱：email
- 结算方式：settlement（现金/月结/预付款）
- 状态：status
- 创建/更新时间：created_at/updated_at
- 索引建议：
- (code) 唯一索引
- (status) 筛选常用
classDiagram
class Supplier {
+int id
+string name
+string code
+string contact
+string phone
+string email
+string settlement
+tinyint status
+datetime created_at
+datetime updated_at
}多仓库管理
- 设计要点：
- 库存主表按 warehouse_id 分区，支持多仓独立库存。
- 调拨业务通过库存变动记录表记录跨仓移动，保持可追溯。
- 订单分配策略：根据收货地址、仓库能力、库存分布选择最优仓库。
- 业务流程：
- 下单锁定：按仓库维度锁定库存，避免超卖。
- 支付成功：从锁定库存扣减为可用库存，生成出库变动。
- 取消/超时：释放锁定库存，回滚占用。
- 调拨：源仓减少可用，目标仓增加可用，记录调拨变动。
flowchart TD
S["下单"] --> L["按仓库锁定库存"]
L --> P{"支付成功?"}
P --> |是| CO["扣减可用库存<br/>生成出库变动"]
P --> |否| R["释放锁定库存"]
CO --> T["可选：跨仓调拨"]
T --> A["源仓减少/目标仓增加<br/>记录调拨变动"]
R --> E["结束"]
A --> E库存预警
- 设计要点：
- 安全库存：当可用库存低于安全库存阈值时触发预警。
- 临期预警：基于有效期字段，提前N天预警即将过期库存。
- 报表与通知：生成预警清单，支持站内信、短信、邮件通知。
- 实现建议：
- 定时任务扫描库存主表，比较 available_qty 与 safety_qty。
- 扫描 expire_date，计算剩余天数，达到阈值时生成预警。
- 将预警记录写入预警表或通过消息队列推送。
flowchart TD
Scan["定时扫描"] --> CheckSafe{"可用库存 < 安全库存?"}
CheckSafe --> |是| WarnSafe["生成低库存预警"]
CheckSafe --> |否| Next["继续"]
Next --> CheckExpire{"即将过期?"}
CheckExpire --> |是| WarnExpire["生成临期预警"]
CheckExpire --> |否| End["结束"]
WarnSafe --> End
WarnExpire --> End采购入库
- 设计要点：
- 采购单：记录供应商、商品、数量、批次、生产日期、有效期等。
- 入库动作：增加可用库存，生成入库变动记录。
- 批次管理：记录批次号、生产日期、有效期，支持先进先出。
- 业务流程：
- 创建采购单 → 审核 → 入库 → 更新库存 → 记录变动。
- 支持部分入库与多次入库，累计数量与批次。
sequenceDiagram
participant P as "采购员"
participant PO as "采购单"
participant WH as "仓库"
participant INV as "库存服务"
participant LOG as "变动日志"
P->>PO : 创建采购单
PO->>WH : 审核通过
WH->>INV : 执行入库
INV->>LOG : 记录入库变动
INV-->>WH : 更新可用库存
WH-->>P : 入库完成销售出库
- 设计要点：
- 订单锁定：下单时根据配置锁定库存，防止超卖。
- 支付成功：扣减可用库存，生成出库变动。
- 取消/超时：释放锁定库存。
- 批次策略：优先出库临近过期批次（FEFO）或最早生产批次（FIFO）。
- 业务流程：
- 下单锁定 → 支付成功扣减 → 发货 → 记录出库变动。
- 取消/超时释放锁定。
sequenceDiagram
participant U as "用户"
participant O as "订单服务"
participant C as "结账服务"
participant I as "库存服务"
participant DB as "数据库"
U->>O : 提交订单
O->>C : 结账
C->>I : 锁定库存
I->>DB : 更新锁定库存/写变动日志
C-->>U : 订单创建成功
Note over C,I : 支付成功后扣减可用库存库存锁定释放
- 设计要点：
- 锁定标志：dou_order_item.stock_lock 表示是否锁定库存。
- 解锁条件：订单取消、超时未支付、售后退款等。
- 释放流程：校验锁定状态 → 更新锁定库存 → 记录释放变动。
- 业务流程：
- 下单锁定 → 支付成功扣减 → 取消/超时释放 → 记录释放变动。
flowchart TD
Start["开始"] --> CheckLock{"是否锁定库存?"}
CheckLock --> |是| Release["释放锁定库存"]
CheckLock --> |否| End["结束"]
Release --> Log["记录释放变动"]
Log --> End批次管理
- 设计要点：
- 批次号：每个入库批次赋予唯一批次号，关联生产日期与有效期。
- 出库策略：支持FIFO（先进先出）或FEFO（先到期先出）。
- 追溯：通过批次号追踪入库来源与出库去向。
- 业务流程：
- 入库：记录批次、生产日期、有效期、数量。
- 出库：按策略选择批次，扣减对应批次库存，记录变动。
flowchart TD
In["入库"] --> Batch["生成批次号<br/>记录生产日期/有效期"]
Batch --> Store["增加批次可用库存"]
Store --> Out["出库选择批次(FIFO/FEFO)"]
Out --> Deduct["扣减批次库存"]
Deduct --> Log["记录出库变动"]保质期管理
- 设计要点：
- 有效期字段：记录每批次的有效期，支持临期预警与自动报废。
- 预警策略：提前N天预警，超过有效期自动转入残次或报废。
- 报表：生成临期与过期库存报表，支持导出与通知。
- 业务流程：
- 入库：记录有效期。
- 监控：定时扫描临期与过期库存。
- 处理：预警、报废、调整库存。
flowchart TD
Scan["定时扫描"] --> Expire{"是否过期?"}
Expire --> |是| Scrap["转入残次/报废"]
Expire --> |否| Near{"是否临期?"}
Near --> |是| Warn["生成临期预警"]
Near --> |否| End["结束"]
Scrap --> End
Warn --> End库存盘点
- 设计要点：
- 盘点单：记录仓库、商品、批次、账面数量、实盘数量、差异原因。
- 差异处理：调整可用库存，记录盘点变动。
- 审计：盘点过程留痕，支持复核与审批。
- 业务流程：
- 创建盘点单 → 实地盘点 → 录入实盘数量 → 计算差异 → 审批 → 调整库存 → 记录变动。
sequenceDiagram
participant W as "仓库"
participant INV as "库存服务"
participant LOG as "变动日志"
W->>INV : 创建盘点单
W->>INV : 录入实盘数量
INV->>INV : 计算差异
INV->>LOG : 记录盘点调整变动
INV-->>W : 调整完成依赖关系分析
- 产品表与库存：dou_product.stock 可作为默认仓库存或全局库存快照，需与多仓库存表协同。
- 订单与库存：dou_order_item.stock_lock 控制是否锁定库存；结账流程依据配置决定是否锁定。
- 变动日志与对账：所有库存变动需记录到变动日志表，支持对账与审计。
- 仓库与供应商：仓库表与供应商表为库存主表的关联维度，支撑多仓与采购入库。
graph LR
P["dou_product"] --> I["库存主表(建议)"]
O["dou_order_item"] --> I
I --> L["库存变动日志(建议)"]
W["仓库表(建议)"] --> I
S["供应商表(建议)"] --> L性能考虑
- 索引优化：
- 库存主表：按仓库、商品、规格、批次建立复合唯一索引，避免重复行。
- 变动日志表：按仓库、商品、时间建立索引，提升查询效率。
- 订单表：已有状态与时间索引，利于状态流转查询。
- 事务与锁：
- 库存锁定与扣减使用数据库事务，确保一致性。
- 高并发场景使用行级锁或乐观锁，避免超卖。
- 异步与缓存：
- 库存变动日志可异步写入，降低主流程延迟。
- 热点商品库存可使用缓存，但需与数据库保持一致性。
- 批量操作：
- 盘点、调拨等批量操作采用分批提交，避免长事务。
- 监控与告警：
- 监控库存变更失败率、事务超时、死锁等指标。
- 设置库存异常阈值告警，及时干预。
故障排查指南
- 常见问题：
- 超卖：检查库存锁定与扣减是否在同一事务中，是否存在并发竞争。
- 库存不一致：核对变动日志与库存主表，查找缺失或重复记录。
- 锁定未释放：检查订单状态机，确认取消/超时逻辑是否正确触发释放。
- 批次错误：核对批次号与有效期，确认出库策略是否符合预期。
- 排查步骤：
- 定位订单与订单项，确认 stock_lock 状态。
- 查询库存变动日志，核对变动类型与数量。
- 检查仓库与供应商关联，确认多仓与采购入库逻辑。
- 查看定时任务与告警，确认预警与报废逻辑。
结论
本文件基于DouPHP现有代码与数据库脚本，提出了库存主表、库存变动记录表、仓库表、供应商表的设计建议，并结合多仓库管理、库存预警、采购入库、销售出库、库存锁定释放、批次与保质期管理、库存盘点等高级功能，给出了完整的实现方案与技术建议。通过合理的表结构设计与业务流程控制，可有效保障库存数据的一致性、可追溯性与高性能，为电商平台开发者提供可靠的库存数据模型参考。
附录
- 相关表结构参考：
- 产品表：包含库存字段，作为商品维度的库存快照或默认仓库存。
- 订单与订单项：包含锁定库存标志，体现下单到支付的库存占用与释放机制。
- 系统表结构：汇总全库表定义，便于检索与核对库存相关字段。