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,216 @@
+# 07 - miot_error.py 移植计划
+
+## 概览
+
+| 项目 | 内容 |
+|------|------|
+| **Python 文件** | `py-miot/miot_error.py` (151行) |
+| **Go 文件** | `go-miot/miot_error.go` |
+| **状态** | ✅ 已完成 (仅缺测试) |
+| **优先级** | 🔴 P0 |
+| **预计工作量** | 2-3 小时 |
+
+## Python 版本分析
+
+### 核心类
+
+#### MIoTErrorCode
+
+**位置**：第 52-80 行
+
+**功能**：错误码枚举
+
+**错误码列表**：
+
+| 错误码 | 名称 | 值 | 说明 |
+|--------|------|-----|------|
+| `CODE_UNKNOWN` | -10000 | 未知错误 |
+| `CODE_UNAVAILABLE` | -10001 | 不可用 |
+| `CODE_INVALID_PARAMS` | -10002 | 无效参数 |
+| `CODE_RESOURCE_ERROR` | -10003 | 资源错误 |
+| `CODE_INTERNAL_ERROR` | -10004 | 内部错误 |
+| `CODE_UNAUTHORIZED_ACCESS` | -10005 | 未授权访问 |
+| `CODE_TIMEOUT` | -10006 | 超时 |
+| `CODE_OAUTH_UNAUTHORIZED` | -10020 | OAuth 未授权 |
+| `CODE_HTTP_INVALID_ACCESS_TOKEN` | -10030 | HTTP 无效 access token |
+| `CODE_MIPS_INVALID_RESULT` | -10040 | MIPS 无效结果 |
+| `CODE_CERT_INVALID_CERT` | -10050 | 证书无效 |
+| `CODE_CONFIG_INVALID_INPUT` | -10100 | 配置无效输入 |
+| `CODE_CONFIG_INVALID_STATE` | -10101 | 配置无效状态 |
+| `CODE_LAN_UNAVAILABLE` | -10120 | LAN 不可用 |
+
+#### MIoTError
+
+**位置**：第 82-98 行
+
+**功能**：基础错误类
+
+**核心方法**：
+
+| 方法名 | 行号 | 功能 |
+|--------|------|------|
+| `__init__` | 87 | 初始化错误 |
+| `to_str` | 94 | 转换为 JSON 字符串 |
+| `to_dict` | 97 | 转换为字典 |
+
+#### 子类错误
+
+| 类名 | 行号 | 说明 |
+|------|------|------|
+| `MIoTOauthError` | 101 | OAuth 错误 |
+| `MIoTHttpError` | 105 | HTTP 错误 |
+| `MIoTMipsError` | 109 | MIPS 错误 |
+| `MIoTDeviceError` | 113 | 设备错误 |
+| `MIoTSpecError` | 117 | SPEC 错误 |
+| `MIoTStorageError` | 121 | 存储错误 |
+| `MIoTCertError` | 125 | 证书错误 |
+| `MIoTClientError` | 129 | 客户端错误 |
+| `MIoTEvError` | 133 | 事件错误 |
+| `MipsServiceError` | 137 | MIPS 服务错误 |
+| `MIoTConfigError` | 141 | 配置错误 |
+| `MIoTOptionsError` | 145 | 选项错误 |
+| `MIoTLanError` | 149 | LAN 错误 |
+
+## Go 版本现状
+
+### 缺失的功能
+
+整个 `miot_error.py` 模块在 Go 版本中完全缺失。
+
+Go 版本中可能需要实现：
+1. **错误码定义** - 对应 `MIoTErrorCode`
+2. **基础错误类** - 对应 `MIoTError`
+3. **子类错误** - 对应各种专用错误类
+
+## 移植建议
+
+### 第一批任务（核心功能）
+
+1. **创建 `miot_error.go` 文件** (1小时)
+   - 定义错误码常量
+   - 定义 `MIoTError` 结构体
+   - 实现 `Error()` 方法
+
+2. **实现错误码** (1小时)
+   - 定义所有错误码常量
+   - 使用 `iota` 简化定义
+
+3. **实现子类错误** (1小时)
+   - 定义各种专用错误类型
+   - 实现构造函数
+
+### 第二批任务（辅助功能）
+
+4. **实现错误转换** (1小时)
+   - 实现 `ToStr()` 方法
+   - 实现 `ToDict()` 方法
+
+5. **单元测试** (1小时)
+   - 测试错误创建
+   - 测试错误转换
+
+## 技术难点
+
+### 1. 错误类型设计
+
+**问题**：Go 的错误类型设计与 Python 不同
+
+**建议**：
+```go
+type MIoTErrorCode int
+
+const (
+    CodeUnknown MIoTErrorCode = -10000
+    CodeUnavailable MIoTErrorCode = -10001
+    // ...
+)
+
+type MIoTError struct {
+    Code    MIoTErrorCode
+    Message string
+}
+
+func (e *MIoTError) Error() string {
+    return fmt.Sprintf("code=%d, message=%s", e.Code, e.Message)
+}
+
+func (e *MIoTError) ToDict() map[string]interface{} {
+    return map[string]interface{}{
+        "code":    e.Code,
+        "message": e.Message,
+    }
+}
+```
+
+### 2. 子类错误
+
+**问题**：Go 没有继承，需要使用组合或类型别名
+
+**建议**：
+```go
+type MIoTOauthError struct {
+    MIoTError
+}
+
+type MIoTHttpError struct {
+    MIoTError
+}
+
+// 或者使用函数构造函数
+func NewMIoTOauthError(message string) *MIoTOauthError {
+    return &MIoTOauthError{
+        MIoTError: MIoTError{
+            Code:    CodeOauthUnauthorized,
+            Message: message,
+        },
+    }
+}
+```
+
+## 测试计划
+
+### 单元测试
+
+1. **错误创建测试**
+   - 测试基础错误
+   - 测试子类错误
+
+2. **错误转换测试**
+   - 测试 `Error()` 方法
+   - 测试 `ToDict()` 方法
+
+3. **错误处理测试**
+   - 测试错误类型判断
+   - 测试错误链
+
+## 依赖关系
+
+| 依赖文件 | 关系 | 说明 |
+|---------|------|------|
+| 无 | - | 独立模块 |
+
+## 移植优先级
+
+| 任务 | 优先级 | 理由 |
+|------|--------|------|
+| 创建基础结构 | 🔴 高 | 基础框架 |
+| 实现错误码 | 🔴 高 | 核心功能 |
+| 实现子类错误 | 🔴 高 | 核心功能 |
+| 实现错误转换 | 🟡 中 | 辅助功能 |
+| 单元测试 | 🟡 中 | 质量保障 |
+
+## 进度跟踪
+
+- [x] 创建 `miot_error.go` 文件 (2026-06-28)
+- [x] 实现错误码 (2026-06-28)
+- [x] 实现子类错误 (2026-06-28)
+- [x] 实现错误转换 (ToDict) (2026-06-28)
+- [ ] 单元测试 (预计 1小时)
+
+**总计**：5小时 (已完成 4/5)
+
+---
+
+**创建时间**：2026-06-28
+**最后更新**：2026-06-28
+**负责人**：待定