4566704
3a44cb9e6a
- 实现 MIoT 客户端核心功能（MQTT 连接、设备管理、属性读写） - 支持云端 API 调用与局域网设备发现（mDNS） - 集成国际化（i18n）多语言支持 - 添加 MIoT 设备规约解析器（spec_parser） - 包含单元测试与使用示例
166 lines
4.0 KiB
Markdown
166 lines
4.0 KiB
Markdown
# 09 - miot_spec.py 移植计划
|
||
|
||
## 概览
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| **Python 文件** | `py-miot/miot_spec.py` (939行) |
|
||
| **Go 文件** | `spec_parser.go` |
|
||
| **状态** | ⚠️ 部分实现 |
|
||
| **优先级** | 🟡 P1 |
|
||
| **预计工作量** | 16-20 小时 |
|
||
|
||
## Python 版本核心类
|
||
|
||
### 数据结构类
|
||
|
||
| 类名 | 行号 | 功能 | Go 状态 |
|
||
|------|------|------|---------|
|
||
| `MIoTSpecValueRange` | 65 | 数值范围（min/max/step） | ❌ 缺失 |
|
||
| `MIoTSpecValueListItem` | 101 | 值列表项 | ❌ 缺失 |
|
||
| `MIoTSpecValueList` | 145 | 值列表 | ❌ 缺失 |
|
||
|
||
### SPEC 基类
|
||
|
||
| 类名 | 行号 | 功能 | Go 状态 |
|
||
|------|------|------|---------|
|
||
| `_SpecStdLib` | 209 | SPEC 标准库（多语言翻译） | ❌ 缺失 |
|
||
| `_MIoTSpecBase` | 436 | SPEC 基类 | ⚠️ 部分 |
|
||
| `MIoTSpecProperty` | 482 | SPEC 属性 | ⚠️ 部分 |
|
||
| `MIoTSpecEvent` | 644 | SPEC 事件 | ⚠️ 部分 |
|
||
| `MIoTSpecAction` | 672 | SPEC 动作 | ⚠️ 部分 |
|
||
| `MIoTSpecService` | 704 | SPEC 服务 | ⚠️ 部分 |
|
||
| `MIoTSpecInstance` | 731 | SPEC 实例（设备） | ⚠️ 部分 |
|
||
|
||
### 核心功能
|
||
|
||
| 功能 | 行号 | 说明 | Go 状态 |
|
||
|------|------|------|---------|
|
||
| SPEC 解析 | 754 | 从 JSON 加载 SPEC | ⚠️ 部分 |
|
||
| 标准库管理 | 296 | 从云端刷新标准库 | ❌ 缺失 |
|
||
| 多语言翻译 | 244-284 | 描述翻译 | ❌ 缺失 |
|
||
| 值格式化 | 599 | 值格式转换 | ⚠️ 部分 |
|
||
| 值精度处理 | 611 | 浮点数精度 | ❌ 缺失 |
|
||
|
||
## Go 版本现状
|
||
|
||
### 已实现的功能
|
||
|
||
- `SpecInstance` 结构体（对应 `MIoTSpecInstance`）
|
||
- `SpecService` 结构体（对应 `MIoTSpecService`）
|
||
- 基本的 SPEC 解析
|
||
|
||
### 缺失的功能
|
||
|
||
1. **值范围和处理**
|
||
- `MIoTSpecValueRange`
|
||
- `MIoTSpecValueList`
|
||
|
||
2. **标准库管理**
|
||
- 从云端下载标准库
|
||
- 多语言翻译
|
||
|
||
3. **属性处理**
|
||
- 表达式求值（`eval_expr`）
|
||
- 值精度处理（`value_precision`）
|
||
|
||
## 移植建议
|
||
|
||
### 第一批任务（核心数据结构）
|
||
|
||
1. **实现值范围类** (2小时)
|
||
- `MIoTSpecValueRange` → `SpecValueRange`
|
||
- `MIoTSpecValueList` → `SpecValueList`
|
||
|
||
2. **实现标准库管理** (4小时)
|
||
- `_SpecStdLib` → `SpecStdLib`
|
||
- 实现云端下载
|
||
- 实现多语言翻译
|
||
|
||
### 第二批任务（属性处理）
|
||
|
||
3. **增强属性处理** (3小时)
|
||
- 实现 `eval_expr`
|
||
- 实现 `value_precision`
|
||
- 实现 `value_format`
|
||
|
||
4. **实现序列化** (2小时)
|
||
- `dump()` 方法
|
||
- JSON 导出
|
||
|
||
### 第三批任务（优化和测试）
|
||
|
||
5. **优化性能** (2小时)
|
||
- 缓存翻译结果
|
||
- 优化 SPEC 解析
|
||
|
||
6. **单元测试** (3小时)
|
||
- 测试值范围
|
||
- 测试属性处理
|
||
- 测试序列化
|
||
|
||
## 技术难点
|
||
|
||
### 1. 表达式求值
|
||
|
||
**问题**：Python 使用 `eval()`，Go 需要其他方案
|
||
|
||
**建议**：
|
||
```go
|
||
// 方案1：不使用表达式（推荐）
|
||
// 在 Go 版本中不支持 expr，直接返回原值
|
||
|
||
// 方案2：使用表达式求值库
|
||
// 使用 github.com/expr-lang/expr
|
||
```
|
||
|
||
### 2. 多语言翻译
|
||
|
||
**问题**：需要管理多语言描述
|
||
|
||
**建议**：
|
||
```go
|
||
type SpecStdLib struct {
|
||
lang string
|
||
devices map[string]map[string]string
|
||
services map[string]map[string]string
|
||
// ...
|
||
}
|
||
|
||
func (s *SpecStdLib) DeviceTranslate(key string) string {
|
||
if translations, ok := s.devices[key]; ok {
|
||
if desc, ok := translations[s.lang]; ok {
|
||
return desc
|
||
}
|
||
// 回退到默认语言
|
||
return translations[defaultLang]
|
||
}
|
||
return ""
|
||
}
|
||
```
|
||
|
||
## 依赖关系
|
||
|
||
| 依赖文件 | 关系 | 说明 |
|
||
|---------|------|------|
|
||
| `miot_error.py` | 强依赖 | 错误定义 |
|
||
| `miot_storage.py` | 强依赖 | 标准库缓存 |
|
||
| `common.py` | 强依赖 | HTTP 请求 |
|
||
|
||
## 进度跟踪
|
||
|
||
- [ ] 实现值范围类 (预计 2小时)
|
||
- [ ] 实现标准库管理 (预计 4小时)
|
||
- [ ] 增强属性处理 (预计 3小时)
|
||
- [ ] 实现序列化 (预计 2小时)
|
||
- [ ] 优化性能 (预计 2小时)
|
||
- [ ] 单元测试 (预计 3小时)
|
||
|
||
**总计**：16小时
|
||
|
||
---
|
||
|
||
**创建时间**：2026-06-28
|
||
**最后更新**：2026-06-28
|
||
**负责人**：待定
|