#智能货架 MES Web App 使用与配置 Playbook

适用对象：系统管理员、集成运维、SMT 物料员 / 上料员、现场班组长。

适用范围：MES Web App 中的智能货架正式业务页与联调 / 运维页。

更新时间：2026-05-16。

重要边界：货架出库只表示“料盘已从货架取出”，不等于“已上料”；产线上料必须继续走 MES 上料防错。

#1. 角色与入口

#1.1 权限

如果页面显示“无权限”，先让系统管理员检查账号角色是否包含上面对应权限。

#1.2 Web 入口

正式业务入口在左侧菜单：

• SMT 管理 → 智能货架总览
• SMT 管理 → 货架入库
• SMT 管理 → 货架备料出库
• SMT 管理 → 待上料队列
• SMT 管理 → 货架库存

集成 / 运维入口在左侧菜单：

• 集成与运维 → 智能货架联调台

正式业务页给现场人员使用；联调台只给集成运维使用，不作为日常作业入口。

#2. 核心概念

#3. 上线前配置 Playbook

#3.1 现场信息准备

上线前先收齐以下信息。没有这些信息，不要宣布真实货架可上线。

密钥不能写入文档、截图或聊天记录；Web 页面也不录入明文 token。真实值放部署环境变量 / secret，系统只保存 env:<NAME> 这种引用。

#3.2 现场配置落地指导

现场配置分三层：中控服务、货架设备、货架储位。现场人员在 Web App 里只核对和使用配置；真实配置由系统管理员 / 运维在部署环境变量、secret 或数据库配置层完成。

#3.2.1 中控服务配置

中控服务记录对应 SmartShelfService。上线前至少确认：

推荐的 tokenRef 形态：

text
outboundAuthHeaderName = Authorization\noutboundAuthTokenRef = env:SMART_SHELF_OUTBOUND_TOKEN\ninboundAuthHeaderName = x-integration-key\ninboundAuthTokenRef = env:SMART_SHELF_CALLBACK_TOKEN

给供应商 / 中控配置的 MES callback 地址：

text
<MES_BASE_URL>/api/smart-shelves/callbacks/stock-in\n<MES_BASE_URL>/api/smart-shelves/callbacks/stock-out

配置后用联调台确认：默认配置能读到中控服务；命令日志里出站请求带正确 header 名；callback 无 header 或错误 token 时应被拒绝，正确 token 才进入回调日志。

#3.2.2 货架设备配置

货架设备记录对应 SmartShelfDevice。上线前至少确认：

多货架上线时，每台货架都必须有唯一 shelfCode；不要复用 Shelf-01668。

#3.2.3 储位配置

储位记录对应 SmartShelfLocation。现场贴纸必须和系统储位一致：

配置储位后，现场按 A/B 面抽样检查：每面至少选首列、末列和一个中间列，让供应商触发一次入库回调，确认 MES 库存显示的 side / userRow / userColumn 与实际灯位一致。

#3.2.4 现场上线配置步骤

1. 固定中控服务器 IP 和端口，确认 MES 服务器能访问 baseUrl。
2. 固定 MES 对中控开放的 callback base URL，确认中控服务器能访问 MES。
3. 在部署环境 / secret 中配置出站和入站 token 明文；系统配置层只保存 env:<NAME> 引用。
4. 配置或核对中控服务字段：code、baseUrl、hostIp、enabled、鉴权 header、tokenRef、timeoutMs。
5. 配置或核对货架设备字段：shelfCode、fixedIp、macAddress、enabled、meta.modeCodes。
6. 配置或核对储位字段：side、userRow、userColumn，并和现场 A/B 面贴纸逐项对齐。
7. 打开 集成与运维 → 智能货架联调台 → 默认配置，核对 Web 读到的配置和现场表一致。
8. 按 user_docs/smart_shelf_go_live_runbook.md 执行入库 smoke、出库 smoke、手动对账 smoke。
9. smoke 通过后再开放给物料员使用正式业务页；未通过时只允许继续联调，不允许现场绕过上料防错。

