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,222 @@
+# 08 - const.py 移植计划
+
+## 概览
+
+| 项目 | 内容 |
+|------|------|
+| **Python 文件** | `py-miot/const.py` (161行) |
+| **Go 文件** | ❌ 缺失 |
+| **状态** | ❌ 完全缺失 |
+| **优先级** | 🔴 P0 |
+| **预计工作量** | 2-3 小时 |
+
+**说明**：此文件对应之前分析的 `miot_constant.py`，实际文件名为 `const.py`。
+
+## Python 版本分析
+
+### 核心常量
+
+#### 基础常量
+
+| 常量名 | 行号 | 值 | 说明 |
+|--------|------|-----|------|
+| `DOMAIN` | 48 | `'xiaomi_home'` | 域名 |
+| `DEFAULT_NAME` | 49 | `'Xiaomi Home'` | 默认名称 |
+| `DEFAULT_NICK_NAME` | 51 | `'Xiaomi'` | 默认昵称 |
+
+#### 超时和间隔
+
+| 常量名 | 行号 | 值 | 说明 |
+|--------|------|-----|------|
+| `MIHOME_HTTP_API_TIMEOUT` | 53 | `30` | HTTP API 超时（秒） |
+| `MIHOME_MQTT_KEEPALIVE` | 54 | `60` | MQTT 保持连接（秒） |
+| `MIHOME_CERT_EXPIRE_MARGIN` | 56 | `3600*24*3` | 证书过期边际（3天） |
+| `NETWORK_REFRESH_INTERVAL` | 58 | `30` | 网络刷新间隔（秒） |
+
+#### OAuth 相关
+
+| 常量名 | 行号 | 值 | 说明 |
+|--------|------|-----|------|
+| `OAUTH2_CLIENT_ID` | 60 | `'2882303761520251711'` | OAuth2 客户端 ID |
+| `OAUTH2_AUTH_URL` | 61 | `'https://account.xiaomi.com/oauth2/authorize'` | OAuth2 授权 URL |
+| `DEFAULT_OAUTH2_API_HOST` | 62 | `'ha.api.io.mi.com'` | 默认 OAuth2 API 主机 |
+| `DEFAULT_CLOUD_BROKER_HOST` | 63 | `'ha.mqtt.io.mi.com'` | 默认云 Broker 主机 |
+| `OAUTH_REDIRECT_URL` | 135 | `'http://homeassistant.local:8123'` | OAuth 重定向 URL |
+
+#### 缓存时间
+
+| 常量名 | 行号 | 值 | 说明 |
+|--------|------|-----|------|
+| `SPEC_STD_LIB_EFFECTIVE_TIME` | 66 | `3600*24*14` | SPEC 标准库有效期（14天） |
+| `MANUFACTURER_EFFECTIVE_TIME` | 68 | `3600*24*14` | 制造商信息有效期（14天） |
+
+#### 支持的平台
+
+| 常量名 | 行号 | 值 | 说明 |
+|--------|------|-----|------|
+| `SUPPORTED_PLATFORMS` | 70-89 | 列表 | 支持的 Home Assistant 平台 |
+| `UNSUPPORTED_MODELS` | 91-96 | 列表 | 不支持的设备模型 |
+
+#### 云服务器
+
+| 常量名 | 行号 | 值 | 说明 |
+|--------|------|-----|------|
+| `DEFAULT_CLOUD_SERVER` | 98 | `'cn'` | 默认云服务器 |
+| `CLOUD_SERVERS` | 99-106 | 字典 | 云服务器列表 |
+
+#### 语言
+
+| 常量名 | 行号 | 值 | 说明 |
+|--------|------|-----|------|
+| `DEFAULT_INTEGRATION_LANGUAGE` | 110 | `'en'` | 默认集成语言 |
+| `INTEGRATION_LANGUAGES` | 111-125 | 字典 | 集成语言列表 |
+
+#### 其他
+
+| 常量名 | 行号 | 值 | 说明 |
+|--------|------|-----|------|
+| `DEFAULT_COVER_DEAD_ZONE_WIDTH` | 127 | `0` | 默认 cover 死区宽度 |
+| `MIN_COVER_DEAD_ZONE_WIDTH` | 128 | `0` | 最小 cover 死区宽度 |
+| `MAX_COVER_DEAD_ZONE_WIDTH` | 129 | `5` | 最大 cover 死区宽度 |
+| `DEFAULT_CTRL_MODE` | 131 | `'auto'` | 默认控制模式 |
+
+#### CA 证书
+
+| 常量名 | 行号 | 值 | 说明 |
+|--------|------|-----|------|
+| `MIHOME_CA_CERT_STR` | 137-157 | 字符串 | MIoT CA 证书（PEM 格式） |
+| `MIHOME_CA_CERT_SHA256` | 159-160 | 字符串 | MIoT CA 证书 SHA256 哈希 |
+
+## Go 版本现状
+
+### 缺失的功能
+
+整个 `const.py` 模块在 Go 版本中完全缺失。
+
+Go 版本中可能需要实现：
+1. **常量定义** - 对应 Python 的常量
+2. **变量定义** - 对应 Python 的变量（如列表、字典）
+
+## 移植建议
+
+### 第一批任务（核心功能）
+
+1. **创建 `const.go` 文件** (1小时)
+   - 定义基础常量
+   - 定义超时和间隔常量
+
+2. **实现 OAuth 相关常量** (1小时)
+   - 定义 OAuth2 客户端 ID
+   - 定义 OAuth2 URL
+   - 定义重定向 URL
+
+3. **实现云服务器和语言常量** (1小时)
+   - 定义云服务器列表
+   - 定义语言列表
+
+4. **实现 CA 证书常量** (1小时)
+   - 定义 CA 证书字符串
+   - 定义 CA 证书哈希
+
+### 第二批任务（辅助功能）
+
+5. **实现支持的平台和模型** (1小时)
+   - 定义支持的平台列表
+   - 定义不支持的模型列表
+
+6. **单元测试** (1小时)
+   - 测试常量值
+   - 测试变量初始化
+
+## 技术难点
+
+### 1. 常量 vs 变量
+
+**问题**：Python 的"常量"实际上是变量，Go 有真正的常量
+
+**建议**：
+```go
+// 真正的常量
+const (
+    DOMAIN = "xiaomi_home"
+    DEFAULT_NAME = "Xiaomi Home"
+    MIHOME_HTTP_API_TIMEOUT = 30
+)
+
+// 变量（需要在 init() 中初始化）
+var (
+    SUPPORTED_PLATFORMS = []string{
+        "binary_sensor",
+        "button",
+        // ...
+    }
+    CLOUD_SERVERS = map[string]string{
+        "cn": "中国大陆",
+        "de": "Europe",
+        // ...
+    }
+)
+```
+
+### 2. CA 证书字符串
+
+**问题**：Python 使用多行字符串，Go 需要使用反引号
+
+**建议**：
+```go
+const MIHOME_CA_CERT_STR = `-----BEGIN CERTIFICATE-----
+MIIBazCCAQ+gAwIBAgIEA/UKYDAMBggqhkjOPQQDAgUAMCIxEzARBgNVBAoTCk1p
+...
+-----END CERTIFICATE-----
+-----BEGIN CERTIFICATE-----
+...
+-----END CERTIFICATE-----`
+```
+
+## 测试计划
+
+### 单元测试
+
+1. **常量值测试**
+   - 测试基础常量
+   - 测试 OAuth 常量
+
+2. **变量初始化测试**
+   - 测试列表变量
+   - 测试字典变量
+
+## 依赖关系
+
+| 依赖文件 | 关系 | 说明 |
+|---------|------|------|
+| 无 | - | 独立模块 |
+
+## 移植优先级
+
+| 任务 | 优先级 | 理由 |
+|------|--------|------|
+| 创建基础结构 | 🔴 高 | 基础框架 |
+| 实现基础常量 | 🔴 高 | 核心功能 |
+| 实现 OAuth 常量 | 🔴 高 | 核心功能 |
+| 实现云服务器常量 | 🔴 高 | 核心功能 |
+| 实现 CA 证书 | 🔴 高 | 核心功能 |
+| 实现平台和模型 | 🟡 中 | 辅助功能 |
+| 单元测试 | 🟡 中 | 质量保障 |
+
+## 进度跟踪
+
+- [ ] 创建 `const.go` 文件 (预计 1小时)
+- [ ] 实现基础常量 (预计 1小时)
+- [ ] 实现 OAuth 相关常量 (预计 1小时)
+- [ ] 实现云服务器和语言常量 (预计 1小时)
+- [ ] 实现 CA 证书常量 (预计 1小时)
+- [ ] 实现支持的平台和模型 (预计 1小时)
+- [ ] 单元测试 (预计 1小时)
+
+**总计**：7小时
+
+---
+
+**创建时间**：2026-06-28
+**最后更新**：2026-06-28
+**负责人**：待定