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,258 @@
+# 05 - miot_storage.py 移植计划
+
+## 概览
+
+| 项目 | 内容 |
+|------|------|
+| **Python 文件** | `py-miot/miot_storage.py` (789行) |
+| **Go 文件** | ❌ 缺失 |
+| **状态** | ❌ 完全缺失 |
+| **优先级** | 🔴 P0 |
+| **预计工作量** | 12-16 小时 |
+
+## Python 版本分析
+
+### 核心类
+
+#### MIoTStorage
+
+**位置**：第 90-538 行
+
+**主要职责**：
+- 文件管理（同步和异步）
+- 支持多种数据类型（bytes、str、dict、list）
+- 文件完整性检查（SHA256 哈希）
+- 异步操作支持（使用 `asyncio`）
+
+**核心方法**：
+
+| 方法名 | 行号 | 功能 | 说明 |
+|--------|------|------|------|
+| `__init__` | 100 | 初始化存储 | 设置根路径和事件循环 |
+| `load` | 168 | 加载文件（同步） | 支持多种数据类型 |
+| `load_async` | 175 | 加载文件（异步） | 使用 `run_in_executor` |
+| `save` | 232 | 保存文件（同步） | 支持多种数据类型 |
+| `save_async` | 239 | 保存文件（异步） | 使用 `run_in_executor` |
+| `remove` | 260 | 删除文件（同步） | |
+| `remove_async` | 265 | 删除文件（异步） | |
+| `remove_domain` | 288 | 删除域目录（同步） | 递归删除 |
+| `remove_domain_async` | 292 | 删除域目录（异步） | |
+| `get_names` | 312 | 获取文件名列表 | 按类型过滤 |
+| `file_exists` | 322 | 检查文件是否存在 | |
+| `save_file` | 326 | 保存二进制文件（同步） | 不添加哈希 |
+| `load_file` | 352 | 加载二进制文件（同步） | |
+| `clear` | 397 | 清空存储（同步） | |
+| `clear_async` | 406 | 清空存储（异步） | |
+| `update_user_config` | 421 | 更新用户配置 | 支持部分更新 |
+| `load_user_config` | 481 | 加载用户配置 | 支持键过滤 |
+
+**关键特性**：
+- 文件完整性检查（SHA256 哈希）
+- 异步操作支持
+- 操作去重（避免重复执行相同操作）
+- 用户配置管理
+
+#### MIoTCert
+
+**位置**：第 540-727 行
+
+**主要职责**：
+- 证书管理（CA 证书、用户证书、私钥）
+- 证书验证
+- 证书生成（CSR）
+
+**核心方法**：
+
+| 方法名 | 行号 | 功能 |
+|--------|------|------|
+| `verify_ca_cert_async` | 583 | 验证 CA 证书 |
+| `user_cert_remaining_time_async` | 605 | 获取用户证书剩余有效期 |
+| `gen_user_key` | 655 | 生成用户私钥（Ed25519） |
+| `gen_user_csr` | 664 | 生成 CSR |
+| `load_user_key_async` | 682 | 加载用户私钥 |
+| `update_user_key_async` | 688 | 更新用户私钥 |
+| `load_user_cert_async` | 695 | 加载用户证书 |
+| `update_user_cert_async` | 701 | 更新用户证书 |
+
+#### DeviceManufacturer
+
+**位置**：第 729-789 行
+
+**主要职责**：
+- 设备制造商信息缓存
+- 从云端获取制造商信息
+- 本地缓存管理
+
+**核心方法**：
+
+| 方法名 | 行号 | 功能 |
+|--------|------|------|
+| `init_async` | 744 | 初始化（加载缓存或从云端获取） |
+| `deinit_async` | 782 | 清理 |
+| `get_name` | 785 | 根据缩写获取完整名称 |
+
+## Go 版本现状
+
+### 缺失的功能
+
+整个 `miot_storage.py` 模块在 Go 版本中完全缺失。
+
+Go 版本中可能需要实现：
+1. **文件存储管理** - 对应 `MIoTStorage`
+2. **证书管理** - 对应 `MIoTCert`
+3. **制造商信息缓存** - 对应 `DeviceManufacturer`
+
+## 移植建议
+
+### 第一批任务（核心功能）
+
+1. **创建 `miot_storage.go` 文件** (2小时)
+   - 定义 `MIoTStorage` 结构体
+   - 实现构造函数
+
+2. **实现文件读写** (4小时)
+   - 实现 `Load` 和 `Save` 方法
+   - 支持多种数据类型（[]byte、string、map、slice）
+   - 实现哈希检查
+
+3. **实现异步操作** (3小时)
+   - 使用 goroutine 实现异步
+   - 实现操作去重（避免重复执行）
+   - 实现优雅关闭
+
+4. **实现用户配置管理** (2小时)
+   - 实现 `UpdateUserConfig` 方法
+   - 实现 `LoadUserConfig` 方法
+
+### 第二批任务（证书管理）
+
+5. **创建 `miot_cert.go` 文件** (1小时)
+   - 定义 `MIoTCert` 结构体
+
+6. **实现证书管理** (4小时)
+   - 实现 CA 证书验证
+   - 实现用户证书管理
+   - 实现证书生成（如果需要）
+
+### 第三批任务（制造商信息）
+
+7. **创建 `miot_manufacturer.go` 文件** (1小时)
+   - 定义 `DeviceManufacturer` 结构体
+
+8. **实现制造商信息缓存** (2小时)
+   - 实现初始化
+   - 实现缓存更新
+
+## 技术难点
+
+### 1. 异步操作
+
+**问题**：Python 使用 `asyncio`，Go 使用 goroutine
+
+**建议**：
+```go
+type MIoTStorage struct {
+    rootPath string
+    mu       sync.RWMutex
+    // 操作去重
+    pendingOps map[string]*PendingOp
+}
+
+type PendingOp struct {
+    done chan struct{}
+    result interface{}
+    err   error
+}
+```
+
+### 2. 文件完整性检查
+
+**问题**：需要在文件中嵌入 SHA256 哈希
+
+**建议**：
+```go
+func (s *MIoTStorage) Save(domain, name string, data interface{}) error {
+    var bytes []byte
+    switch v := data.(type) {
+    case []byte:
+        bytes = v
+    case string:
+        bytes = []byte(v)
+    case map[string]interface{}, []interface{}:
+        bytes, _ = json.Marshal(v)
+    }
+    
+    // 添加哈希
+    hash := sha256.Sum256(bytes)
+    bytesWithHash := append(bytes, hash[:]...)
+    
+    // 写入文件
+    return ioutil.WriteFile(s.getFullPath(domain, name, data), bytesWithHash, 0644)
+}
+```
+
+### 3. 证书管理
+
+**问题**：需要使用加密库
+
+**建议**：
+- 使用 Go 标准库 `crypto`
+- 使用第三方库 `golang.org/x/crypto/ed25519`
+
+## 测试计划
+
+### 单元测试
+
+1. **文件读写测试**
+   - 测试各种数据类型的读写
+   - 测试哈希检查
+   - 测试错误处理
+
+2. **异步操作测试**
+   - 测试并发读写
+   - 测试操作去重
+   - 测试优雅关闭
+
+3. **证书管理测试**
+   - 测试证书验证
+   - 测试证书生成
+   - 测试证书加载
+
+## 依赖关系
+
+| 依赖文件 | 关系 | 说明 |
+|---------|------|------|
+| `miot_error.py` | 强依赖 | 错误定义 |
+| `const.py` | 强依赖 | 常量定义 |
+| `crypto` 库 | 强依赖 | 证书管理 |
+
+## 移植优先级
+
+| 任务 | 优先级 | 理由 |
+|------|--------|------|
+| 创建基础结构 | 🔴 高 | 基础框架 |
+| 实现文件读写 | 🔴 高 | 核心功能 |
+| 实现异步操作 | 🔴 高 | 核心功能 |
+| 实现用户配置 | 🔴 高 | 核心功能 |
+| 实现证书管理 | 🟡 中 | 重要功能 |
+| 实现制造商信息 | 🟢 低 | 辅助功能 |
+
+## 进度跟踪
+
+- [ ] 创建 `miot_storage.go` 文件 (预计 2小时)
+- [ ] 实现文件读写 (预计 4小时)
+- [ ] 实现异步操作 (预计 3小时)
+- [ ] 实现用户配置管理 (预计 2小时)
+- [ ] 创建 `miot_cert.go` 文件 (预计 1小时)
+- [ ] 实现证书管理 (预计 4小时)
+- [ ] 创建 `miot_manufacturer.go` 文件 (预计 1小时)
+- [ ] 实现制造商信息缓存 (预计 2小时)
+- [ ] 单元测试 (预计 4小时)
+
+**总计**：23小时
+
+---
+
+**创建时间**：2026-06-28
+**最后更新**：2026-06-28
+**负责人**：待定