#3.3 在 Web App 里核对默认配置

路径：集成与运维 → 智能货架联调台 → 默认配置。

核对项：

1. 中控服务

• 编码：默认 SMART-SHELF-MIDDLE-001。
• 名称：默认智能货架中控服务。
• 地址：当前中控服务 baseUrl。
• 主机 IP：当前中控服务器 IP。
• 超时：默认 5000 ms。
• 状态：必须为启用。

1. 默认设备

• 货架编码：默认 Shelf-01668。
• 固定 IP / MAC：必须与现场设备一致。
• 状态：必须为启用。

1. 储位摘要

• 当前首台货架 A/B 面储位已按现场范围预置。
• 回调 Header：例如 x-integration-key。

当前版本 Web App 以“核对配置”为主；真实 baseUrl、tokenRef、设备固定 IP 等配置修改由系统管理员 / 运维在部署配置或数据库配置层完成，不在业务页输入明文密钥。

#3.4 货架储位配置口径

当前首台货架 Shelf-01668 的预置储位范围：

如果现场贴纸、行列、A/B 面和上表不一致，先停用上线验证，更新配置后再测试。

#3.5 备料出库前的 MES 基础配置

货架备料出库 页面按 runNo + stationId + slotCode 查询候选料盘，所以在使用前必须满足：

1. 工单 / 批次已经在 MES 中存在。
2. 产线站位和槽位已经配置好。
3. 当前槽位有期望物料或替代料规则。
4. 对应物料已经完成智能货架入库，并在 货架库存 页面显示为在架。
5. 站位类型必须能进入上料防错链路；不要把非上料站位拿来创建货架出库任务。

#4. 日常作业 Playbook

#4.1 货架入库

路径：SMT 管理 → 货架入库。

适用场景：新料盘进入智能货架，MES 先创建唯一单盘记录，再通知中控服务等待货架回调储位。

操作步骤：

1. 打开 货架入库。
2. 填写必填项：

• 物料编码：料号，例如 MAT-001。
• 批次：物料批次，例如 LOT-A。

1. 填写可选项：

• 原始二维码：扫描来料标签原文；允许重复，仅作追溯辅助。
• 货架编码：留空使用默认货架；多货架场景必须填写目标 shelfCode。
• 面别：A 或 B。
• 初始数量：单盘初始数量。
• 入库数量：本次入库数量；留空时按初始数量处理。

1. 点击 发送入库任务。
2. 页面返回：

• 入库任务 <taskNo>
• MES 单盘码 <reelId>
• 协议 reelID <protocolReelId>
• 任务下发 / 中控接收 状态

1. 现场按货架提示放入料盘。
2. 等待中控服务回调 stock-in。
3. 打开 货架库存，用 MES 单盘码、物料或批次查询，确认该料盘已在架并显示储位。

验收标准：

• 货架库存 能看到该 reelId。
• 库存状态为在架相关状态。
• 储位显示 shelfCode / side / userRow / userColumn。
• 如果没有回调，库存页不会凭空出现该料盘；应由运维查看联调台的命令日志和回调日志。

注意事项：

• 不要把 rawBarcode 当唯一单盘码；同一采购订单的多盘物料可能标签完全一样。
• 现场上料优先扫描 MES 单盘码 reelId，或协议 reelID。
• 入库任务发送成功不代表已经入架，必须等货架反馈实际储位。

#4.2 查询货架库存

路径：SMT 管理 → 货架库存。

用途：查看 MES 当前认为“在货架上”的料盘和储位。

筛选项：

• MES 单盘码
• 物料编码
• 批次

列表字段：

• 最近回调
• 料盘：MES 单盘码，下面显示原始标签或协议码。
• 物料 / 批次
• 储位
• 数量：当前数量 / 初始数量。
• 库存状态
• 料盘状态

使用建议：

1. 入库回调后，用 MES 单盘码 搜一次，确认储位。
2. 备料前，用物料编码或批次确认候选料盘是否在架。
3. 如果现场货架和 MES 库存不一致，不要直接改库；进入联调台做手动对账。

