# 设备与门店模块业务说明

> 本文档描述设备管理、门店管理、库存管理及设备回调链路。
> 帮助开发人员快速理解"为什么这样设计"以及各环节的特殊处理方式。

---

## 一、设备管理

### 1.1 Device 实体

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 雪花算法主键 |
| deviceId | String | 设备SN号（唯一标识） |
| shopId | Long | 所属门店ID |
| name | String | 设备名称 |
| authToken | String | 设备认证Token |
| status | Integer | 设备状态 |
| doorStatus | String | 门状态：ERROR / OPENED / CLOSED / ANOTHER(设备繁忙) |
| currentInventoryHash | String | 当前库存哈希（用于同步判断） |
| createTime / updateTime | LocalDateTime | 时间戳 |

**非DB字段**（`@TableField(exist = false)`）：shopName, address, deviceTypeLabel, statusLabel, statusColor, isOnline, temperature, volume, doorCount, layerCount, hasScreen, totalSales, todaySales, orderCount, lastOnlineTime

### 1.2 门状态枚举 (`DeviceDoorStatus`)

| code | 枚举值 | 说明 |
|------|--------|------|
| ERROR | 开门失败 | 远程开门请求失败 |
| OPENED | 门已开 | 门处于打开状态 |
| CLOSED | 门已关 | 门处于关闭状态 |
| ANOTHER | 设备繁忙 | 设备正忙，无法开门 |

#### 为什么门状态用字符串而非数字编码？

门状态直接来自哈哈平台设备端的回调，设备端使用字符串状态码（如 "1"=ERROR, "2"=OPENED, "3"=CLOSED, "4"=ANOTHER）。为避免数字编码与数据库值之间的映射混乱，`DeviceDoorStatus` 枚举在数据库中存储英文状态字符串（ERROR/OPENED/CLOSED/ANOTHER），并在 `convertToDbValue()` 方法中处理原始数字码到字符串的转换。这种设计使得数据库中的值自解释，排查问题时一目了然。

### 1.3 设备服务核心方法 (`DeviceService`)

| 方法 | 说明 |
|------|------|
| getPage() | 分页查询设备列表（支持门店/状态筛选） |
| getDetailById() | 设备详情（含门店名、状态标签填充） |
| getStatistics() | 设备统计数据 |
| openDoor() | 远程开门 |
| scanCodeOpenDoor() | 扫码开门业务（含支付分校验） |
| setTemperature() | 设置温度 |
| setVolume() | 设置音量 |
| getNearbyDevices() | 附近设备查询（经纬度+距离） |
| getDeviceBySn() | 通过SN号查询设备 |
| updateDeviceStatus() | 更新设备状态 |
| updateInventoryHash() | 更新库存哈希 |

---

## 二、设备回调处理 (`HahaCallbackService`)

#### 什么是设备回调？

哈哈平台（智能售卖机设备平台）采用回调机制主动推送设备事件。我们的服务端作为回调接收方，在 `CallbackController` 中接收并分发处理。回调类型包括设备状态变更、AI识别结果、订单信息等。

**为什么用回调而非轮询？**
- 实时性：设备事件立即推送，无需等待轮询周期
- 高效：只有事件发生时才产生网络请求，节省资源
- 可靠：回调失败可重试，配合签名验证保证安全

### 2.1 回调消息类型

| 类型 | 方法 | 说明 |
|------|------|------|
| DEVICE_STATUS | handleDeviceStatus() | 开关门状态通知 |
| ONLINE_STATUS | handleOnlineStatus() | 设备在线/离线通知 |
| VOICE_RESULT | handleVoiceResult() | 音量调节结果 |
| CLIENT_NEW_PRODUCT | handleNewProductAudit() | 新品审核结果 |
| MERGE_PRODUCT | handleMergeProduct() | 商品合并结果 |
| ORC_RESULT | handleOrcResult() | AI识别结果通知 |
| 订单回调 | handleOrderCallback() | 设备端订单信息回调 |

### 2.2 核心回调流程

#### ORC_RESULT（AI识别回调）

