仓储（WM）批量补码需求说明

本文档整理的是 2026-09-08 确认的本轮批量补码需求包（M1~M5），用于后续开发基线。
前置能力（不在本文范围，已完成）：杂项入库/出库/供应商退货三单据 BPM 审批闭环、设备台账联动设备仓自动入库、盘点差异自动核销接线、MDM 物料主数据（含“设备”物料类型/分类/单位）。

1. 背景与目标

当前 WM 仓储已具备单据、库存流水、盘点、设备仓自动入库等能力，但存在以下缺口，本轮一并补齐：

全局约束：仅后端；不修改前端项目；接口变更只出联调文档；库存创建/数量更新/流水一律经库存事务服务，不直写库存表；BPM 分类与流程定义手工部署；新增表不落 tenant_id；ADD COLUMN 按存在性检查执行。

2. 范围界定

• 做：M1 盘点结果审批 BPM；M2 定期盘点自动调度；M3 条码组合/成图/扫码；M4 SN 轻量闭环；M5 独立设备入库单。
• 不做：盘点“冲销/反核销”；历史已完成任务补核销；库存单据行重构为 SN 明细；前端代码。

3. M1 盘点结果审批 BPM

3.1 业务场景

盘点中录入/导入实盘后，由负责人将盘点结果提交 BPM 审批；审批通过后系统解冻库存并自动核销盘盈/盘亏差异更新台账；审批不通过则允许修改实盘后重新提交。

3.2 状态机（复用现枚举，不新增“已审批”态）

草稿 PREPARE ──开始盘点──▶ 盘点中 APPROVING ──提交结果审批(建BPM)──▶ 盘点中 APPROVING
                                                                  │（processInstanceId 非空=审批中）
盘点中 ──审批通过──▶ 已完成 FINISHED（解冻 + 自动核销差异，同事务）
盘点中 ──审批驳回──▶ 盘点中 APPROVING（清 processInstanceId，可改实盘后重提）
盘点中 ──审批取消──▶ 已取消 CANCELED（解冻）
草稿/盘点中 ──取消──▶ 已取消 CANCELED（解冻）

3.3 业务规则

• 开始盘点（草稿→盘点中）：仅草稿；盘点行非空；开启冻结则冻结盘点行库存。
• 录入/导入实盘：仅盘点中允许（人工录入、Excel 导入统一口径）。
• 提交结果审批 前置校验：状态=盘点中；已有 ≥1 条盘点结果；未提交过（processInstanceId 为空，防重复提交）。
• 审批通过（同一事务、失败整体回滚回盘点中）：置已完成 → 若冻结则先解冻 → 逐条盘点结果核销：差异 = 实盘 − 账面；>0 盘盈作入库、<0 盘亏作出库（数量为负）、=0 跳过；以盘点结果回填的库存定位精确核销；生成库存流水 bizType=盘点。
• 原“完成盘点”公开动作移除，核销改由审批通过事件驱动。
• 驳回不改任务状态（保持盘点中），仅清流程实例标记，允许修改实盘后重提。

3.4 数据与接口

• mes_wm_stock_taking_task 增加 process_instance_id；任务查询/详情响应返回该字段（前端据此区分“审批中”与“可提交审批”）。
• 接口：提交盘点结果审批（单据 id + 流程定义 key）、可审批流程定义列表（分类编码 stock_taking_result_approve）。
• BPM 监听：解析业务主键=任务 id，校验任务存在且盘点中，按审批结果更新（通过/驳回/取消）。

4. M2 定期盘点自动调度

4.1 业务场景

盘点方案可开启“定期自动生成”：系统按方案配置的周期（cron）自动创建盘点任务，到点即用，无需人工逐期建单。

4.2 业务规则

• 方案字段：是否自动生成（auto_generate）、生成周期 cron（generate_cron，Quartz 6 段）、上次生成时间（last_generate_time）。
• 开启自动生成时必须配置合法 cron；未开启则忽略 cron。
• 仅 启用状态 + 开启自动生成 + 已配置 cron 的方案参与扫描。
• 后台定时任务周期触发（infra 后台配置 cron，handler=方案生成 Job 的 Bean 名，建议每分钟一次）：按各方案“上次生成时间 + cron”判断是否到期，到期才生成。
• 防重复：生成任务成功后同事务回写上次生成时间；首次扫描仅记录基线时间、不立即生成（从下一周期开始）。
• 自动生成的任务：沿用方案的类型/盲盘/冻结/动态盘点时间段；名称取方案名；盘点人取系统默认用户；任务编码走“盘点任务编码”自动规则；创建后即按方案生成盘点明细行（草稿态）。
• 单个方案生成失败不影响其它方案。

4.3 数据与接口

• mes_wm_stock_taking_plan 增加 auto_generate / generate_cron / last_generate_time；方案新增/修改与查询响应携带。
• 提供“由方案按周期生成任务”的服务方法，供 Job 调用；Job 本身不做库存/单据业务。

