cyj/water_factory_iot_whitepaper.md

💧 水厂智能货柜（IoT）分布式终端接入与自动化交付技术白皮书

一、 业务愿景与战略定位

本方案旨在通过 IoT（物联网） 硬件矩阵，实现水厂饮用水交付的全面自动化与去人工化。针对无屏幕、定位提货、套餐保值等核心需求，构建“线上订水、LBS 匹配、无感交付”的智慧物流体系。

---

二、 核心应用场景与业务需求模型

1. 定位提货与套餐保值逻辑

• 需求： 用户购买桶水套餐，不受后续调价影响；定位用户小区并呈现所有单元楼提水点，实现远程库存预览，防止用户“跑空”。
• 小程序实现：
  • 权益钱包：引入“虚拟储水池”概念，用户购买套餐后，账户记录为“待取桶数”，而非金额，实现锁价保值。
  • LBS 智能网格：首页通过 uni.getLocation 获取坐标，服务器根据经纬度反向检索关联小区，并在地图上以“桩位”形式展示该小区内所有单元楼下对应的提柜状态（空闲/库存数）。
  • 【新增机制：空柜自动调导 (Self-Correction)】：当某单元楼货柜库存为 0 时，地图图标转为置灰状态并显示“补货中”，同时系统自动计算并推荐该小区内距离最近的“有货柜机”。

2. 无屏幕式“无感核销”模式（蓝牙/云端直控）

• 需求： 货柜感应 + 云端瞬时指令”**模式。
  • 操作流：用户靠近货柜 \rightarrow 手机蓝牙自动识别设备号（Beacon 广播）或 LBS 确认经纬度重合 \rightarrow 小程序自动弹出“当前已到达XX单元提水点” \rightarrow 用户在手机点击“开门” \rightarrow 云端通过 MQTT 指令开锁。
  • 价值：降低硬件成本（无屏、防暴力），提升交互流畅度。

3. 故障闭环与客服联动系统

• 需求： 下单不开门、没电、库存不足等异常，自动切入客服协助。
• 业务逻辑：
  1. 主动监测：系统 15 秒内未收到门磁反馈，自动触发“开启失败弹窗”。
  2. 一键路由：弹窗直接集成“在线客服”与“紧急开锁申请”。对于电池电量低于 10% 或库存为 0 的柜体，小程序端自动置灰并置顶显示“联系客服维修/补货”。

4. 商家端（水厂）实时监控看板

• 需求： 实时获取补货、电量、库存等全量信息。
• 技术看板：
  • IoT 设备画像：每个柜子都有实时“血条”（电量指示）和“胃容积”（库存比例）。
  • 热力算法：根据库存消耗频率，自动标注哪些柜子属于“急需补货”级别。

5. 补货员/检修员管理系统（工单派发制）

• 需求： 考核规定时间内补货及检修。
• 小程序程序设定：
  • 强时效工单：系统检测到库存不足或电池耗尽，自动生成“4小时响应工单”指派给最近的运维员。
  • 到岗打卡：运维员必须到达柜体 5 米范围内（经纬度校验），才能开启“运维门”进行操作。
  • 闭环报告：补货完成后，自动上报最新重量数据，系统同步更新前台库存。

---

三、 全链路技术架构与数据流向

1. 四层架构模型

• 物理执行层（Edge）：基于 ESP32/工业级 4G 模组的主控板，集成继电器、重力传感器、温湿度计。
• 网络传输层（Network）：采用 MQTT 协议，基于 TLS/SSL 加密，确保指令在复杂小区环境下的秒级送达。
• 业务逻辑层（Service）：负责权益校验、库存动态调拨、支付分账逻辑判断。
• 应用展示层（Application）：用户小程序（取水/充值）、商家管理后台（核销）、补货员 App（工单管理）。

2. 高级交互序列图 (Sequence Diagram)

