commit 371e219505feddf41681157c449132ae7e4b7b40
Author: User <user@example.com>
Date:   Fri Apr 17 10:09:12 2026 +0800

    Initial commit: Add water factory IoT whitepaper

diff --git a/water_factory_iot_whitepaper.md b/water_factory_iot_whitepaper.md
new file mode 100644
index 0000000..6b494f5
--- /dev/null
+++ b/water_factory_iot_whitepaper.md
@@ -0,0 +1,252 @@
+# 💧 水厂智能货柜（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-商业化**：全面对接货柜节点，开启自动化交付。
+
+
+
+
+
+
+