From 8321c44be98b3bef899eb357d0317631311361ba Mon Sep 17 00:00:00 2001
From: zhouz <>
Date: Wed, 5 Aug 2026 19:53:32 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=A2=9E=E5=8A=A0=E4=BB=93=E4=BD=8D?=
 =?UTF-8?q?=E5=BA=93=E5=AD=98=E7=B1=BB=E5=9E=8B=E8=AE=BE=E8=AE=A1=E8=A7=84?=
 =?UTF-8?q?=E6=A0=BC?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...2026-08-05-struct-inventory-type-design.md | 74 +++++++++++++++++++
 1 file changed, 74 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-08-05-struct-inventory-type-design.md

diff --git a/docs/superpowers/specs/2026-08-05-struct-inventory-type-design.md b/docs/superpowers/specs/2026-08-05-struct-inventory-type-design.md
new file mode 100644
index 00000000..60027c63
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-05-struct-inventory-type-design.md
@@ -0,0 +1,74 @@
+# 仓位库存类型设计规格
+
+## 目标
+
+在 `wms_structattr` 增加库存类型字段，使系统无需关联组盘表或木箱表即可识别仓位当前存放的是成品、空载具还是空木箱，并由各类任务完成回调统一维护。
+
+## 字段和值域
+
+新增 `inventory_type varchar(1) NOT NULL DEFAULT '0'`：
+
+- `0`：空。
+- `1`：成品。
+- `2`：空载具（现有空托盘业务在代码中命名为 EmptyVehicle）。
+- `3`：空木箱。
+
+Java 增加单字段枚举 `StructInventoryTypeEnum`，业务代码使用枚举值，不散落字符串常量。仓位管理查询同步返回并展示库存类型。
+
+## 完成回调维护规则
+
+- 成品入库完成：目标仓位写入 `1`。
+- 成品出库完成：原仓位清空载具时写入 `0`。
+- 空载具入库完成：目标仓位写入 `2`。
+- 空载具出库完成：原仓位写入 `0`。
+- 空木箱入库完成：目标仓位写入 `3`。
+- 空木箱出库完成：原仓位写入 `0`。
+- 取消任务：库存未发生物理变化，不修改库存类型。
+
+所有类型变更与现有载具号、数量、锁状态变更写在同一条 Mapper XML 更新 SQL 中，避免字段状态部分成功。
+
+## 移库规则
+
+移库支持成品、空木箱及以后新增的其他库存类型，不能固定写为成品。
+
+任务完成事务按以下顺序执行：
+
+1. 根据起始仓位编码查询起始仓位，读取 `inventory_type`。
+2. 起始仓位类型为 `0` 时拒绝完成，抛出业务异常。
+3. 目标仓位完成更新时传入起始仓位类型，并写入相同值。
+4. 起始仓位完成更新时清空载具并将类型写为 `0`。
+
+现有移库完成逻辑先更新目标、后清空来源；增加类型查询后仍保持这一更新顺序，整个方法已有事务保护，任何一步失败都会回滚。
+
+## 历史数据回填
+
+数据库脚本新增字段后执行一次回填，优先级如下：
+
+1. `storagevehicle_code` 为空：`0`。
+2. 关联有效组盘记录：`1`。
+3. 载具编码为现有空载具标识 `EMPTY_VEHICLE`，且无组盘记录：`2`。
+4. 关联 `wmw_boxinfo` 且木箱状态为在库：`3`。
+5. 其他无法识别但载具号不为空的数据保持 `0`，便于通过查询定位并人工确认，不错误标记为成品。
+
+回填脚本同时提供无法识别记录的查询语句，执行后可以直接检查遗留数据。
+
+## 查询与选位
+
+本次范围只增加类型维护和展示。现有选位条件仍以载具号、组盘表、木箱表和锁状态为准，不立即改写为依赖新字段，避免历史数据质量影响现有业务。后续确认回填数据稳定后，可单独优化候选仓位 SQL。
+
+## 一致性与异常
+
+- 类型字段与载具号必须在同一 SQL 中更新。
+- 完成 SQL 继续保留现有任务 ID、锁类型、载具号等并发条件。
+- 移库来源类型为空时不允许完成，防止把无库存状态传播到目标仓位。
+- Mapper SQL 全部写入 XML，不使用注解 SQL。
+
+## 验收范围
+
+- 成品、空载具、空木箱入库完成后仓位类型正确。
+- 三类库存出库完成后仓位类型均为 `0`。
+- 成品和空木箱移库完成后，目标继承来源类型，来源变为 `0`。
+- 取消任务不会改变库存类型。
+- 历史数据可按既定优先级完成回填，无法识别数据可被查询。
+- 仓位管理页面能展示库存类型名称。
+- WMS 后端编译和前端静态检查通过。