幂等MES导出怎么做?manufacturing-wechat-miniapp-starter 幂等键、载荷哈希与回执验证
幂等MES导出怎么做?manufacturing-wechat-miniapp-starter 幂等键、载荷哈希与回执验证
manufacturing-wechat-miniapp-starter 是一个面向中小制造业的微信小程序起步模板(starter),把员工熟悉的微信小程序变成一线数据入口。它最容易被做错的一环,是把报工、考勤、质量事件可靠地回传给 MES——而本文要讲的核心就是:幂等MES导出如何用"幂等键 + 载荷哈希 + 回执验证"三件套实现,让同一次现场事件只被 MES 计一次账,网络重试也绝不翻倍。
一、为什么 MES 导出必须"幂等"?
车间场景里,重复提交几乎不可避免:
- 员工点完"提交报工"没看到结果,又点了一次;
- 弱网环境下请求超时,客户端自动重试;
- 定时同步任务重跑,把同一批事件再推一遍。
如果 MES 端不做去重,一次报工可能被记成两次,产量、工时、质量数据立刻失真。README 中给出的原则是:失败或不确定的写入应保持"待处理"状态以便安全重试,而不是被计两次(见 README.md 的 MES 集成模型章节)。
二、幂等 MES 导出的三个核心部件
导出入口是云函数网关的 mes.export 动作(handler.js),真正的逻辑集中在 MesConnector.exportRecord。
1️⃣ 稳定的幂等键(Idempotency Key)
每条要导出的业务事件必须携带一个稳定的幂等键:同一事件无论重试多少次,键值不变;不同事件键值不同。
- 命名建议采用
记录ID-版本号的形式,例如演示脚本中的attendance-demo-001-v1(demo.js); - 格式受严格约束:只允许 8~80 个字符的小写字母、数字和连字符,不合规直接拒绝,错误码为
IDEMPOTENCY_KEY_INVALID(connector.js)。
2️⃣ 载荷哈希(Payload Hash)
光有幂等键还不够——如果同一个键对应的数据被篡改或改写过,"去重"反而会掩盖问题。因此导出前会对 payload 计算 SHA-256 哈希(connector.js)。
关键点在于哈希前会先把对象序列化成规范化 JSON(canonical JSON):对象按键名排序后递归序列化(crypto.js)。这样无论字段书写顺序如何,小程序侧和 MES 侧算出来的哈希必然一致,哈希才能真正用于比对。
载荷哈希有两重用途:
- 判断"这次重试是不是同一个请求"——同键同哈希才算安全重放;
- 校验 MES 返回的回执是否对应本次数据。
3️⃣ 回执验证(Receipt Verification)
MES 返回的内容不是"黑盒信任",而是逐条验证:
- 必须明确返回
accepted: true并附带receiptId,否则报MES_RECEIPT_INVALID; - 如果 MES 回执中带了
payloadHash,必须与本地计算值完全一致,否则报MES_RECEIPT_HASH_MISMATCH(connector.js)。
验证通过后,回执(幂等键、载荷哈希、receiptId、acceptedAt)会被保存下来,供后续重放直接命中(connector.js)。同时会写入一条 mes.exported 审计事件——注意审计只记录事件标识,不包含导出的原始载荷,这是隐私边界的一部分(connector.test.js 专门验证了这一点)。
三、重复请求的四种结局 📋
| 场景 | 处理方式 | 结果 |
|---|---|---|
| 同键 + 同载荷 | 命中本地已存回执 | 直接返回原始回执,标记 replayed: true,不再发起网络调用 |
| 同键 + 不同载荷 | 拒绝 | 错误码 IDEMPOTENCY_CONFLICT |
| 幂等键格式非法 | 拒绝 | 错误码 IDEMPOTENCY_KEY_INVALID |
| MES 未确认 / 回执哈希不符 | 拒绝 | MES_RECEIPT_INVALID / MES_RECEIPT_HASH_MISMATCH |
这四种行为在 tests/connector.test.js 中有完整断言:重放命中本地回执后,底层传输层只收到 1 次调用(transport.calls.length === 1),这正是"幂等"最直观的证明。
四、本地快速体验
项目零依赖,只需 Node.js 20+:
npm test # 运行全部合成测试,含幂等回执用例
npm run demo # 运行确定性演示
demo 会模拟一次考勤打卡并导出到内存版 MES,输出内容仅包含合成标识、一个 MES 回执 ID 和一个 SHA-256 载荷哈希(demo.js)。如果想接入真实 MES,只需替换 MesConnector 的 transport,把请求发往自己的适配器,三件套逻辑原样保留。
五、关键文件索引 🔗
- 导出核心逻辑:src/connector.js
- 规范化 JSON 与 SHA-256:src/crypto.js
- 网关入口
mes.export:cloudfunctions/employeeGateway/handler.js - 幂等性测试用例:tests/connector.test.js
- 演示脚本:examples/demo.js
- 集成模型说明:README.md
小结
幂等MES导出并不神秘,核心就三句话:每个事件一个稳定键、每次导出算一次规范化哈希、每份回执都验证一遍。做到这三点,重复请求要么安全回放、要么明确报错,MES 账本永远不会被重复数据污染。想在自己的项目里落地,直接参照 manufacturing-wechat-miniapp-starter 的 connector 实现,替换成你自己的 MES 适配器即可。