impress_sig_mesh_hacs/调试检查清单.md

# SigMesh Gateway - 调试检查清单

**用途**: 系统化排查问题，确保不遗漏任何步骤

---

## 阶段 1: 部署前检查

### 1.1 硬件检查
- [ ] 网关已正确供电
- [ ] USB 转 TTL 模块工作正常
- [ ] 接线正确（TX→RX, RX→TX, GND→GND）
- [ ] 电压匹配（3.3V 或 5V）

### 1.2 系统检查
- [ ] HAOS 版本 ≥ 2024.1.0
- [ ] HACS 已安装且版本 ≥ 1.34.0
- [ ] 串口驱动已安装

```bash
# 检查串口设备
ls -l /dev/ttyUSB*
# 预期输出：crw-rw---- 1 root dialout ... /dev/ttyUSB0
```

### 1.3 权限检查
- [ ] homeassistant 用户在 dialout 组
- [ ] 串口设备权限正确

```bash
# 检查用户组
groups homeassistant

# 如需添加权限
sudo usermod -a -G dialout homeassistant
# 然后重启 HA
```

---

## 阶段 2: 安装检查

### 2.1 文件完整性
- [ ] `custom_components/sigmesh_gateway/` 目录存在
- [ ] `__init__.py` 存在
- [ ] `manifest.json` 存在且格式正确
- [ ] `const.py` 存在
- [ ] `config_flow.py` 存在
- [ ] `coordinator.py` 存在
- [ ] `serial_reader.py` 存在
- [ ] `protocol_parser.py` 存在
- [ ] `platforms/` 目录及所有平台文件存在

### 2.2 HACS 注册
- [ ] `hacs.json` 存在且格式正确
- [ ] README.md 存在

### 2.3 安装验证
```bash
# 检查文件结构
find ~/.homeassistant/custom_components/sigmesh_gateway/ -type f
```

---

## 阶段 3: 配置检查

### 3.1 UI 配置
- [ ] 集成出现在"添加集成"列表中
- [ ] 串口设备可选择
- [ ] 配置可提交
- [ ] 配置后集成状态为"已加载"

### 3.2 YAML 配置（如使用）
```yaml
# 检查 YAML 语法
ha core check

# 预期输出：Configuration check completed
```

---

## 阶段 4: 启动检查

### 4.1 启动日志
```bash
# 查看启动日志
tail -f ~/.homeassistant/home-assistant.log | grep sigmesh
```

检查项：
- [ ] 看到"设置 SigMesh Gateway 集成"
- [ ] 看到"串口已连接"
- [ ] 看到"SigMesh Gateway 协调器已启动"
- [ ] 无 ERROR 级别日志

### 4.2 实体创建
- [ ] 进入"设置 → 设备与服务"
- [ ] 看到 SigMesh Gateway 集成
- [ ] 点击后看到设备列表
- [ ] 实体出现在"设置 → 实体"

---

## 阶段 5: 数据接收检查

### 5.1 串口通信验证
```bash
# 手动测试串口
screen /dev/ttyUSB0 115200

# 发送测试命令
AT
# 预期返回：OK

# 退出：Ctrl+A, 然后 K, 然后 Y
```

### 5.2 数据接收验证
- [ ] 日志中看到"串口接收：+EVENT=..."
- [ ] 无"解码失败"错误
- [ ] 无"无效的 Mesh 消息格式"警告

### 5.3 协议解析验证
- [ ] Opcode 正确识别
- [ ] Payload 正确解析
- [ ] 设备状态正确更新

---

## 阶段 6: 实体功能检查

### 6.1 传感器
- [ ] 传感器实体存在
- [ ] 状态值合理
- [ ] 单位正确显示
- [ ] 状态随时间更新

### 6.2 开关（如有）
- [ ] 开关实体存在
- [ ] 状态显示正确
- [ ] （如已实现）开关操作响应

