impress_sig_mesh_hacs/调试信息收集.md

# 调试信息收集指南

**问题**: 配置向导 500 Internal Server Error

---

## 1. 必收集的信息

### 1.1 Home Assistant 日志

```bash
# 实时查看日志（在添加集成时）
tail -f ~/.homeassistant/home-assistant.log | grep -E "(sigmesh|error|Error|ERROR)" -i

# 或查看完整日志
cat ~/.homeassistant/home-assistant.log > ~/ha_full_log.txt
```

**关键信息**:
- [ ] 集成加载时的错误堆栈
- [ ] 任何提到 `sigmesh_gateway` 的行
- [ ] 错误发生时间点的日志

---

### 1.2 Home Assistant 版本信息

```bash
# 查看 HA 版本
ha --version

# 或在 HA UI: 设置 → 关于
# 记录：HA 版本、Python 版本、操作系统
```

**需要记录**:
- Home Assistant 版本：__________
- Python 版本：__________
- 操作系统：__________
- 安装方式（HAOS/Container/Supervised/Core）: __________

---

### 1.3 浏览器控制台错误

**Chrome/Edge**:
1. 按 `F12` 打开开发者工具
2. 切换到 `Console` 标签
3. 点击添加集成按钮
4. 截图或复制所有红色错误信息

**需要记录**:
- [ ] 控制台错误截图
- [ ] Network 标签中失败的请求详情

---

## 2. 代码相关问题排查

### 2.1 检查集成文件完整性

```bash
# 检查文件是否存在
ls -la ~/.homeassistant/custom_components/sigmesh_gateway/

# 预期输出应包含:
# __init__.py
# config_flow.py
# const.py
# coordinator.py
# manifest.json
# serial_reader.py
# protocol_parser.py
```

**检查项**:
- [ ] 所有文件都存在
- [ ] 文件大小不为 0
- [ ] 文件权限正确（homeassistant 用户可读）

---

### 2.2 验证 manifest.json 格式

```bash
# 检查 JSON 格式
python3 -m json.tool ~/.homeassistant/custom_components/sigmesh_gateway/manifest.json
```

**如报错，说明 JSON 格式有问题**

---

### 2.3 检查 Python 语法错误

```bash
# 逐个检查 Python 文件
python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/__init__.py
python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/config_flow.py
python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/const.py
python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/coordinator.py
python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/serial_reader.py
python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/protocol_parser.py

# 检查 platforms 目录
python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/platforms/sensor.py
python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/platforms/switch.py
python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/platforms/light.py
python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/platforms/binary_sensor.py
python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/platforms/device_tracker.py
```

**如报错，记录具体错误信息**:
```
文件：__________
错误：__________
行号：__________
```

---

### 2.4 检查依赖是否安装

```bash
# 查看 manifest.json 中的依赖
cat ~/.homeassistant/custom_components/sigmesh_gateway/manifest.json | grep requirements

# 检查是否已安装
pip list | grep -E "(pyserial|bleak)"
```

**当前依赖**:
```json
"requirements": ["pyserial-asyncio==0.6", "bleak-mesh>=0.2.0"]
```

---

## 3. 启用详细日志

### 3.1 修改 configuration.yaml

```yaml
# configuration.yaml
logger:
  default: warning
  logs:
    custom_components.sigmesh_gateway: debug
    custom_components.sigmesh_gateway.config_flow: debug
    custom_components.sigmesh_gateway.serial_reader: debug
    custom_components.sigmesh_gateway.protocol_parser: debug
    custom_components.sigmesh_gateway.coordinator: debug
    homeassistant.loader: debug
    homeassistant.config_entries: debug
```

### 3.2 重启后重新测试

```bash
# 重启 HA
ha core restart

# 等待 30 秒后查看日志
tail -f ~/.homeassistant/home-assistant.log
```

---

## 4. 常见问题和解决方案

### 问题 1: `No module named 'serial'`

**解决方案**:
```bash
# 进入 HA 环境安装
docker exec homeassistant pip install pyserial-asyncio==0.6

# 或 HAOS
ha addons ssh

# 然后重启
ha core restart
```

### 问题 2: `cannot import name 'XXX' from 'homeassistant.XXX'`

**原因**: HA 版本不兼容

**解决方案**:
- 检查 HA 版本是否 ≥ 2024.1.0
- 如版本过低，升级 HA 或修改代码适配

### 问题 3: `ModuleNotFoundError: No module named 'custom_components'`

**原因**: 文件路径错误

**解决方案**:
```bash
# 确认目录结构
ls -la ~/.homeassistant/custom_components/
# 应该是 sigmesh_gateway/ 直接在 custom_components/ 下
```

### 问题 4: config_flow 导入错误

**检查**:
```bash
# 查看 config_flow.py 的导入语句
head -30 ~/.homeassistant/custom_components/sigmesh_gateway/config_flow.py
```

---

## 5. 调试信息模板

**请填写以下信息**:

```
=== 环境信息 ===
HA 版本：__________
Python 版本：__________
操作系统：__________
安装方式：__________

=== 错误信息 ===
浏览器控制台错误：
__________

HA 日志错误（完整堆栈）:
__________

=== 已尝试的排查 ===
- [ ] 检查文件完整性
- [ ] 验证 Python 语法
- [ ] 检查依赖安装
- [ ] 启用详细日志

=== 附加信息 ===
- 集成文件部署路径：__________
- 是否已重启 HA: [ ] 是 [ ] 否
- 之前是否能正常加载：[ ] 是 [ ] 否
- 最近是否有代码变更：[ ] 是 [ ] 否
```

---

## 6. 快速诊断脚本

```bash
#!/bin/bash
# diagnose.sh - 快速诊断脚本

HA_CONFIG="${HOME}/.homeassistant"
INTEGRATION="${HA_CONFIG}/custom_components/sigmesh_gateway"

echo "=== SigMesh Gateway 诊断工具 ==="
echo ""

# 1. 检查文件存在
echo "1. 检查文件完整性..."
if [ -d "$INTEGRATION" ]; then
    echo "   ✓ 集成目录存在"
    ls -1 "$INTEGRATION"
else
    echo "   ✗ 集成目录不存在"
    exit 1
fi

# 2. 检查 Python 语法
echo ""
echo "2. 检查 Python 语法..."
for file in "$INTEGRATION"/*.py "$INTEGRATION"/platforms/*.py; do
    if python3 -m py_compile "$file" 2>/dev/null; then
        echo "   ✓ $(basename $file)"
    else
        echo "   ✗ $(basename $file) - 语法错误"
    fi
done

# 3. 检查依赖
echo ""
echo "3. 检查依赖..."
pip list | grep -E "(serial|bleak)" || echo "   未找到相关依赖"

# 4. 查看最近日志
echo ""
echo "4. 最近日志 (sigmesh 相关)..."
tail -100 "${HA_CONFIG}/home-assistant.log" | grep -i sigmesh || echo "   无相关日志"

echo ""
echo "=== 诊断完成 ==="
```

保存为 `diagnose.sh`，运行：
```bash
chmod +x diagnose.sh
./diagnose.sh
```

---

## 7. 下一步

收集完上述信息后：

1. **查看日志中的完整错误堆栈** - 这是定位问题的关键
2. **运行快速诊断脚本** - 自动检查常见问题
3. **提供调试信息模板中的内容** - 用于进一步分析

**最关键的调试信息**:
1. `home-assistant.log` 中集成加载时的完整错误堆栈
2. 浏览器控制台的 JavaScript 错误
3. `python3 -m py_compile` 的语法检查结果