impress_sig_mesh_hacs/问题修复记录.md

# 问题修复记录

## 2026-04-16: 修复 callback 导入缺失错误

### 问题描述
配置集成时出现 `"Invalid handler specified"` 错误

### 错误日志

#### 错误：配置流程无法加载
```
无法加载配置向导：{"message":"Invalid handler specified"}
```

**原因**: `config_flow.py` 中使用了 `@callback` 装饰器但没有导入

### 解决方案

#### 修复：添加 callback 导入
```python
from homeassistant.core import callback
```

### 提交记录
| Commit | 说明 |
|--------|------|
| 4031747 | fix: 添加缺失的 callback 导入 |

### 部署步骤
```bash
cp -r custom_components/sigmesh_gateway ~/.homeassistant/custom_components/
ha core restart
```

---

## 2026-04-16: 修复平台加载和 OptionsFlow 错误（第二次修复）

### 问题描述
平台文件设置时出现 `'NoneType' object has no attribute 'values'` 错误

### 错误日志

#### 错误 1: 平台文件访问 None 数据
```
AttributeError: 'NoneType' object has no attribute 'values'
File: sensor.py, line 40
File: binary_sensor.py, line 37
File: switch.py, line 34
File: light.py, line 40
File: device_tracker.py, line 34
```

**原因**: `coordinator.data` 在初始化时为 `None`

#### 错误 2: OptionsFlow 初始化错误
```
TypeError: SigMeshGatewayOptionsFlow() takes no arguments
File: config_flow.py, line 74
```

**原因**: `async_get_options_flow` 是静态方法，传递了 `config_entry` 参数，但 `__init__` 不接受参数

### 解决方案

#### 修复 1: 平台文件添加 None 检查
```python
async def async_setup_entry(...):
    if coordinator.data is None:
        _LOGGER.debug("协调器数据为空，等待设备数据")
        return

    for device in coordinator.data.values():
        ...
```

#### 修复 2: 修复 async_get_options_flow
```python
@callback
def async_get_options_flow(self) -> SigMeshGatewayOptionsFlow:
    """获取选项流程."""
    return SigMeshGatewayOptionsFlow()
```

#### 修复 3: OptionsFlow 添加 __init__
```python
class SigMeshGatewayOptionsFlow(config_entries.OptionsFlow):
    def __init__(self) -> None:
        """初始化选项流程."""
        self._errors: dict[str, str] = {}
```

### 提交记录
| Commit | 说明 |
|--------|------|
| 311cfbb | fix: 修复平台文件和 OptionsFlow 错误 |

### 部署步骤
```bash
cp -r custom_components/sigmesh_gateway ~/.homeassistant/custom_components/
ha core restart
```

---

## 2026-04-16: 修复平台加载和 OptionsFlow 错误（第一次修复）

### 问题描述
配置集成时出现错误，无法加载平台实体

### 错误日志

#### 错误 1: 平台模块加载失败
```
ModuleNotFoundError: No module named 'custom_components.sigmesh_gateway.sensor'
```

**原因**: 平台文件放在 `platforms/` 子目录中，但 HA 期望平台文件直接在集成根目录下

#### 错误 2: OptionsFlow config_entry 错误
```
AttributeError: property 'config_entry' of 'SigMeshGatewayOptionsFlow' object has no setter
```

**原因**: 新版 HA 中 OptionsFlow 自动提供 `self.config_entry`，不需要手动设置

### 解决方案

#### 修复 1: 移动平台文件到集成根目录
```bash
# 从 platforms/ 移到根目录
mv platforms/sensor.py .
mv platforms/binary_sensor.py .
mv platforms/switch.py .
mv platforms/light.py .
mv platforms/device_tracker.py .
rmdir platforms
```

#### 修复 2: 修复 OptionsFlow
```diff
class SigMeshGatewayOptionsFlow(config_entries.OptionsFlow):
    """SigMesh Gateway 选项流程."""

-   def __init__(self, config_entry: config_entries.ConfigEntry) -> None:
-       """初始化选项流程."""
-       self.config_entry = config_entry

    async def async_step_init(self, user_input: dict[str, Any] | None = None) -> FlowResult:
```

#### 修复 3: 添加集成图标
- 复制图标到 `custom_components/sigmesh_gateway/icons/icon.png`
- HA 会自动识别该图标并显示在集成页面

### 提交记录
| Commit | 说明 |
|--------|------|
| 19774a4 | fix: 修复平台加载和 OptionsFlow 错误 |

### 部署步骤
```bash
# 复制更新后的集成文件
cp -r /home/ubuntu/workspace/cherry-studio/enginneer/impress_sig_mesh_hacs/custom_components/sigmesh_gateway \
      <HA 配置目录>/custom_components/

# 重启 Home Assistant
ha core restart
```

### 验证
重启后，在 HA UI 中重新尝试添加集成，应能正常显示配置表单和创建实体。

---

## 2026-04-15: 修复配置向导 500 错误

### 问题描述
添加集成时出现 500 Internal Server Error

### 根本原因
1. **类型注解错误**：`config_flow.py` 使用了小写 `any` 而非 `Any`
2. **依赖包不存在**：`manifest.json` 中引用了不存在的 `bleak-mesh>=0.2.0`
3. **导入错误**：`coordinator.py` 从错误的模块导入 `MeshMessageEvent` 和 `ProvDeviceEvent`

### 错误日志

#### 错误 1: 依赖包不存在
```
homeassistant.requirements.RequirementsNotFound:
Requirements for sigmesh_gateway not found: ['bleak-mesh>=0.2.0'].
```

#### 错误 2: 导入错误
```
Error occurred loading flow for integration sigmesh_gateway:
cannot import name 'MeshMessageEvent' from 'custom_components.sigmesh_gateway.protocol_parser'
```

### 解决方案

#### 修复 1: config_flow.py 类型注解
```diff
+ from typing import Any

- async def async_step_user(self, user_input: dict[str, any] | None = None) -> FlowResult:
+ async def async_step_user(self, user_input: dict[str, Any] | None = None) -> FlowResult:
```

#### 修复 2: manifest.json 依赖
```diff
- "requirements": ["pyserial-asyncio==0.6", "bleak-mesh>=0.2.0"],
+ "requirements": ["pyserial-asyncio-fast>=0.6"],
```

#### 修复 3: coordinator.py 导入
```diff
from .protocol_parser import (
    DeviceManager,
    DeviceState,
-   MeshMessageEvent,
    ParsedMeshMessage,
-   ProvDeviceEvent,
    ProtocolParser,
)
+ from .serial_reader import (
+     MeshMessageEvent,
+     ProvDeviceEvent,
+     SerialReader,
+ )
```

### 提交记录
| Commit | 说明 |
|--------|------|
| 472fec4 | fix: 修复 coordinator.py 导入错误 |
| e905410 | fix: 修复 manifest.json 依赖错误 |
| 66b86e3 | fix: 修复 config_flow.py 类型注解错误 |

### 部署步骤
```bash
# 复制更新后的集成文件
cp -r /home/ubuntu/workspace/cherry-studio/enginneer/impress_sig_mesh_hacs/custom_components/sigmesh_gateway \
      <HA 配置目录>/custom_components/

# 重启 Home Assistant
ha core restart
```

### 验证
重启后，在 HA UI 中重新尝试添加集成，应能正常显示配置表单。