# MES 仓储物资「条码/二维码 · 标签打印 · 盘点 · 批次与单品追溯」差距分析与实施建议

> 依据：`yudao-module-mes` 现有代码盘点（2026-09-08），对照三项需求逐条核对"已有/缺失"。结论均可溯源到对应 Controller / Service / DO / 表。

## 1. 总体结论

`mes_wm_*` 一整套地基已经铺得很宽：**库存台账+流水、批次、条码、SN、盘点 plan/task/line/result、批次追溯**都建好了。真正的差距大多是"**最后一公里没接线**"，其次才是"需新增模型"。缺表/重造的场景很少，多数是"逻辑已写但无调用点、字段已留但无人维护、模型已建但未进库存链"。

三需求命中最重要的三处：

1. **盘点盘盈盘亏自动核销"未接线"**（`processStockTakingDifference` 无任何调用方，finish 只置状态）——最确定、代价最小的缺口。
2. **标签打印 / 扫码 / 条码组合字段**整体缺失（只有条码字符串与 config 里的模板名字段）。
3. **SN 只做"号池"，未进库存/单据链**，`isSerialManaged` 空转 → "按单件 SN 精准追溯"目前是断的。

---

## 2. 现状能力速查

| 能力 | 主表 | 关键接口（Controller 路径） | 状态 |
|------|------|------------------------------|------|
| 库存台账/多条件查询/冻结 | `mes_wm_material_stock` | `/mes/wm/material-stock/page/get/update-frozen` | ✅ 在用，支持物料/批次/仓库/库区库位/供应商筛选 |
| 库存调整（自定义入/出） | 同上 + 流水 | `/mes/wm/material-stock/adjust-in/adjust-out` | ✅ 走 transaction，自动更新台账 |
| 移库/调拨 | 同上 + `mes_wm_transfer(_line/_detail)` | `/mes/wm/material-stock/move`、`/mes/wm/transfer/*` | ✅ |
| 库存流水 | `mes_wm_transaction` | `/mes/wm/transaction/page`（可按 bizType/bizCode/item/batch 筛） | ✅ 含 bizId/bizCode/bizLineId/relatedTransactionId，具备反向串联基础 |
| 可用量 available | 内存计算字段 | 页面现算 `qty - frozen - reserved` | ⚠️ 展示层现算；reserved 仅生产领料/销售出库两单占库（`MesWmStockReserveService`） |
| 在途 inTransit | `mes_wm_material_stock.in_transit_quantity` | 无 | ❌ 无任何写入/冲销方，空转字段 |
| 盘点计划/任务/行/结果 | `mes_wm_stock_taking_plan(_param)/task(_line/_result)` | `/mes/wm/stock-taking-plan/*`、`/mes/wm/stock-taking-task/*` | ✅ 主流程在用；行支持 Excel 导入自动判盈亏（`importStockTakingQuantity`） |
| 盘点盘盈/盘亏核销 | 经 transaction 更新台账 | `processStockTakingDifference`（Service） | ⚠️ **半成品**：逻辑存在（`WM_STOCK_TAKING`=107 生成 IN/OUT 流水），但无调用点 |
| 盘点审批 | — | task 只有 submit/finish/cancel | ⚠️ 手工两段式（PREPARE→APPROVING→FINISHED），**未接 BPM** |
| 批次 | `mes_wm_batch`（原料+成品统一） | `/mes/wm/batch/get/page` | ✅ 唯一编码/自动编码/批次条码；库存按 batch 维度，入库强校验 batch |
| 批次追溯 | 批次×流水×报工 | `/mes/wm/batch/forward-list` `/backward-list` `/purchase-sources` `/sales-targets` `/process-trace` `/get-by-sn` | ✅ 已闭环，向前/向后/来源/去向/工序/SN 反查 |
| SN 号池 | `mes_wm_sn` | `/mes/wm/sn/*`（`generateSnCodes`） | ⚠️ 只生成"号码池"，单据/库存/流水**均无 SN 维度** |
| 条码生成 | `mes_wm_barcode(_config)` | 各业务对象创建时 `autoGenerateBarcode` | ✅ 18 类 biztype，受 config.autoGenerateFlag 控制 |
| 条码内容 | config.contentFormat | `{BUSINESSCODE}` 单占位 | ⚠️ 无"物料+批次+编号+库位"组合字段 |
| 标签打印/成图 | config.defaultTemplate(仅字符串) | 无 | ❌ 无打印/渲染/成图接口 |
| 扫码服务端 | — | 无 | ❌ 收发货/领料/盘点均无 scan 校验 |
| 设备→物料→库存 | `mes_dv_machinery.item_id` | 创建设备自动建料并入设备仓 | ✅（阶段2，`docs/machinery_equipment_material_inbound.md`） |