5. M3 条码 / 标签 / 扫码增强

5.1 业务场景

把仓储条码从“单一业务编码”升级为可组合、可成图、可扫码反查，支撑标签打印与 PDA 扫码。

5.2 需求点

1. 条码内容组合字段：条码内容模板支持多个占位符自由组合（如业务编码 + 物料编码 + 批次 + 库位 + SN 等），配置到条码配置项，生成时按模板渲染真实内容。
2. 服务端成图 / 打印：MES 模块引入二维码/条码生成库（zxing）在服务端成图；提供打印/预览能力。图片若需留存一律走附件中间表；仅即时预览可用 Base64，不落业务表图片列。
3. 扫码解析：新增服务端接口，对扫码内容做结构化解析：识别业务编码与其它键值，反查并返回对应业务对象（单据 / 物料 / 批次 / SN / 库位等），供扫码枪与移动端跳转、核验。

5.3 验收要点

• 组合模板渲染内容正确（含中文/大小写）。
• 生成图像可被扫码还原，且还原结果与渲染内容一致。
• 解析接口对未识别内容给出明确错误而非静默。

6. M4 SN 单品库存轻量闭环

6.1 业务场景

对开启序列号管理的物料，要求能登记每件 SN 的出入、查看单件当前在库与去向，并支持盘点按 SN 核对。**单据行不重构为 SN 明细**（保持行级数量管理，SN 作为登记/核销记录闭环）。

6.2 需求点

1. SN 在库状态与位置：mes_wm_sn 补齐在库状态、所在库位等字段（DO 与表字段对齐）。
2. 流水带 SN：库存事务/流水表增加 snCode 列，记录该笔出入对应的序列号。
3. 入库登记 SN：按 SN 管理物料的入库事务登记 SN（置为在库、记录库位）。
4. 出库核销 SN：出库时核销指定在库 SN（置为出库/非在库），与库存事务同记录。
5. 单件在库/去向查询：按 SN 查当前在库位置、最近去向流水。
6. 盘点按 SN 核对：按 SN 管理物料的盘点支持 SN 粒度核对（在盘点维度内校验实物 SN 与在库 SN）。
7. 序列号管理标记贯通：物料“是否序列号管理（isSerialManaged）”需在 MDM API（物料响应/创建 DTO）中贯通，供 MES 各模块判断。

6.3 业务规则

• 仅“按 SN 管理”的物料登记/核销 SN。
• 同一 SN 在库唯一；出库核销的 SN 必须处于在库状态。

7. M5 独立设备入库单

7.1 业务场景

“设备台账创建即自动入设备仓”解决设备建档联动；“设备入库单”则作为可追溯、可审批的入库凭证，用于设备由外部进入/正式入仓的业务，按单留痕。

7.2 单据结构

• 主表：单据编码（自动生成，新增“设备入库单编码”规则）、名称、入库日期、来源/备注、状态、BPM 流程实例编号等。
• 明细行：设备（台账）→ 自动带入设备物料(itemId)；仓库/库区/库位固定设备仓三元组；数量默认 1；同单可多台；备注。

7.3 流程与状态（沿用杂项入库模板）

草稿 PREPARE ──提交审批(建BPM,回写流程编号)──▶ 审批中 APPROVING
审批通过 → 已审批 APPROVED ──完成入库──▶ 已完成 FINISHED
驳回 → 草稿 PREPARE（可改重提）
审批/草稿取消 → 已取消 CANCELED

• 审批通过进入“可执行入库”，库存动作仅在“完成入库”执行（逐明细行设备仓 IN +1，更新台账与流水，业务类型独立）。

7.4 业务规则

• 明细仅可选已关联物料（有 itemId）的设备台账。
• 库位必须属于设备仓体系。
• 设备编码/物料已有则不允许重复建档（沿用台账约束）。
• “完成入库”仅已审批状态可执行，且仅执行一次；库存与流水统一走库存事务服务，不直写库存表。
• 独立 BPM 流程分类与独立库存流水业务类型（用于设备入库单据与设备台账自动入库区分）。

8. 跨单元依赖与实施顺序

M1 盘点结果审批 BPM（改既有盘点任务，含 DB 列/错误码/监听器/端点替换）
  └─▶ M2 定期盘点调度（M1 任务创建/状态机是其下游产物）
M3 条码成图/扫码/组合字段（MES 依赖引入 zxing）
M4 SN 轻量闭环（含 MDM-API 字段贯通）
M5 设备入库单（可复用杂项入库单据骨架）
M6 收尾：全量编译、docs 联调文档、统一端到端冒烟（含 DB 脚本执行、BPM 分类与流程定义手工部署）

9. 待澄清/决策项（实现前需确认）

• M5 独立设备入库单是否需要与设备台账的“自动入库”叠加（即设备既随台账自动入库，又可单独走入库单），或自动入库收敛为仅随入库单执行。

附：实施状态追踪（供续作基线）