#4.3 SMT 备料出库

路径：SMT 管理 → 货架备料出库。

适用场景：按 SMT 批次、站位和槽位，从智能货架选择候选料盘并下发亮灯 / 出库任务。

操作步骤：

1. 打开 货架备料出库。
2. 填写槽位定位信息：

• 批次号：runNo。
• 站位 ID：站位主键 / stationId。
• 槽位：slotCode。

1. 系统自动查询候选料盘：

• 候选查询只读，不会锁定库存。
• 候选会显示料盘、物料、批次、储位、数量、匹配类型。
• 期望料 表示命中当前槽位期望物料；替代料 表示命中替代料规则。

1. 点击候选行的 选择，系统会把 MES 单盘码填入 MES 单盘码 输入框。
2. 如需手工指定多个料盘，在 MES 单盘码 中一行填一个 reelId。
3. 填写 灯色：只能使用 绿、黄、紫、蓝、白。
4. 单个料盘时可填写或自动带出 期望物料。
5. 点击 发送出库任务。
6. 页面返回：

• 出库任务 <taskNo>
• 已受理料盘 / 未受理料盘
• 任务下发 / 中控接收
• 任务明细状态

1. 现场按货架亮灯取出料盘。
2. 等待中控 stock-out 回调。
3. 打开 待上料队列，确认该料盘进入待上料。

验收标准：

• 出库任务已下发并被中控接收。
• stock-out 回调后，料盘从在架库存移出。
• 待上料队列 出现对应 reelId，状态为待上料相关状态。
• 不会自动生成上料记录。

注意事项：

• 货架出库成功只代表“料盘已从货架取出”。
• 不要跳过上料防错。
• 如果候选为空，先检查：批次号、站位 ID、槽位是否正确；期望物料是否配置；对应物料是否已在架。
• 如果出库任务部分失败，按页面的未受理料盘和失败原因处理；不要重复点击造成多次出库。

#4.4 待上料队列与上料防错

路径：SMT 管理 → 待上料队列。

适用场景：查看已经从货架取出、但还没在产线完成上料确认的料盘。

操作步骤：

1. 打开 待上料队列。
2. 按需要筛选：

• 批次号
• 机台 ID
• 站位码
• 物料编码
• MES 单盘码

1. 在列表中找到目标料盘。
2. 在 上料扫码 列点击 复制，复制 MES 单盘码；或点击 去上料。
3. 系统进入 /mes/loading/scan-through，并携带批次、站位、槽位和料盘上下文。
4. 在上料防错页面扫描 MES 单盘码 reelId 或协议 reelID。
5. 通过上料防错后，系统才生成正式上料记录，并把料盘状态推进到已上料。

验收标准：

• 上料页面提示来自智能货架待上料上下文。
• 扫错料、错站位、错槽位时不能通过防错。
• 通过防错后，待上料队列不再显示该料盘。

注意事项：

• 原始标签二维码可能重复，当前阶段不推荐直接用原始标签作为唯一扫码依据。
• 如果现场必须扫原始标签，需要先设计消歧规则；不能临时绕过单盘码。

#5. 运维 / 联调 Playbook

路径：集成与运维 → 智能货架联调台。

联调台用于集成、运维和异常排查，不给普通现场作业人员日常使用。

#5.1 查看默认配置

在 默认配置 卡片核对：

• 中控服务编码、名称、地址、主机 IP、超时和启用状态。
• 默认设备货架编码、固定 IP、MAC 和启用状态。
• 储位数量、A/B 面数量、回调 Header。

如果真实现场参数和页面不一致，不要继续真实货架操作；先让系统管理员更新配置。

#5.2 命令日志

用途：查看 MES 下发给中控服务的命令，例如入库 pullBarcode、出库 systemStockOut、对账查询等。

重点看：

• 命令类型。
• 状态：PENDING、SENT、SUCCESS、FAILED、RETRYING。
• 发送时间、完成时间。
• 失败错误。
• 请求 / 响应详情。