---

## 3. 逐条需求差距与建议落点

### 3.1 需求3：物资二维码/标签打印，绑定批次、编号、库位，配合资产与物资追溯

| 子需求 | 现状 | 差距 | 建议后端落点 |
|--------|------|------|--------------|
| 二维码/标签打印 | 只存条码字符串，config 有 `defaultTemplate` 字段 | **无成图、无模板渲染、无打印接口** | 新增"标签打印"能力：① 条码/二维码图片生成（BarcodeFormatEnum 已有 QR/CODE39/EAN13/UPC-A 枚举）；② 打印模板（按 bizType 取字段组合 → 渲染文本/图片）；③ 打印接口（单条/批量，可入打印队列）。参考文件：`MesWmBarcodeServiceImpl`、`MesWmBarcodeConfigDO.contentFormat` |
| 绑定"批次+编号+库位" | content 仅 `{BUSINESSCODE}` | 条码不内嵌组合字段，无法一码携带业务结构 | 扩展编码规则：config 支持多占位符组合（如 `{CODE}+{BATCH}+{LOCATION}+{SN}`）；或保留"码→(bizType,bizId)→对象"反查，配合打印模板字段展示实现"标签带全信息" |
| 资产与物资追溯 | 设备→物料→设备仓已做（阶段2）；批次追溯对原料/成品已闭环 | 追溯到批次粒度；**单品 SN 追溯断**；库存调整/盘点核销/移库是否纳入批次链需核对 | 若需"资产/物资统一追溯视图"：以 `mes_wm_transaction` 为主链补统一追溯查询（入库→库存→出库/领用），覆盖盘点核销(107)、移库等 bizType；单品级见 3.3 SN |

### 3.2 需求4：实时库存查询、定期盘点、盘点数据导入、自动核算盘盈盘亏、更新库存台账

| 子需求 | 现状 | 差距 | 建议后端落点 |
|--------|------|------|--------------|
| 实时库存查询 | 台账分页 + available 现算 | available 为页面计算；reserved 仅覆盖领料/销售出库；**在途字段空转** | 若需"可用量统一口径/在途"，补：`inTransitQuantity` 的写入与冲销（调拨在途）、reserved 覆盖面决策 |
| 定期盘点 | plan 只"圈定一次范围"（按仓库/库区/库位/物料/批次参数） | 未发现**按周期自动生成任务/提醒**的调度 | 盘点方案加周期(每日/每周/月 + 下次盘点日)，由定时任务到期生成 task 并通知（可放 `MesWmStockTakingPlanService`） |
| 盘点数据导入 | 行 Excel 导入（物料编码+批次+实盘数）自动判盈亏 | ✅ 已具备 | 可选：补扫码录入（见 3.3） |
| **自动核算盘盈盘亏、更新库存台账** | `processStockTakingDifference` 已实现：按结果差额生成 `MesBizTypeConstants.WM_STOCK_TAKING`(107) 的 IN/OUT 流水并经 `createTransaction` 更新库存 | **方法无任何调用方**；`finishStockTakingTask`(ServiceImpl:146) 只置 FINISHED+解冻 | **首选接线方案**：完成盘点时自动核销（finish 内调用）或新增"核销"端点；补幂等（仅允许核销一次）、可查询核销流水、并发防护。涉及文件：`MesWmStockTakingTaskServiceImpl`(:234 方法体/接口)，Controller 补入口+权限 |
| 盘点审批 | task：submit 置 APPROVING+可选冻结，finish 要求 APPROVING | 手工两段式，无 BPM | 若要与其余仓储单据一致走真实 BPM：参照 `MesWmItemReceiptStatusListener`/阶段1 三单据模式接入；否则保持现状即可，文档注明口径 |

### 3.3 需求5：全品类条码/二维码管理，串联出入库/领用/盘点，批次与单品精准追溯