```
设备AI识别完成
    ↓
解析 sku_list: [{code, quantity}]
    ↓
创建/查找订单 createOrderFromRecognition()
    - 幂等：通过 activityId 防重复
    - 订单金额初始化为0（等待设备端回调）
    ↓
解析视频URL等资源信息
    ↓
创建 DoorRecord（doorStatus=CLOSED）
```

#### 订单回调

```
设备端计算好订单金额和商品明细后回调
    ↓
查找或创建本地订单
    ↓
updateOrderFromCallback()
    - 写入 orderNo, totalAmount, items
    - 初始化 discountAmount=0, paidAmount=totalAmount
    ↓
saveOrderGoods() — 保存订单商品明细
    ↓
processCouponDiscount() — 自动优惠券扣减
    ↓
processPayScorePayment() — 支付分扣费
```

---

## 三、开关门记录 (DoorRecord)

### 3.1 实体字段

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 雪花算法主键 |
| activityId | String | 哈哈平台活动ID |
| deviceId | String | 设备ID |
| userId | Long | 用户ID |
| doorIndex | String | 门索引（A/B/C/D） |
| openType | String | 开门类型：IN-上货，OUT-消费 |
| doorStatus | String | 门状态：OPENED-已开，CLOSED-已关 |
| nobuy | Integer | 是否无消费：0-有消费，1-无消费 |
| orderId | Long | 关联订单ID（有消费时） |
| openTime | LocalDateTime | 开门时间 |
| closeTime | LocalDateTime | 关门时间 |
| duration | Integer | 持续时长（秒） |
| source | String | 来源：MINIAPP / ADMIN |
| remark | String | 备注 |

### 3.2 开门类型 (`OpenType`)

| code | 说明 |
|------|------|
| IN | 上货开门（运营人员补货） |
| OUT | 消费开门（用户购物） |

---

## 四、门店管理

### 4.1 Shop 实体

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 雪花算法主键 |
| shopCode | String | 门店编码（唯一标识） |
| name | String | 门店名称 |
| address | String | 门店地址 |
| province / city / district | String | 省市区 |
| longitude / latitude | Double | 经纬度 |
| contactName / contactPhone | String | 联系人/电话 |
| businessHours | String | 营业时间 |
| status | Integer | 状态：0-禁用 1-启用 |
| remark | String | 备注 |

**非DB字段**：deviceCount（设备总数）, onlineCount（在线设备数）, statusLabel, statusColor

### 4.2 门店服务核心方法 (`ShopService`)

| 方法 | 说明 |
|------|------|
| getPage() | 分页查询门店 |
| getDetailById() | 门店详情（含设备数/在线数） |
| getStatistics() | 门店统计 |
| getNearbyShops() | 附近门店查询（小程序端） |

### 4.3 门店补货员 (ShopReplenisher)

关联门店和补货人员，用于补货权限管理。

---

## 五、库存管理

### 5.1 DeviceInventory 实体（设备商品库存）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 雪花算法主键 |
| deviceId | String | 设备ID（SN号） |
| productId | Long | 商品ID（本地） |
| productCode | String | 商品编码（哈哈平台code） |
| productName | String | 商品名称（冗余） |
| stock | Integer | 当前库存数量 |
| shelfNum | Integer | 货架层号 |
| position | String | 货道位置（left/right） |
| warningThreshold | Integer | 库存预警阈值 |
| lastRestockTime | LocalDateTime | 最后补货时间 |

### 5.2 库存服务 (`DeviceInventoryService`)

| 方法 | 说明 |
|------|------|
| getInventoryByDevice() | 查询设备库存列表 |
| syncInventory() | 同步设备库存（从设备端获取最新数据） |
| deductStock() | 扣减库存（订单完成后） |
| checkLowStock() | 低库存预警检查 |

### 5.3 库存同步流程

```
设备端上报库存变更
    ↓
HahaCallbackService 接收通知
    ↓
比对 currentInventoryHash
    ↓
如不一致 → 调用哈哈SDK获取最新库存
    ↓
更新 DeviceInventory 记录
    ↓
更新 currentInventoryHash
    ↓
检查低库存 → 触发告警
```