`mermaid sequenceDiagram participant U as 消费者小程序 participant S as 业务中台 (PHP/Node.js) participant M as MQTT 消息总线 (EMQX) participant C as 智能货柜终端 participant P as 微信支付分/代金券接口

U->>S: 1. 扫码查阅柜体 (LBS+设备ID)
S-->>U: 2. 返回可用库存 & 专属优惠券
U->>S: 3. 点击“确认取水” (权益预扣)
S->>P: 4. 冻结余额/校验代金券状态
P-->>S: 5. 状态确认
S->>M: 6. 下发指令 (QoS 1: 至少送达一次)
M->>C: 7. 物理开门指令 (带加密Nonce)
C->>C: 8. 传感器检测门启
C->>M: 9. 实时反馈：门已开
M-->>U: 10. 小程序提示：请取水
Note over C: 用户提取桶装水...
C->>C: 11. 传感器检测门闭 & 重量减扣
C->>M: 12. 最终交易报文 (补货建议点)
M->>S: 13. 结算请求
S->>S: 14. 正式扣减权益 & 生成财务报表

`

---

四、 通信协议与数据字典规范

1. 指令安全加固

采用 HMAC-SHA256 对指令进行签名，防止中间人攻击或恶意开门。 Payload 样本： json { "header": { "sn": "WH-CAB-2024-001", "ver": "1.2.0", "nonce": "8h7g2k1l" }, "body": { "action": "REMOTE_OPEN", "params": { "slot": 1, "timeout": 30 }, "sign": "5e8f...f2a1" } }

2. 状态机定义 (State Machine)

• IDLE: 空闲状态，等待指令。
• LOCKED: 权益校验通过，正在下发脉冲。
• BUSY: 用户正在交互（取水进行中）。
• MAINTENANCE: 故障或补货模式，小程序下线该节点。

---

五、 核心功能模块代码深度实现

1. 智能防刷与补偿逻辑 (小程序/后端)

问题场景：用户点了开门但信号不好，或者门坏了没开，如何保证不误扣费？

`javascript // 后端：具备“事务性”的开门逻辑 async function secureOpenProcess(userId, cabinetId) { const transaction = await db.startTransaction(); try { // 1. 锁券：先将福利券/水票设为“占用中” await transaction.collection('vouchers').update(query, { status: 'PENDING' });

// 2. 下发异步指令，设置 15 秒确认窗口
const result = await mqttService.publishWithAck(cabinetId, 'open', 15000);

if (result.ack === 'SUCCESS') {
  await transaction.commit(); // 指令送达，提交事务
  return { success: true };
} else {
  throw new Error('DEVICE_OFFLINE'); 
}

} catch (e) { await transaction.rollback(); // 失败回滚，水票自动返还 return { success: false, reason: e.message }; } } `

2. 补货员端：基于路径优化的库存盘点

`python

逻辑伪代码：根据告警级别生成最优补货路径

def generate_refill_route(warn_cabinets): # 排列优先级：告警等级(0-100) > 距离 priority_list = sorted(warn_cabinets, key=lambda x: (x.alert_level, x.distance)) return priority_list # 返回给补货员 App 的任务流 `

---

六、 智能货柜接入小程序的标准化流程 (Access Standard)

1. 核心逻辑：如何核验并完成取水（从下单到核销）

针对你疑惑的“下单后如何核验取水”，本项目采用 “虚拟权益池 + 动态指令核销” 机制。以下是详细的核验方案：

A. 权益发放（下单阶段）

1. 资产化：用户下单购买后，系统不只是生成一个订单，而是在数据库中为用户 OpenID 增加“电子水票/桶数”资产（如：可用余额 +10 桶）。
2. 权益凭证：系统生成一组不记名的电子权益 ID，状态标记为 UNUSED（未使用）。

B. 身份与位置核验（扫码阶段）

1. 设备匹配：用户扫码，小程序获取 cabinet_id。系统即刻下发 MQTT PING 指令确认柜机通讯链路活跃。
2. **位置强校验 **(针对无蓝牙环境增强)****：
   • 小程序调用 uni.getLocation 获取手机经纬度。
   • 后端比对：将手机位置与柜子的注册坐标进行计算（Haversine 公式）。
   • 判定：距离 < 50 米时，判定为“到店”，激活“开门按钮”；否则提示“请到达柜机旁操作”。
3. 在线预警：若 MQTT 链路超时未响应，按钮置灰并提示“柜机离线中，请稍后再试”，防止用户重复扣款。