### 6.3 灯光（如有）
- [ ] 灯光实体存在
- [ ] 亮度调节响应
- [ ] 开关操作响应

### 6.4 设备追踪
- [ ] tracker 实体存在
- [ ] 状态为"home"或"not_home"

---

## 阶段 7: 压力测试

### 7.1 多设备测试
- [ ] 连接 10 个设备，系统稳定
- [ ] 连接 50 个设备，系统稳定
- [ ] 连接 100 个设备，系统稳定
- [ ] 连接 200 个设备，系统稳定

### 7.2 性能监控
```bash
# 查看内存占用
ps aux | grep homeassistant

# 查看 CPU 占用
top -p $(pgrep -f homeassistant)
```

检查项：
- [ ] 内存占用 < 50MB
- [ ] CPU 占用 < 5%
- [ ] 无明显内存泄漏

---

## 阶段 8: 异常处理检查

### 8.1 串口断开测试
- [ ] 拔掉 USB 转 TTL 模块
- [ ] 日志中看到"串口连接已断开"
- [ ] 系统尝试重连
- [ ] 插回后自动恢复连接

### 8.2 异常数据处理
- [ ] 发送畸形数据
- [ ] 系统不崩溃
- [ ] 日志中记录错误
- [ ] 正常数据继续处理

---

## 阶段 9: 日志分析

### 9.1 日志级别验证
```yaml
# 临时启用详细日志
logger:
  logs:
    custom_components.sigmesh_gateway: debug
```

检查项：
- [ ] DEBUG 日志显示原始数据
- [ ] DEBUG 日志显示解析过程
- [ ] INFO 日志显示关键事件
- [ ] WARNING 日志显示警告
- [ ] ERROR 日志显示错误详情

### 9.2 日志清理
- [ ] 测试完成后恢复日志级别
- [ ] 生产环境不启用 DEBUG

---

## 阶段 10: 文档记录

### 10.1 配置记录
- [ ] 记录实际使用的配置参数
- [ ] 记录调整过的参数值
- [ ] 记录参数调整原因

### 10.2 问题记录
- [ ] 记录遇到的问题
- [ ] 记录解决方案
- [ ] 记录排查步骤

---

## 快速诊断流程

```
问题现象
    ↓
┌─────────────────┐
│ 1. 检查集成状态 │
│    设置 → 设备与服务 │
└────────┬────────┘
         │ 未加载
         ↓
┌─────────────────┐
│ 2. 检查日志错误 │
│    home-assistant.log │
└────────┬────────┘
         │ 串口错误
         ↓
┌─────────────────┐
│ 3. 检查串口权限 │
│    groups homeassistant │
└────────┬────────┘
         │ 权限正常
         ↓
┌─────────────────┐
│ 4. 手动测试串口 │
│    screen /dev/ttyUSB0 │
└────────┬────────┘
         │ 无响应
         ↓
┌─────────────────┐
│ 5. 检查硬件连接 │
│    电源/接线/电压 │
└─────────────────┘
```

---

## 常用诊断命令

```bash
# 1. 查看串口设备
ls -l /dev/ttyUSB*

# 2. 查看用户组
groups homeassistant

# 3. 查看实时日志
tail -f ~/.homeassistant/home-assistant.log | grep sigmesh

# 4. 查看集成状态
ha integrations info sigmesh_gateway

# 5. 重启集成
ha integrations reload sigmesh_gateway

# 6. 查看内存占用
ps aux | grep homeassistant | grep -v grep

# 7. 测试串口通信
screen /dev/ttyUSB0 115200

# 8. 查看系统资源
top -p $(pgrep -f homeassistant)
```

---

## 检查清单完成确认

- [ ] 所有阶段检查完成
- [ ] 所有问题已解决
- [ ] 配置参数已记录
- [ ] 系统运行稳定

**检查人**: ______________
**检查日期**: ______________
**系统版本**: HA __________, HACS __________