重试规则：

1. 只有 FAILED 命令可以重试。
2. 同一命令同时只允许一个 retry 在飞。
3. 对 systemStockOut 这种真实动作命令，重试前必须先核对现场状态和中控日志，避免重复亮灯 / 重复出库。
4. 查询类失败优先重新触发对应查询或对账。

#5.3 回调事件

用途：查看中控服务回调 MES 的 stock-in / stock-out 事件。

重点看：

• 事件类型：STOCK_IN / STOCK_OUT。
• 处理状态：ACCEPTED、DUPLICATE、EXCEPTION、REJECTED、FAILED。
• shelfCode、储位、料盘码。
• 错误信息。
• payload 详情。

处理建议：

• ACCEPTED：MES 已接受并处理。
• DUPLICATE：重复回调，通常不用处理。
• REJECTED：字段、货架、储位、料盘或鉴权不符合要求，需要排查。
• EXCEPTION：业务异常，例如异常出库，需要结合现场状态处理。
• FAILED：系统处理失败，需要开发 / 运维介入。

#5.4 手动对账

用途：主动查询中控服务库存、出库列表和异常储位，与 MES 投影比较。

操作步骤：

1. 打开联调台 手动对账 区域。
2. 选择或填写货架编码；默认可使用当前默认货架。
3. 点击 执行手动对账。
4. 查看本次 run：

• 状态。
• 查询到的在架数量、出库列表数量、异常数量。
• 差异列表。

差异类型：

#5.5 处理对账差异

对每条差异可以执行：

每次处理都要填写备注，说明现场依据、处理人判断或关联工单。系统会记录处理人、处理时间和 audit log。

当前差异处理是“备注类闭环”，不会自动清货架异常，也不会自动修正 MES 库存投影。清异常 / 修正投影属于危险操作，必须等供应商语义确认后单独设计权限和确认流程。

#5.6 fake 联调工具

联调台中的 fake stock-in / stock-out / replay 工具只用于本地或 fake controller 阶段。

真实环境注意：

• 不要用 fake 工具代替真实货架验证。
• 不要在生产环境随意回放 callback。
• 需要回放真实 payload 时，先按 user_docs/smart_shelf_go_live_runbook.md 的 smoke 流程确认目标环境和写入影响。

#6. 推荐端到端验收流程

#6.1 fake / 本地联调验收

1. 启动 MES Web、MES Server 和 fake controller。
2. 登录具备 SYSTEM_INTEGRATION、LOADING_VIEW、LOADING_VERIFY 的账号。
3. 在 货架入库 创建测试料盘。
4. 用 fake stock-in 或 callback replay 让 MES 接收入库回调。
5. 在 货架库存 确认料盘在架。
6. 在 货架备料出库 按 runNo + stationId + slotCode 查询候选并发送出库任务。
7. 用 fake stock-out 让 MES 接收出库回调。
8. 在 待上料队列 确认料盘出现。
9. 点击 去上料，进入上料防错。
10. 扫描 MES 单盘码，确认防错通过。
11. 在联调台执行手动对账；如果出现差异，用处理动作闭环。

#6.2 真实中控 smoke 验收

真实货架 smoke 必须先按 user_docs/smart_shelf_go_live_runbook.md 执行：

1. 中控查询 smoke：getShelfStorage、getStockOutList、getErrorLattice 返回 2xx。
2. callback 鉴权 smoke：无 header / 错 header 必须被 MES 拒绝；正确 header 才能进入处理。
3. 真实入库：正式入库页创建料盘，现场放入货架，库存页显示在架。
4. 真实出库：正式备料页发送出库，现场取料，待上料队列出现。
5. 上料防错：从待上料进入扫码，扫描 MES 单盘码，通过后生成上料记录。
6. 对账：联调台执行手动对账，差异能人工闭环。

#7. 常见问题处理

#7.1 入库任务发送失败

先检查：