#### 库存哈希机制的设计考量

`currentInventoryHash` 是设备当前库存的哈希摘要。每次设备端回调库存变更时，先比对哈希值：
- 哈希一致 → 库存未变化，跳过同步，减少不必要的SDK调用
- 哈希不一致 → 库存有变化，拉取最新数据并更新

这种设计避免了频繁全量同步的性能开销，只在库存确实变化时才触发同步。

### 5.4 补货记录 (StockRecord / StockRecordItem)

| 实体 | 说明 |
|------|------|
| StockRecord | 补货记录主表（操作人、设备、时间） |
| StockRecordItem | 补货明细（商品、数量变化） |

---

## 六、设备告警体系

### 6.1 DeviceAlertRecord 实体

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 雪花算法主键 |
| deviceId | String | 设备ID |
| alertType | String | 告警类型 |
| alertLevel | Integer | 告警级别 |
| title | String | 告警标题 |
| content | String | 告警内容 |
| status | Integer | 处理状态 |

### 6.2 告警类型 (`DeviceAlertType`)

| code | 说明 |
|------|------|
| OFFLINE | 设备离线 |
| LOW_STOCK | 低库存 |
| DOOR_ERROR | 开门异常 |

### 6.3 告警通知

告警通过企业微信 Webhook 推送，配置在 `haha-service/.../notify/` 中。

---

## 七、商品管理

### 7.1 Product 实体

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 雪花算法主键 |
| productId | String | 哈哈平台商品ID |
| code | String | 商品编码（哈哈平台code） |
| barcode | String | 商品条码 |
| name | String | 商品名称 |
| type | String | 商品分类 |
| pic | String | 商品图片URL |
| retailPrice | Double | 零售价 |
| costPrice | Double | 成本价 |
| applyStatus | String | 适用设备：全部柜/静态柜/动态柜 |
| syncStatus | Integer | 同步状态：0-未同步 1-同步中 2-已同步 3-同步失败 |

### 7.2 商品同步

商品数据从哈哈平台（SDK）同步到本地，`DataSyncServiceImpl` 处理全量/增量同步。

---

## 八、核心代码文件索引

| 文件 | 职责 |
|------|------|
| `haha-entity/.../Device.java` | 设备实体 |
| `haha-entity/.../Shop.java` | 门店实体 |
| `haha-entity/.../Product.java` | 商品实体 |
| `haha-entity/.../DoorRecord.java` | 开关门记录 |
| `haha-entity/.../DeviceInventory.java` | 设备库存 |
| `haha-entity/.../StockRecord.java` | 补货记录 |
| `haha-entity/.../DeviceAlertRecord.java` | 设备告警记录 |
| `haha-service/.../DeviceServiceImpl.java` | 设备服务 |
| `haha-service/.../ShopServiceImpl.java` | 门店服务 |
| `haha-service/.../ProductServiceImpl.java` | 商品服务 |
| `haha-service/.../DoorRecordServiceImpl.java` | 开关门记录服务 |
| `haha-service/.../DeviceInventoryServiceImpl.java` | 库存服务 |
| `haha-service/.../DeviceAlertServiceImpl.java` | 告警服务 |
| `haha-service/.../HahaCallbackServiceImpl.java` | 设备回调处理 |
| `haha-service/.../DataSyncServiceImpl.java` | 数据同步服务 |
| `haha-admin/.../DeviceController.java` | 运营平台-设备API |
| `haha-admin/.../ShopController.java` | 运营平台-门店API |
| `haha-admin/.../InventoryController.java` | 运营平台-库存API |
| `haha-admin/.../DeviceAlertController.java` | 运营平台-告警API |
| `haha-miniapp/.../DeviceController.java` | 小程序-设备API |
| `haha-common/.../enums/DeviceDoorStatus.java` | 门状态枚举 |
| `haha-common/.../enums/DeviceAlertType.java` | 告警类型枚举 |
| `haha-common/.../enums/DeviceOnlineStatus.java` | 在线状态枚举 |
| `haha-common/.../constant/DeviceConstants.java` | 设备常量 |