feat: 初始化小米 IoT (MIoT) 智能家居 Go 库

- 实现 MIoT 客户端核心功能（MQTT 连接、设备管理、属性读写） - 支持云端 API 调用与局域网设备发现（mDNS） - 集成国际化（i18n）多语言支持 - 添加 MIoT 设备规约解析器（spec_parser） - 包含单元测试与使用示例
2026-06-28 22:05:49 +08:00
parent ac442812b4
commit 3a44cb9e6a
118 changed files with 31630 additions and 0 deletions
@@ -0,0 +1,184 @@
+# 第三轮任务提示词（修订版）
+
+> 总文档：`ROUND3_PLAN.md`
+> 9 项空实现 + 5 项部分实现
+
+## ❌ 块 C — 回调事件（5 项空实现）
+
+### C1 — onMipsCloudStateChanged disconnect 批量处理
+
+```
+目标：miot_client.go:624
+
+Python：disconnect 时遍历 _device_list_cloud，所有 online 标 false → 聚合 cache → 通知
+
+Go 当前：fmt.Printf + "// TODO: Update device states accordingly"
+
+需实现：
+1. 遍历 c.deviceListCloud，所有 online=true 的标 false
+2. 逐个 did 调 checkDeviceState 聚合 → 更新 deviceListCache["online"]
+3. 通知 subDeviceState 订阅者（offline）
+4. 调 ShowDevicesChangedNotify
+```
+
+### C2 — onMipsLocalStateChanged disconnect 批量处理
+
+```
+目标：miot_client.go:653
+
+Python：disconnect 时遍历 _device_list_gateway，筛选 group_id 匹配的设备标 offline → 聚合
+
+Go 当前：fmt.Printf + TODO
+
+需实现：同 C1，但是遍历 deviceListGateway 中 group_id 匹配的设备
+```
+
+### C3 — onMipsServiceStateChange 创建 MipsLocalClient
+
+```
+目标：miot_client.go:646
+
+Python：ADDED/UPDATED → 创建 MipsLocalClient → set on_dev_list_changed → connect
+
+Go 当前：fmt.Printf + TODO
+
+需实现：
+1. ADDED → NewMipsLocalClient(did, groupID, host, port, certs) → Connect
+2. 注册 on_dev_list_changed 回调
+3. Changed → disconnect 旧 + connect 新
+4. REMOVED → disconnect + 从 mipsLocal map 删除
+```
+
+### C4 — onGWDeviceListChanged 拉取网关设备列表
+
+```
+目标：miot_client.go:685
+
+Python：从网关 get_dev_list + 筛选 did → updateDevicesFromGW
+
+Go 当前：fmt.Printf + TODO
+
+需实现：调对应 MipsLocalClient.get_dev_list → updateDevicesFromGW(did_list)
+```
+
+### C5 — onLanDeviceStateChanged 新增方法
+
+```
+目标：miot_client.go 新增
+
+Python：__on_lan_device_state_changed(did, state, ctx)
+  1. 更新 deviceListLan[did]["online"] + ["push_available"]
+  2. 调 checkDeviceState 三源聚合
+  3. 更新 deviceListCache["online"]
+  4. 通知 subDeviceState
+
+Go：方法不存在，且 Init 中未接线
+
+需实现：
+1. 新增 onLanDeviceStateChanged 方法
+2. 在 LanStateChange 或 Init 中接线：
+   lan.SubDeviceState("miot_client", c.onLanDeviceStateChanged, nil)
+```
+
+## ❌ 块 D — MQTT 消息处理（2 项空实现 + 2 项部分）
+
+### D1 — handleMIPSMessage 解包+分发
+
+```
+目标：miot_client_sub.go:257
+
+Python：MIPS payload 是 _MipsMessage.unpack() 后 dispatch
+
+Go 当前：fmt.Printf + TODO
+
+需实现：MipsMessage.Unpack(payload) → 提取 topic → match subTree → 调 handler
+```
+
+### D2 — handleMIPSStateMessage 解析+缓存更新
+
+```
+目标：miot_client_sub.go:263
+
+Python：解析 state 消息中的 online 字段 → 调 OnDeviceStateChanged
+
+Go 当前：fmt.Printf + TODO
+
+需实现：解析 payload → 调用 OnDeviceStateChanged(did, state)
+```
+
+### D3 — OnDeviceStateChanged 增加三源聚合
+
+```
+目标：miot_client_device.go:340
+
+当前：只写 cloud cache + device cache，未调 checkDeviceState
+
+修改：更新完对应源 cache 后，调 checkDeviceState(did) 再写 deviceListCache
+```
+
+### D4 — updateDeviceMsgSub 补全
+
+```
+目标：miot_client_sub.go
+
+当前：只用 mipsCloud.IsConnected() 判断
+
+修改：
+1. 读 gateway push_available + LAN push_available
+2. 三源优先级：gateway(online+push) > LAN(online+push) > cloud(online)
+3. 源变化时 unsubFrom(old) → subFrom(new)
+```
+
+## ❌ 块 E — Token/证书刷新（2 项空实现）
+
+### E1 — RequestRefreshAuthInfo 回调体
+
+```
+目标：miot_client.go:548
+
+Go 当前：AfterFunc 回调只有 fmt.Printf + TODO
+
+需实现：参考 Python refresh_oauth_info_async：
+1. storage.LoadUserConfig → 读 auth_info
+2. 判断 expires_ts - now <= 60 → 需要刷新
+3. oauth.RefreshAccessToken(refresh_token)
+4. http.UpdateHTTPHeader(access_token=new)
+5. mipsCloud.UpdateAccessToken(new)
+6. storage.UpdateUserConfig(auth_info=new)
+7. 重新调度下次刷新
+```
+
+### E2 — RequestRefreshUserCert 回调体
+
+```
+目标：miot_client.go:564
+
+Go 当前：AfterFunc 回调只有 fmt.Printf + TODO
+
+需实现：参考 Python refresh_user_cert_async：
+1. cert.VerifyCACert()
+2. cert.UserCertRemainingTime() - MIHOME_CERT_EXPIRE_MARGIN <= 60 → 需要刷新
+3. cert.LoadUserKey()
+4. cert.GenUserCSR()
+5. http.GetCentralCert(csr)
+6. cert.SaveUserCert(cert)
+7. 重新调度下次刷新
+```
+
+## ⚠️ 块 F — 验证项
+
+### F2 — loadCacheDevice 存储 key
+
+```
+目标：miot_client.go:217
+
+Python：storage.load_async(domain='miot_devices', name=f'{uid}_{cloud_server}', type_=dict)
+
+Go：storage.Load("miot_devices", deviceKey, "dict")
+
+确认 Go 的 storage.Save/Load 与 Python 的 domain/name/type 参数对齐。
+```
+
+## ⚠️ 块 B — Deinit 验证项
+
+需 Read 函数体验证 Deinit 完整性与 Python 对齐，确认 B1-B12 全部到位。