huachuang/docs/superpowers/specs/2026-07-22-outbound-create-design.md

出库单新增功能设计

目标与范围

按照 .image/出库新增.png 重构出入库单主表的新增布局，支持从仓库可用库存选择和手工新增物料汇总两种明细添加方式，并将主表与明细作为一个聚合事务保存。

本次仅实现出库新增，不新增数据库字段，不扩展入库、明细编辑、分配、确认或回传流程。主表使用 wms_iostorinv，明细写入 wms_iostorinvdtl。

页面布局

新增页采用已确认的参考图布局：

• 顶部操作区提供“保存”和“关闭”。
• 主表区域展示单据号、仓库、业务类型、单据状态、明细数、总重量、业务日期和备注。
• 明细区域提供“选择库存”和“新增汇总”两个入口。
• 明细表展示序号、物料编码、物料名称、箱号、子卷号、SAP 批次号、出库重量、单位、源单号、明细备注和操作。
• 初次打开时明细表为空。

主表字段与默认值

页面字段	wms_iostorinv 字段	行为
单据号	billCode	只读；保存时通过 base 模块编码生成 API 生成
仓库	storId、storCode、storName	必填，可选择
业务类型	billType	必填，可选择
出入类型	ioType	后端固定为出库
单据状态	billStatus	默认并固定为“生成”
明细数	detailCount	根据明细条数自动计算
总重量	totalWeight	汇总明细的出库重量
业务日期	bizDate	默认当天，可修改
备注	remark	选填

前端在明细增删和重量变化时即时更新明细数与总重量。后端保存时必须根据请求明细重新计算，不能直接信任前端汇总字段。

明细字段与持久化边界

明细使用 wms_iostorinvdtl 的现有字段：

业务含义	明细字段	保存规则
主表关联	iostorinvId	主表插入后回填
序号	seqNo	从 1 开始连续生成
物料	materialId、materialCode	必填
子卷号	pcsn	库存明细带入；手工汇总为空
出库重量	planQty	必须大于 0
已分配数量	assignQty	新增时为 0
未分配数量	unassignQty	新增时等于出库重量
单位	qtyUnitId、qtyUnitName	从库存或物料信息带入
来源单据	sourceBillCode、sourceBillType、sourceBilldtlId	库存存在来源时带入
备注	remark	选填

箱号、物料名称和独立 SAP 批次号在 wms_iostorinvdtl 中没有对应字段，只用于新增页面展示，不落库，也不与其他字段混用。手工汇总明细的箱号、子卷号和 SAP 批次号均为空。

明细新增方式

从库存选择

1. 用户必须先选择仓库。
2. 库存弹窗查询该仓库下的可用库存，并支持按物料、箱号、子卷号等现有库存字段筛选。
3. 用户可独立勾选库存记录，界面不自动联动勾选同箱的其他子卷。
4. 确认时以后端为准，提取已选记录涉及的箱号，去重后重新查询这些箱号在所选仓库下的全部可用子卷。
5. 将查询出的每个子卷逐条带回出库明细表；默认出库重量为该子卷当前可用重量。
6. 同一箱号重复选择只展开一次，避免重复明细。

新增物料汇总

1. 用户选择物料并输入总出库重量，可填写备注。
2. 单位从物料现有信息带出。
3. 新增一条汇总明细，箱号、子卷号和 SAP 批次号保持为空。

接口与事务设计

采用主表与明细聚合保存方案：

• 新增“创建出库单（含明细）”接口，接收主表可编辑字段和明细列表。
• 新增按仓库和筛选条件查询可用库存的接口。
• 库存确认或保存前由后端按箱号展开全部可用子卷，确保展开结果属于当前仓库且仍然可用。
• 保存服务开启事务，先调用 base 模块编码生成 API 获取单据号，再构造主表、计算汇总、插入主表，最后插入全部 wms_iostorinvdtl 明细。
• 编码生成、主表插入或任一明细插入失败时整体回滚。

单据号规则沿用项目已有的出入库编码规则配置和 CodeGenApi 调用方式，不在本功能中创建新的编码规则或字段。

数据校验与错误处理

• 仓库、业务类型和业务日期必填。
• 保存时至少存在一条明细。
• 每条明细必须包含物料，且出库重量大于 0。
• 切换仓库时清空当前明细，避免跨仓库数据混用。
• 库存带入时校验箱号属于所选仓库，并以当前可用库存重新展开；库存已不可用时返回明确的业务错误。
• 重复箱号在展开前去重。
• 编码 API 返回失败或空编码时终止保存并回滚。
• 后端固定出库类型和生成状态，并重新计算明细数、总重量、序号及初始分配数量，防止客户端篡改。

测试与验收

后端测试覆盖：

• base 编码 API 生成的单据号写入主表。
• 默认出库类型和生成状态正确。
• 后端根据明细重算明细数和总重量。
• 主表与明细在同一事务中写入，异常时整体回滚。
• 库存查询限定所选仓库和可用数量。
• 任意选中一个箱号下的记录后，返回该箱号全部可用子卷。
• 多条选中记录包含重复箱号时只展开一次。
• 物料缺失、重量非正数、空明细及失效库存被拒绝。

前端测试或可自动化验证覆盖：

• 新增页业务日期默认为当天，状态为生成，明细为空。
• 明细增删和重量修改会更新明细数与总重量。
• 未选择仓库不能打开库存选择流程。
• 库存确认结果逐子卷进入明细表。
• 手工汇总行的箱号、子卷号和 SAP 批次号为空。
• 切换仓库会清空现有明细。
• 提交数据只使用现有主表和明细字段。

完成后运行 WMS 模块相关单元测试、前端类型检查和构建，并对照参考图检查新增页布局与两种明细添加流程。