# IvfTl.Hardware.HilTests — 硬件在环(HIL)回归套件

把合并改造遗留 M 区**真机验证**的检查逻辑沉淀为永久入库的回归用例,防止这些修复以后被改回去。
经真实 `IvfTl.Hardware.Impl.SerialChannelImpl` 端到端连真舱(与去桩后 control 走同一路径)。

## 守护什么

| 测试 | 守护缺陷 | 类型 | 断言 |
|---|---|---|---|
| `FocusZeroHilTests` | **M-06** 按 well 焦点零点 | 纯读 0x11,无电机 | 各 well 读值去重>1(证按 well 分槽,非恒读 well-1);值落在安全 Z 区间 [0,125000] |
| `FrameLengthHilTests` | **M-05** 0x12 写 E方回包帧长(=12)修复 | 纯读(连读不写) | 连续读 12 轮全部 sane 非负(帧长错会致残留字节污染读) |
| `EepromWriteHilTests` | **M-01/02/03** EEPROM 写命令真下发 | 写回环(非破坏) | **默认 Skip**;读 V→写 V+1→读==V+1→写回 V→读==V(立即恢复原值) |

> 帧长表本身另由 `ivf_tl_SerialHelper.Tests/CustomProtocolLengthTests`(纯逻辑单测)逐项锁死;本套件守护真机端到端行为。

## 怎么跑

**前提**:`control` 未运行、`operate` 未运行(否则串口被占,测试会 Skip 而非真验证)。

```bash
# 默认:零写入(只跑两个纯读测试 + 写测试 Skip)
dotnet test ivf_tl_operate_2.0/control/IvfTl.Hardware.HilTests/IvfTl.Hardware.HilTests.csproj -c Debug

# 开写回环(写 EEPROM 后立即恢复原值,非破坏)
HIL_ALLOW_WRITE=1 dotnet test ivf_tl_operate_2.0/control/IvfTl.Hardware.HilTests/IvfTl.Hardware.HilTests.csproj -c Debug
```

详细输出加 `--logger "console;verbosity=detailed"` 看每 well 值/写读回值。

## Skip 语义(诚实,不伪绿)

- **无响应真舱**(无硬件 / control 占口 / 未连接)→ 全部 **Skipped**,常规 `dotnet test`/CI 永绿。
- **写测试**默认 Skipped,需 `HIL_ALLOW_WRITE=1` 才跑。
- 某项在所选舱**不存在**(如某舱无灯光)→ 自动逐舱试,全舱都无才 Skip。

## 安全口径

- 默认运行**零写入**,只读 EEPROM。
- 写回环每次写后**立即恢复原值**,设备状态不变(已真机验证非破坏)。
- **全程不动任何电机**,仅 EEPROM 读写。

## 设计/计划

- 设计:`项目文档/需求文档/specs/2026-06-23-HIL硬件在环回归套件-design.md`
- 实现计划:`项目文档/开发计划/2026-06-23-HIL硬件在环回归套件实现计划.md`