C. 权益核销（开门阶段）

1. 预锁定：用户点击“确认开门”，后端立即执行 Transaction（事务）：
   • 查询用户是否有可用余额。
   • 将 1 份权益设为 LOCKING（锁定中），防止并发重复开启。
2. 指令下发：通过 MQTT 向货柜发送 UNLOCK_CABINET 指令。
3. 状态反馈：
   • 成功：货柜反馈“门已开启”，权益标记为 USED（已使用），生成核销流水。
   • 失败：若 15 秒内未收到开门反馈，直接接入客服系统，让客服处理这笔订单。

2. 身份识别与设备绑定（参数二维码体系）

• 二维码本质：机身二维码并非静态图片，而是携带设备 ID 的“动态索引链接”（例如：https://domain.com/q?id=10001）。
• 批量生产规范：
  • 映射逻辑：后端建立 设备SN - 设备ID - 二维码URL 的 1:1 映射表。
  • 自动化生成：通过 Node.js/Python 脚本调用 qrcode 库，根据数据库 ID 批量生成 100+ 物理贴纸。
  • 施工校验：印刷贴纸需附带明文编号，安装时由运维端扫码并上传 LBS 坐标，完成“人-机-地”三位一体绑定。

2. “扫码即看”的信息同步机制

• 跳转逻辑：利用微信“普通链接二维码跳转小程序”协议，所有货柜二维码均指向同一个小程序页面。
• 动态解析流程：
  1. 取参：小程序在 onLoad(options) 中解析 options.q 获取 cabinet_id。
  2. 溯源：小程序以该 ID 为 Key，实时请求云端接口 /api/cabinet/info。
  3. 渲染：后端实时查询该柜体的 IoT 状态（库存剩几桶、电池余量、是否维修），前端实现“千柜千面”的精准显示。

3. 前端交互与权限校验逻辑

`javascript // 基于 UniApp 的扫码取水核心逻辑 async function startWithdrawWater(cabinetId) { // A. 获取用户地理位置，确保在柜机旁 const location = await uni.getLocation({ type: 'gcj02' });

// B. 调用后端校验接口：余额充值情况 + 设备在线状态 const checkRes = await request('/api/cabinet/check', { cabinetId, userId: global.userId, lat: location.latitude, lng: location.longitude });

if (checkRes.status === 'READY') { // C. 唤起蓝牙或网络指令下发确认框 uni.showModal({ title: '发现提水点', content: '确认开启 1 号柜门取水？', success: async (res) => { if (res.confirm) { // D. 下发开门指令 const openRes = await request('/api/cabinet/open', { cabinetId }); if(openRes.code === 0) { // E. 进入倒计时监听，等待设备反馈开门信号 monitorDoorStatus(cabinetId); } } } }); } } `

4. 数据通信闭环（双向反馈）

• 云端指令控制：小程序点击后，通过 HTTPS POST 请求后端，后端转发 MQTT 指令至货柜。
• WebSocket 状态同步：小程序前端通过 Socket 实时监听后端推送。当货柜感应器检测到“物理门已开启”或“门已关闭”，小程序界面同步切换：[待取水] -> [取心中] -> [成功扣费/取水完成]。

---

七、 企业级安全与高可用保障

1. 容灾机制（断网续传）：货柜具备离线存储功能。若断网期间发生本地开门（手动/钥匙），恢复后第一时间同步日志。
2. 【调整】续航与能源管理：考虑到实际布放环境，设备采用**“大容量工业锂电池 + 定期换电/充电”**模式。系统集成低电量预警：
   • 电量梯级预警：低于 20% 时推送后台补货员工单；低于 10% 时小程序端自动置灰并停止接单，防止物理开锁力矩不足。
3. 异常处理机制：提供“远程强制开锁”与“一键报漏及退费回滚”功能，确保用户权益不受损。 【新增：离线开门补偿逻辑】

---

八、 实施路线图 (Roadmap)

• Q1-调研期：完成 4G 模组与主控板的底层通信打通。
• Q2-内测期：完成试点投放，验证传感器精度。
• Q3-商业化：全面对接货柜节点，开启自动化交付。