# 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
**负责人**：待定