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

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

1. 总体结论

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

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

盘点盘盈盘亏自动核销"未接线"（processStockTakingDifference 无任何调用方，finish 只置状态）——最确定、代价最小的缺口。
标签打印 / 扫码 / 条码组合字段整体缺失（只有条码字符串与 config 里的模板名字段）。
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 先查存在）。