# 入库

约定见 [00-conventions.md](./00-conventions.md)。库存变化见 [40-inventory.md](./40-inventory.md)。Phase 1 锁定，Phase 9 写迁移。

收货差异不建表，由明细的 `expected_qty - received_qty` 得出。质检结果记在收货记录上。

## wms_inbound 入库单

用途：入库单据头。

| 字段 | 类型 | 可空 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
| tenant_code | VARCHAR(32) | N | | 租户编码 |
| inbound_no | VARCHAR(64) | N | | 入库单号 |
| warehouse_code | VARCHAR(32) | N | | 仓库 |
| customer_code | VARCHAR(64) | N | | 货主 |
| inbound_type | VARCHAR(32) | N | | 类型 |
| supplier_code | VARCHAR(64) | Y | | 供应商 |
| status | VARCHAR(32) | N | draft | 状态 |
| qc_required | TINYINT UNSIGNED | N | 0 | 1 表示收货后需质检 |
| expected_at | TIMESTAMP | Y | | 预计到货 |
| remark | VARCHAR(500) | Y | | |
| version | INT UNSIGNED | N | 0 | 乐观锁 |
| created_at | TIMESTAMP | Y | | |
| updated_at | TIMESTAMP | Y | | |

索引：

| 名称 | 类型 | 字段 | 支撑的查询 |
| --- | --- | --- | --- |
| uk_tenant_inbound_no | UNIQUE | (tenant_code, inbound_no) | 按单号查找 |
| idx_tenant_status_created | INDEX | (tenant_code, status, created_at) | 列表 |
| idx_tenant_wh_customer | INDEX | (tenant_code, warehouse_code, customer_code, status) | 仓库 / 货主筛选 |

`inbound_type`：`purchase` 采购、`return` 退货入库、`transfer` 调拨、`other` 其他。退货业务单据表在后续 Phase 再设计，这里只保留类型值。

状态与合法转换：

```
draft → confirmed → receiving → received → putting_away → completed
draft → cancelled
confirmed → cancelled
receiving → cancelled   （仅当全部明细 received_qty = 0）
```

`completed`、`cancelled` 为终态。禁止跳步。每次成功转换写 `wms_status_log`，`biz_type = inbound`。

关联：明细、收货、上架。不软删除，取消用状态。

并发 / 审计：更新状态时带 `version`。确认时按预计数量增加在途（`location_code = ''`，`biz_type = inbound_confirm`）。取消已确认且未收货的单据时冲回在途。

## wms_inbound_line 入库明细

用途：入库单的 SKU 行。

| 字段 | 类型 | 可空 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
| tenant_code | VARCHAR(32) | N | | 租户编码 |
| inbound_no | VARCHAR(64) | N | | 入库单号 |
| line_no | INT UNSIGNED | N | | 行号，单内从 1 递增 |
| sku_code | VARCHAR(64) | N | | SKU |
| batch_no | VARCHAR(64) | N | '' | 指定批次；收货时才知道则为空，记到收货记录 |
| expected_qty | DECIMAL(16,4) | N | | 预计数量，大于 0 |
| received_qty | DECIMAL(16,4) | N | 0 | 已收，由收货记录累计 |
| putaway_qty | DECIMAL(16,4) | N | 0 | 已上架，由上架记录累计 |
| created_at | TIMESTAMP | Y | | |
| updated_at | TIMESTAMP | Y | | |

索引：

| 名称 | 类型 | 字段 | 支撑的查询 |
| --- | --- | --- | --- |
| uk_tenant_inbound_line | UNIQUE | (tenant_code, inbound_no, line_no) | 定位明细 |
| idx_tenant_inbound_sku | INDEX | (tenant_code, inbound_no, sku_code) | 按 SKU 找行 |

关联：头表 `wms_inbound`。`received_qty`、`putaway_qty` 只由收货、上架事务回写，不单独做接口改数。

约束：`putaway_qty <= received_qty <= expected_qty` 不强制等于预计。短收允许进入 `received`。超收拒绝。

## wms_inbound_receipt 收货记录

用途：一次收货的事实。只追加。质检结论写在本行。

| 字段 | 类型 | 可空 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
| tenant_code | VARCHAR(32) | N | | 租户编码 |
| receipt_no | VARCHAR(64) | N | | 收货记录号，可用 movement 同源取号或与 movement_no 相同 |
| inbound_no | VARCHAR(64) | N | | 入库单号 |
| line_no | INT UNSIGNED | N | | 明细行号 |
| sku_code | VARCHAR(64) | N | | SKU |
| batch_no | VARCHAR(64) | N | '' | 实收批次 |
| location_code | VARCHAR(64) | N | | 收到的库位，通常是收货位 |
| qty | DECIMAL(16,4) | N | | 数量，大于 0 |
| qc_result | VARCHAR(32) | N | skipped | 质检结果 |
| operator_user_code | VARCHAR(64) | Y | | 操作人 |
| created_at | TIMESTAMP | Y | | |
| updated_at | TIMESTAMP | Y | | 行创建后不更新 |

索引：

| 名称 | 类型 | 字段 | 支撑的查询 |
| --- | --- | --- | --- |
| uk_tenant_receipt_no | UNIQUE | (tenant_code, receipt_no) | 按收货号查找 |
| idx_tenant_inbound_line | INDEX | (tenant_code, inbound_no, line_no) | 某行的收货历史 |

`qc_result`：`skipped` 无需质检，`passed` 合格，`failed` 不合格。

同一事务：

- 在途减少 `qty`。
- `passed` 或 `skipped`：收货位 `available_qty` 增加。
- `failed`：收货位 `damaged_qty` 增加。
- 流水 `biz_type = inbound_receive`，`biz_no = inbound_no`。
- 明细 `received_qty` 增加。

不需要质检时 `qc_result` 直接为 `skipped`。需要质检时，本阶段仍在收货事务内给出结论，不另建质检单。

## wms_inbound_putaway 上架记录

用途：从收货位移到存储位的事实。只追加。

| 字段 | 类型 | 可空 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
| tenant_code | VARCHAR(32) | N | | 租户编码 |
| putaway_no | VARCHAR(64) | N | | 上架记录号 |
| inbound_no | VARCHAR(64) | N | | 入库单号 |
| line_no | INT UNSIGNED | N | | 明细行号 |
| sku_code | VARCHAR(64) | N | | SKU |
| batch_no | VARCHAR(64) | N | '' | 批次 |
| from_location_code | VARCHAR(64) | N | | 源库位 |
| to_location_code | VARCHAR(64) | N | | 目标库位 |
| qty | DECIMAL(16,4) | N | | 数量，大于 0 |
| operator_user_code | VARCHAR(64) | Y | | 操作人 |
| created_at | TIMESTAMP | Y | | |
| updated_at | TIMESTAMP | Y | | 行创建后不更新 |

索引：

| 名称 | 类型 | 字段 | 支撑的查询 |
| --- | --- | --- | --- |
| uk_tenant_putaway_no | UNIQUE | (tenant_code, putaway_no) | 按上架号查找 |
| idx_tenant_inbound_line | INDEX | (tenant_code, inbound_no, line_no) | 某行的上架历史 |

同一事务：源库位可用减少、目标库位可用增加，流水 `biz_type = inbound_putaway`。目标库位须为 `active`，并满足混放与容量。残损数量不上架到存储位，留在收货 / 残品位。明细 `putaway_qty` 增加。

全部明细 `putaway_qty = received_qty` 且状态为 `putting_away` 时，才允许转到 `completed`。