1. 账号是否有 LOADING_VERIFY。
2. 物料编码、批次 是否填写。
3. 面别 是否为 A 或 B。
4. 初始数量、入库数量 是否为数字。
5. 中控服务是否可访问。
6. 联调台命令日志是否有失败详情。

#7.2 入库任务已发送，但库存页没有料盘

可能原因：

1. 中控没有回调 MES。
2. 回调被鉴权拒绝。
3. 回调的 shelfCode / side / userRow / userColumn 不在已启用储位中。
4. 回调的 reelID 与 MES 生成的协议码不一致。
5. 回调被判定为重复或异常。

处理：进入联调台查看回调事件和命令日志；必要时执行手动对账。

#7.3 SMT 备料没有候选料盘

先检查：

1. 批次号、站位 ID、槽位 是否正确。
2. 当前槽位是否配置期望物料 / 替代料。
3. 目标物料是否已经在 货架库存 中在架。
4. 料盘状态是否已经被出库、保留、异常或待上料。
5. 站位是否属于可上料防错的站位。

#7.4 出库后找不到待上料记录

先检查：

1. 出库命令是否真正被中控接收。
2. 中控是否回调 stock-out。
3. 回调是否 ACCEPTED。
4. 出库回调里的 taskOutInfo 是否能关联到 MES 出库任务明细。
5. 是否已经完成上料防错，导致队列中不再显示。

#7.5 扫描原始标签无法上料

这是预期边界。原始标签 rawBarcode 可能重复，不能保证单盘唯一。当前阶段现场应扫描：

1. MES 单盘码 reelId；或
2. 协议 reelID / protocolReelId。

如果现场流程必须扫原始标签，需要先设计同标签多盘消歧规则，不能直接绕过。

#7.6 对账发现差异

处理顺序：

1. 不要直接修改数据库。
2. 查看差异类型和储位 / 料盘信息。
3. 核对现场货架实际状态。
4. 查看命令日志和回调事件。
5. 使用 确认差异、忽略差异、标记已处理 或 重新打开 记录处理结论。
6. 对需要清异常或修正投影的场景，等待供应商语义确认和系统危险操作功能支持。

#8. 上线前检查清单

上线前至少确认：

• [ ] 业务账号权限已配置：查看、操作、运维分离。
• [ ] 中控服务 base URL、服务器固定 IP、端口、防火墙已确认。
• [ ] MES callback URL 已提供给供应商并从中控服务可达。
• [ ] MES → 中控、 中控 → MES 的 header 名和 tokenRef 已配置。
• [ ] token 只在 secret / env 中保存，未写入文档、截图或日志。
• [ ] Shelf-01668 的 A/B 面、行列和现场贴纸一致。
• [ ] 真实 stock-in、stock-out、异常、重复回调 payload 样例已收集。
• [ ] taskOutInfo 是否原样回传已确认。
• [ ] callback 重传、ack、乱序语义已确认。
• [ ] actionType=-1/2、errorIn/errorOut、clearError 语义已确认。
• [ ] fake 端到端流程已跑通。
• [ ] 真实中控 smoke 已按 runbook 跑通。
• [ ] 对账差异能人工闭环并留下 audit log。

#9. 操作证据留存

每次联调或上线前演练，至少保存：

• 绝对时间窗口。
• 操作账号和角色。
• 中控 base URL、MES callback URL、header 名；不要保存 token 值。
• 入库任务号、出库任务号、MES 单盘码、物料、批次、储位。
• 命令日志截图或导出。
• 回调事件截图或导出。
• 对账 run ID 和差异处理记录。
• 供应商中控日志时间点。
• 失败时的 HTTP status、response body、MES error code 和现场处理结论。

#10. 不要做的事

• 不要把原始二维码当作唯一单盘码。
• 不要跳过上料防错。
• 不要把“货架出库”当成“已上料”。
• 不要在文档、截图、聊天记录里保存 token 明文。
• 不要在真实环境随意使用 fake replay。
• 不要在未确认供应商状态机前执行清异常或自动修正 MES 投影。
• 不要通过直接改数据库来闭环对账差异。