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

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

## 1. 背景与目标

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

| 缺口 | 现状 | 目标 |
|------|------|------|
| 盘点无复核关口 | 录入/导入实盘后由“完成盘点”直接核销台账 | 盘点结果先走 BPM 审批，通过才解冻并核销 |
| 盘点靠人工逐期建任务 | 每次需手工创建任务 | 方案配置周期，后台定时自动生成任务 |
| 条码能力弱 | 仅支持单一业务编码占位符、无成图/扫码 | 组合字段、服务端成图、扫码解析 |
| SN 无闭环 | 仅有 SN 主档，无在库/去向 | 登记/核销 SN、单件在库/去向查询（轻量闭环） |
| 设备入库无单据 | 仅“台账创建即自动入设备仓” | 独立设备入库单，走创建、审批、完成入库、查询 |

**全局约束**：仅后端；不修改前端项目；接口变更只出联调文档；库存创建/数量更新/流水一律经库存事务服务，不直写库存表；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 独立设备入库单是否需要与设备台账的“自动入库”叠加（即设备既随台账自动入库，又可单独走入库单），或自动入库收敛为仅随入库单执行。

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

| 单元 | 状态 | 备注 |
|------|------|------|
| M1 盘点结果审批 BPM | 代码完成，编译通过 | 错误码/DO/RespVO/Mapper/接口与实现/监听器/端点替换已落地；DB 脚本已写待执行 |
| M2 定期盘点调度 | 部分完成，未编译 | 方案字段/校验/查询与 Service 已改；任务侧“按方案生成任务”、Job、DB 脚本未做 |
| M3 条码组合/成图/扫码 | 未开始 | 待 zxing 引入、模板渲染、解析接口 |
| M4 SN 轻量闭环 | 未开始 | 待表字段/登记核销/查询/API 贯通 |
| M5 设备入库单 | 未开始 | 待新单据全栈与 BPM |
| M6 收尾 | 未开始 | 全量编译 + docs + 冒烟 + DB/流程部署 |