10 KiB
库存余额、批次、流水、调整、盘点
约定见 00-conventions.md。数量桶的业务含义见 01-er-overview.md 与 05-inventory.md。Phase 1 锁定，Phase 7、8 写迁移。
冻结、锁定不单独建单据表。冻结是可用与 hold_qty 的对转；订单锁定是可用与 reserved_qty 的对转，锁定对象记在 wms_outbound_allocation 和流水的 biz_no 上。
wms_batch 批次
用途：批次属性。不管理批次的库存使用 batch_no = ''，不写本表。
| 字段 | 类型 | 可空 | 默认 | 说明 |
|---|---|---|---|---|
| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
| tenant_code | VARCHAR(32) | N | 租户编码 | |
| customer_code | VARCHAR(64) | N | 货主 | |
| sku_code | VARCHAR(64) | N | SKU 编码 | |
| batch_no | VARCHAR(64) | N | 批次号，禁止空字符串 | |
| supplier_code | VARCHAR(64) | Y | 供应商 | |
| mfg_date | DATE | Y | 生产日期 | |
| expiry_date | DATE | Y | 失效日期 | |
| created_at | TIMESTAMP | Y | ||
| updated_at | TIMESTAMP | Y |
索引：
| 名称 | 类型 | 字段 | 支撑的查询 |
|---|---|---|---|
| uk_tenant_customer_sku_batch | UNIQUE | (tenant_code, customer_code, sku_code, batch_no) | 定位批次 |
| idx_tenant_sku_expiry | INDEX | (tenant_code, sku_code, expiry_date) | 临期查询 |
关联：wms_inventory.batch_no。首次收货写入，之后只允许补空缺的日期，不改已有批次号。
并发 / 审计：无软删除。属性变更写 wms_operation_log。
wms_inventory 库存余额
用途：某一货主、仓库、库位、SKU、批次上的数量结果。余额是结果，不是事实。
| 字段 | 类型 | 可空 | 默认 | 说明 |
|---|---|---|---|---|
| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
| tenant_code | VARCHAR(32) | N | 租户编码 | |
| customer_code | VARCHAR(64) | N | 货主 | |
| warehouse_code | VARCHAR(32) | N | 仓库编码 | |
| location_code | VARCHAR(64) | N | '' | 库位；在途为空字符串 |
| sku_code | VARCHAR(64) | N | SKU 编码 | |
| batch_no | VARCHAR(64) | N | '' | 批次；无批次为空字符串 |
| available_qty | DECIMAL(16,4) | N | 0 | 可用 |
| reserved_qty | DECIMAL(16,4) | N | 0 | 预占 |
| picked_qty | DECIMAL(16,4) | N | 0 | 已拣 |
| hold_qty | DECIMAL(16,4) | N | 0 | 冻结 |
| damaged_qty | DECIMAL(16,4) | N | 0 | 残损 |
| in_transit_qty | DECIMAL(16,4) | N | 0 | 在途 |
| version | INT UNSIGNED | N | 0 | 乐观锁，随数量更新递增 |
| created_at | TIMESTAMP | Y | ||
| updated_at | TIMESTAMP | Y |
索引：
| 名称 | 类型 | 字段 | 支撑的查询 |
|---|---|---|---|
| uk_inventory_grain | UNIQUE | (tenant_code, customer_code, warehouse_code, location_code, sku_code, batch_no) | 定位余额行 |
| idx_tenant_wh_sku | INDEX | (tenant_code, warehouse_code, sku_code) | 仓库内某 SKU 库存 |
| idx_tenant_customer_sku | INDEX | (tenant_code, customer_code, sku_code) | 货主下某 SKU 库存 |
关联：维度对应仓库、库位、SKU、批次。在途行的 location_code 不引用 wms_location。
并发 / 审计：
- 禁止先查出数量再在 PHP 里相减后回写。
- 扣减使用单条条件更新，例如可用转预占：
UPDATE wms_inventory
SET available_qty = available_qty - :qty,
reserved_qty = reserved_qty + :qty,
version = version + 1
WHERE tenant_code = :tenant_code
AND id = :id
AND available_qty >= :qty;
- 受影响行数为 0：库存不足或版本冲突，抛业务异常，整单事务回滚。
- 同一事务插入对应的
wms_stock_log。 - 各数量桶不得为负。不软删除；数量全为 0 的行保留，避免并发下反复插入同一粒度。
wms_stock_log 库存流水
用途：库存变化的事实。任何余额变化都要有流水。只追加。
一次业务动作若改变多个数量桶或多行余额，每个桶一行，共用同一个 movement_no。
| 字段 | 类型 | 可空 | 默认 | 说明 |
|---|---|---|---|---|
| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
| tenant_code | VARCHAR(32) | N | 租户编码 | |
| movement_no | VARCHAR(64) | N | 同一次动作的组号 | |
| customer_code | VARCHAR(64) | N | 货主 | |
| warehouse_code | VARCHAR(32) | N | 仓库 | |
| location_code | VARCHAR(64) | N | '' | 库位 |
| sku_code | VARCHAR(64) | N | SKU | |
| batch_no | VARCHAR(64) | N | '' | 批次 |
| qty_bucket | VARCHAR(32) | N | available、reserved、picked、hold、damaged、in_transit |
|
| qty_before | DECIMAL(16,4) | N | 该桶变更前 | |
| qty_delta | DECIMAL(16,4) | N | 有符号变化量 | |
| qty_after | DECIMAL(16,4) | N | 该桶变更后 | |
| biz_type | VARCHAR(32) | N | 业务类型 | |
| biz_no | VARCHAR(64) | N | 业务单号 | |
| biz_line_no | INT UNSIGNED | Y | 单据行号 | |
| operator_user_code | VARCHAR(64) | Y | 操作人 | |
| request_id | VARCHAR(64) | Y | 请求标识 | |
| created_at | TIMESTAMP | Y | 发生时间 | |
| updated_at | TIMESTAMP | Y | 行创建后不更新 |
索引：
| 名称 | 类型 | 字段 | 支撑的查询 |
|---|---|---|---|
| idx_tenant_sku_created | INDEX | (tenant_code, sku_code, created_at) | 某 SKU 的库存为何变化 |
| idx_tenant_biz | INDEX | (tenant_code, biz_type, biz_no) | 某单据的流水 |
| idx_tenant_movement | INDEX | (tenant_code, movement_no) | 同一次动作的各行 |
biz_type：inbound_confirm、inbound_receive、inbound_putaway、reserve、release、pick、ship、hold、unhold、damage、transfer、adjust、stocktake。
关联：biz_no 指向入库单、出库单、调整单或盘点单。
并发 / 审计：禁止更新和删除。qty_after = qty_before + qty_delta，且 qty_after 等于同一事务中余额桶的新值。
wms_stock_adjust 库存调整单
用途：人工调整的单据头。确认时才改余额并写流水。
| 字段 | 类型 | 可空 | 默认 | 说明 |
|---|---|---|---|---|
| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
| tenant_code | VARCHAR(32) | N | 租户编码 | |
| adjust_no | VARCHAR(64) | N | 调整单号 | |
| warehouse_code | VARCHAR(32) | N | 仓库 | |
| customer_code | VARCHAR(64) | N | 货主 | |
| status | VARCHAR(32) | N | draft | 状态 |
| reason | VARCHAR(500) | N | 原因 | |
| version | INT UNSIGNED | N | 0 | 乐观锁 |
| created_at | TIMESTAMP | Y | ||
| updated_at | TIMESTAMP | Y |
索引：
| 名称 | 类型 | 字段 | 支撑的查询 |
|---|---|---|---|
| uk_tenant_adjust_no | UNIQUE | (tenant_code, adjust_no) | 按单号查找 |
| idx_tenant_status_created | INDEX | (tenant_code, status, created_at) | 列表 |
状态：draft → confirmed，draft → cancelled。confirmed、cancelled 为终态。
确认时按明细对指定数量桶做原子增减，biz_type = adjust。减少时受影响行数为 0 则整单回滚。状态变更写 wms_status_log。不软删除。
wms_stock_adjust_line 调整明细
用途：调整单的一行，只改一个数量桶。
| 字段 | 类型 | 可空 | 默认 | 说明 |
|---|---|---|---|---|
| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
| tenant_code | VARCHAR(32) | N | 租户编码 | |
| adjust_no | VARCHAR(64) | N | 调整单号 | |
| line_no | INT UNSIGNED | N | 行号，单内从 1 递增 | |
| location_code | VARCHAR(64) | N | '' | 库位 |
| sku_code | VARCHAR(64) | N | SKU | |
| batch_no | VARCHAR(64) | N | '' | 批次 |
| qty_bucket | VARCHAR(32) | N | 数量桶 | |
| qty_delta | DECIMAL(16,4) | N | 有符号数量，禁止 0 | |
| created_at | TIMESTAMP | Y | ||
| updated_at | TIMESTAMP | Y |
索引：
| 名称 | 类型 | 字段 | 支撑的查询 |
|---|---|---|---|
| uk_tenant_adjust_line | UNIQUE | (tenant_code, adjust_no, line_no) | 定位明细 |
关联：头表 wms_stock_adjust。确认后明细不再修改。
wms_stocktake 盘点单
用途：盘点单据头。确认时把账面与实盘的差额写成流水，biz_type = stocktake。
| 字段 | 类型 | 可空 | 默认 | 说明 |
|---|---|---|---|---|
| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
| tenant_code | VARCHAR(32) | N | 租户编码 | |
| stocktake_no | VARCHAR(64) | N | 盘点单号 | |
| warehouse_code | VARCHAR(32) | N | 仓库 | |
| status | VARCHAR(32) | N | draft | 状态 |
| version | INT UNSIGNED | N | 0 | 乐观锁 |
| created_at | TIMESTAMP | Y | ||
| updated_at | TIMESTAMP | Y |
索引：
| 名称 | 类型 | 字段 | 支撑的查询 |
|---|---|---|---|
| uk_tenant_stocktake_no | UNIQUE | (tenant_code, stocktake_no) | 按单号查找 |
| idx_tenant_status_created | INDEX | (tenant_code, status, created_at) | 列表 |
状态：draft → counting → confirmed，draft 或 counting 可到 cancelled。confirmed、cancelled 为终态。
盘点期间不锁死全仓。确认时按当时账面重算差额；若并发导致目标桶不足，确认失败并回滚。不软删除。
wms_stocktake_line 盘点明细
用途：一个库位、SKU、批次、数量桶上的账面与实盘。
| 字段 | 类型 | 可空 | 默认 | 说明 |
|---|---|---|---|---|
| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
| tenant_code | VARCHAR(32) | N | 租户编码 | |
| stocktake_no | VARCHAR(64) | N | 盘点单号 | |
| line_no | INT UNSIGNED | N | 行号 | |
| customer_code | VARCHAR(64) | N | 货主 | |
| location_code | VARCHAR(64) | N | 库位 | |
| sku_code | VARCHAR(64) | N | SKU | |
| batch_no | VARCHAR(64) | N | '' | 批次 |
| qty_bucket | VARCHAR(32) | N | available | 盘点的数量桶 |
| system_qty | DECIMAL(16,4) | N | 生成明细时的账面 | |
| counted_qty | DECIMAL(16,4) | Y | 实盘，未盘为空 | |
| created_at | TIMESTAMP | Y | ||
| updated_at | TIMESTAMP | Y |
索引：
| 名称 | 类型 | 字段 | 支撑的查询 |
|---|---|---|---|
| uk_tenant_stocktake_line | UNIQUE | (tenant_code, stocktake_no, line_no) | 定位明细 |
| idx_tenant_stocktake_loc | INDEX | (tenant_code, stocktake_no, location_code) | 按库位录入 |
关联：头表 wms_stocktake。确认时差额为 counted_qty - 当前账面，不以生成时的 system_qty 作为扣减依据。system_qty 只说明生成时刻的账面。