| 子需求 | 现状 | 差距 | 建议后端落点 |
|--------|------|------|--------------|
| 全品类启用条码 | 按 bizType 的 config.autoGenerateFlag 自动生成；物料/批次/SN/库位等已覆盖 | STOCK/供应商/客户类无生成入口；**非强制**，未生成则无码可扫 | 明确"启用范围"，对需全品类强制的主数据（物料/批次/库位/SN）做启动校验与补码 |
| 串联出入库/领用/盘点 | 各单据已建（收料/杂项/领料 productissue/退料 returnissue/盘点） | **服务端无扫码入口**：收货/发料/领料/盘点点行不能"扫条码/SN/批次定位并校验" | 提供统一"扫码解析"接口：按 content 或 (bizType,bizId) 或 SN/批次号解析出物料/批次/库位，供各单据行快速带入并校验（与物料、批次启用、库位匹配）；盘点行录入复用 |
| 批次与单品精准追溯 | 批次追溯已闭环 | **单品（SN）未进库存链**：`mes_wm_sn` 仅号池，`mes_wm_material_stock`/`mes_wm_transaction` 均无 sn 维度，`isSerialManaged` 无消费方 | SN 单品链路（改动较大）：库存/流水/单据行支持 SN；启用 `isSerialManaged` 物料的入库生成/绑定 SN、出库核销 SN；提供"SN 在库位置/历史去向"查询；盘点支持按 SN 单件核对 |

---

## 4. 按"就绪度"归类缺口（建议实施时按此切里程碑）

### 4.1 半成品：逻辑已有，只差接线（改动小、风险低）
- **盘点差异自动核销**：`MesWmStockTakingTaskServiceImpl#processStockTakingDifference` 已能生成盘盈/盘亏流水并更新台账，接上完成盘点即触发/独立端点 + 幂等即可闭环需求4"自动核算盘盈盘亏、更新库存台账"。

### 4.2 模型已有，需补能力（中改）
- **标签打印与成图**：利用已有 BarcodeFormatEnum/条码表，补图片生成、模板渲染、打印接口。
- **条码内容组合字段 / 一码多信息**：扩展 contentFormat 多占位符（物料/批次/库位/编号/SN）。
- **服务端扫码**：统一"解析条码/SN/批次"接口，供收发货、领料、盘点行复用。
- **盘点 BPM（可选）** 与 **定期盘点调度（可选）**。
- **在途/可用量口径**（若业务要求在途）。
- **追溯链补齐**：把盘点核销(107)、移库等 bizType 纳入批次/流水追溯（核对现 forward/backward 是否已含）。

### 4.3 需新增模型 / 较重构（大改，按需立项）
- **SN 单品库存链**：库存、流水、单据行增加 SN 维度 + 出入库核销 + 单件追溯查询 + 盘点单件核对。
- **资产属性**：若"资产"不止设备台账，需在物料侧补资产编号/归属/启用日期/报废等属性，与设备台账合并视图。
- **销售发运级追溯**（如要求按出库单 SN/批次追溯去向明细）。

---

## 5. 建议实施顺序

| 优先级 | 事项 | 理由/依据 | 主要涉及 |
|--------|------|-----------|----------|
| P0 | 盘点完成自动核销盘盈盘亏 | 逻辑现成（差异核销已编码），收益直接，代价最小；直接命中需求4核心 | `MesWmStockTakingTaskServiceImpl`(+Controller/幂等/流水查询) |
| P0 | 标签打印（成图+模板+打印） | 需求3硬性项；当前完全缺失 | 条码服务+config+打印接口；BarcodeFormatEnum 复用 |
| P1 | 服务端扫码 + 盘点扫码录入 | 需求5"串联出入库/领用/盘点"关键 | 统一扫码解析接口，单据行接入 |
| P1 | 条码内容组合字段 / 一码携带批次·库位·编号·SN | 配合打印与追溯 | contentFormat 多占位符 |
| P1 | SN 单品库存链 | 需求3/5"单品精准追溯" | 库存/流水/单据 SN 维度 + 核销 + 单件追溯 |
| P2 | 盘点接 BPM、定期盘点调度 | 与阶段1口径一致化、需求4"定期" | 参照阶段1三单据模式；调度 job |
| P2 | 在途/可用量口径、资产属性、销售发运追溯 | 依业务需要再定 | — |

> 建议先做 P0 两项形成"闭环样板"，再按 4.2/4.3 推进；每项按跨模块/库表变更在完成后执行 `mvn compile -pl yudao-module-mes -am -q`，涉及 MDM/BPM 再全量编译。数据库脚本遵循 sql-syntax/sql-script 规范（无 tenant_id、ADD COLUMN 先查存在）。