文档最后同步：2026-07-18（codex+codex 自动审计同步，表示同步检查新鲜度，非本页内容改动时间）
CulinaTech 智能温度计生态的 Flutter 客户端文档。本 wiki 给 AI 编码 agent 和新加入的开发者用，避免在 30k 行代码里走偏。
跨平台 Flutter App（iOS + Android），通过 BLE 与「中继盒」（booster）通讯，中继盒再无线读取探针温度。主打场景：烹饪过程实时监测温度、达到目标温度报警、多设备并行监控。CM4 机型走 MQTT/TLS 云端 + BLE 双通道，传统机型仅 BLE。当前实现里，这个“双通道”有明确主备语义：CM4 可以进入 cloud-primary 模式，但 App 仍保留 BLE 侧连接/锁；当设备经 BLE 上报 MQTT_STS=0 或 WIFI_STS=0、即设备自己的云端上行不可用时，设置类命令会回退到 BLE 发送，而不是继续盲发到云端。
当前代码还把一组 CM4 专属设备状态直接建模到了 Booster：ringCount（蜂鸣器响铃模式/时长）、wifiMac、wifiRssiDbm、mqttConnected。此外，当前 Booster 还明确区分了两个固件版本来源：firmwareVersion 是随遥测包上报的杰理 BLE 芯片版本，主要用于连接后“已收到真实数据”的判定与诊断；espFirmwareVersion 则来自 VER 回复中的 ESP WiFi 芯片版本，固件升级页与 OTA 版本比较应以它为准。这表示 App 不只关心温度与 BLE 连接，还会跟踪 CM4 的 WiFi 接入质量、broker 连通性，以及设备侧蜂鸣器配置。另一个当前代码里的真实约束是：wifiRssiDbm 虽然已经建模到 Booster，但注释明确标成 pending firmware。也就是说，现阶段固件通常只会通过 WIFI_STS=N 上报 0–4 格 WiFi 档位；精确 dBm 值只有在后续支持该字段的固件上才会出现，当前应把它视为“可空增强信息”，不能当成所有 CM4 都稳定可得的实时遥测。
另一个当前代码里的真实约束是：探针列表的 UI 排序不是所有机型都一样。Booster.probesInDisplayOrder 明确规定，CM4 按中继盒 LCD 自上而下的颜色顺序 blue / white / black / yellow 排列；legacy 机型才保持自然槽位顺序 black / white / blue / yellow。仪表盘卡片、版本/告警信息弹窗、设置页固件列表等探针列表界面都共用这一排序来源。
另一个当前代码已落地、但本页未写出的细节是：CM4 的 ringCount 不只覆盖 0–3，设备回读还包含 4 = Mute；App 通过 RI_CNT=? 读取该值，并以设备保存的蜂鸣器模式作为准。同一段连接初始化流程里，App 还会发送 TEMP=? 主动读取 CM4 LCD 当前显示模式，设备回包为 TEMP_INT / TEMP_EXT / TEMP_ALL；代码明确把这个显示模式视为设备真实来源，因为该模式也可能被中继盒物理按键改动。
| 中继盒 | 探针数 | 心跳/锁机制 | 通道 |
|---|---|---|---|
| CM4 | 4（LCD 显示序 blue/white/black/yellow——与 wire/slot 序 black/white/blue/yellow 不同，ProbeNumber.cm4LcdOrder 特意为此排序，避免 App 与中继盒屏幕显示顺序对不上） |
每 45s 发 ASCII CNT_0（独占锁刷新，60s TTL，per Liang 2026-06-06：与 legacy 同机制、wire 不同；c613148 之前是 20s 无独占锁） |
BLE + MQTT/WiFi |
| CM3 | 3 | 每 45s 发 0x55B1（60s TTL 独占锁） |
BLE only |
| CM2 / MW5 | 2 | 同上 | BLE only |
| CM1 / MW4 | 1 | 同上 | BLE only |
| MW3 | 2（已停产） | 物理 2 探针的 2nd-gen 中继盒（竹盒、无屏）；同 CM1 协议族但 App getProbeCount 未特判（fallback 4）—— 见 booster.dart 的 dcf2699 EOL 注释（Kevin 2026-05-29 确认 EOL，无开放 TAPD） |
BLE only |
| CulinaGrillix (CG_) | — | 新产品族，deviceTypeLabel 已识别 |
BLE |
探针颜色 ↔ 地址字节：
0x0A/0x0B=black、0x0D=white、0x0E=blue、0x0F=yellow。0x0F固件常量名PEN_RED仅为历史遗留——红色硬件从未量产（Beta 2026-05-13 二次确认）。
lib/core/transport/）| 分区 | 内容 |
|---|---|
| 01-项目概览 | 技术栈、目录结构、五条主线用户流程、跨业务共享层注释 |
| 02-通讯与协议 | BLE 生命周期、重连/宽限期、状态模型、BLE 协议、MQTT、v4.2 规范原文、CM4 协议、Supabase 账号与设备同步、FCM 后台推送 |
| 03-客户端实现 | iOS/Android 平台差异、告警、开发调试、24 个屏的逐屏文档（含账号/登录全家族）、iOS 实时活动 |
| 04-规划与跟进 | 待解决问题清单、长期重构追踪页 |
详见 概览 §核心不变式。摘要：
0x55B1（Liang 2026-04-20 锁定不变）、CM4 每 45s 发 ASCII CNT_0——同一机制、60s TTL，仅 wire 字节不同（CM4 不接受 0x55B1）。c613148 之前 CM4 cadence 是 20s 且文档为"无独占锁"，那是错的ble_device_service.dart:388 gracePeriod）0x55AA 后 1s 内的 0x07 断开 = 入仓关机（_dockShutoffWindow=1s），跳过宽限期，10s boosterShuttingDown 过渡 → boosterOffdeviceId.hashCode 相位错峰（ble_service.dart:1354）lib/core/protocol/temperature_lookup.dart），不信中继盒预转换值AlarmThresholds.internalOverTempF=212 / internalHiClampC=101）probeDisconnected 报警。中继盒 60s 全沉默 → lostConnectionambientOverTemp/internalOverTemp) → 状态 (probeDisconnected/boosterDisconnected/boosterPoweredOff) → 烹饪 (targetReached/earlyWarning1/earlyWarning2) → 信息 (lowBattery/boosterLowBattery/probeDocked/internalUnderTemp/ambientUnderTemp)，详见 告警与通知