故障码与网络告警

设备有两条互不相干的异常提示通道，先分清再看码：

通道	编号	严重程度	对设备的影响
故障	F-01 … F-06	停机	停止加热、锁定 Fault 状态机，必须人工复位
网络告警	W-01 … W-04	仅提示	不停机、不锁状态机，离线打印照常可用

F 码来自温控与功率安全（FaultCode，include/controller.h），W 码来自联网层 （NetAlert，include/ui_model.h）。两者不会互相触发，也不会互相掩盖。

故障码（F 码）

进入 Fault 的那一刻判定一次并保持到复位。屏上顶栏显示 F-0x 与对应文案， REST /api/state 的 fault 字段与 MQTT event 主题同步上报，排查时不必连串口。

判定优先级是「硬过温 > 硬过流 > 传感器掉线」—— 越危险的越先报，掉线判据自带 valid 前置，不会掩盖真实的超温。

码	枚举	含义	判据
F-01	AhtLost	仓温传感器掉线	!ahtValid（读数越界或 I²C 无应答）※
F-02	NtcLost	热板 NTC 掉线	!ntcValid（ADC 采到端点，判为开路/短路）※
F-03	BoardOverTemp	热板硬过温	heaterBoardC ≥ 热板保护温度 + 15 ℃
F-04	ChamberOverTemp	仓温硬超上限	chamberC ≥ 耗材仓温上限 + 15 ℃
F-05	OverCurrent	加热回路硬过流	电流绝对值 > 加热电流上限 × 1.5
F-06	InaLost	电流采样掉线	!inaValid（读数越界或 I²C 无应答）※

※ 掉线类（F-01/F-02/F-06）只在自动温控（加热功能）开启且处于预热/打印时才检测， 连续 3 s 无效才锁定。温控关闭时加热输出恒为 0，传感器好坏没有安全意义，掉线不锁机； F-03/F-04/F-05 硬保护不受此限，任何状态都生效。

硬保护阈值相对软保护留有余量：软保护先动作（超温走 100 % 排气、过流走软降功率）， 只有压不住时（越界再超出上表余量并持续 HARD_TRIP_MS = 0.5 s）才升级为停机故障， 避免与软保护抢动作、也避免单次采样尖峰误报。

编号就是枚举值本身（AhtLost = 1 → F-01，None = 0 只是哨兵）。所以新增 故障码只能追加在 FaultCode::Count 之前，且改码时必须同步核对三处：屏上 （tft_ui.cpp）、MQTT event、文档表格。

故障页

故障是全屏独占页：顶栏显示故障码与类别，中部按码给出标题与处理建议，并逐行列出 AHT20 / NTC / INA226 的实测值。

页面上只响应两个输入：

• 长按编码器键 → 复位（见下）
• 系统总开关 → 人工断电（systemEnabled = false，直接回 Idle）

其余输入一律忽略，避免排查期间误改设置。

复位有两条路径，效果不同

路径	动作	结果
故障页长按编码器	clearFault()	热类故障（F-03/04/05）先进入 Cooling 安全姿态（保持 100 % 排气与热板风扇），直到温度回落到软限以下；掉线类（F-01/02/06）直接回 Idle
关闭系统总使能	update() 的 !systemEnabled_ 分支	直接回 Idle，清空全部计时与故障码（人工断电，温控不再参与）

热类复位故意保留硬保护计时：故障态本来就全速排风，若直接回 Idle，排风与热板 风扇会立刻停，等于把设备置于比故障态更热的姿态；保留计时可保证条件仍在时下一控制 周期（50 ms）立即复锁，不会出现「复位后一段无排风」的空窗。

复位不是「当作没事发生」：故障码、累计次数与发生时刻都留在 NVS 里可查。

NVS 故障记忆（断电保持锁定）

每次锁定故障都写入 NVS（FaultRecord：故障码、是否仍锁定、累计锁定次数、发生时刻）。

• 防止拔电绕过保护：热类故障（F-03/F-04/F-05）若在锁定状态下断电重启，setup() 读取记录后调用 restoreFault() 直接回到 Fault 态并显示原故障码，输出层自动 进入全速排风的安全姿态，仍须长按复位或关系统才能解锁。传感器掉线类 （F-01/F-02/F-06）不恢复锁定 —— 开机本来就会重新检测传感器，恢复了也只会被新 判定立即覆盖，所以开机时顺手清掉 latch 标志、保留历史记录。
• 排障历史：复位只清 latch 标志，故障码 / 累计次数 / 最近一次发生时刻都保留在 NVS，通过 /api/state 的 lastFault / faultCount / lastFaultEpoch 字段（或串口 [FAULT] 日志）可查；恢复出厂设置时清除。

判据与边界：ChamberController::persistsAcrossReboot() 决定哪些码跨重启恢复（与 clearFault() 的热类判定同一批）；lastFaultEpoch 在时钟不可用（NTP 未同步且从未手动 校时）时为 0；NVS 写失败只打串口日志不重试 —— 记忆是安全增强而非前提，不能拖住 50 ms 热控节拍。

网络告警（W 码）

网络问题只提示不停机：不进故障页、不锁状态机、不停加热，离线打印照常。设备端的 呈现是主屏把日期位置换成一行告警文案（告警色，时间仍在右侧），系统设置页标题栏中段 显示 W-0x + 文案；REST /api/state 的 netAlert 字段同步上报。

码	枚举	含义	判据
W-01	WifiAuthFail	WiFi 认证失败	断开原因码属认证/关联类连续 10 次（密码错或加密方式不匹配）
W-02	WifiNoAp	找不到 WiFi	断开原因码 NO_AP_FOUND 连续 10 次（SSID 错或超出覆盖）
W-03	MqttAuthFail	MQTT 认证失败	CONNACK 返回 4/5（broker 拒绝匿名或凭据错）连续 10 次
W-04	MqttUnreachable	MQTT 连接超时	其余失败原因连续 10 次（地址/端口/防火墙/网络不通；含 rc=2 客户端 ID 冲突）

为什么是 10 次：一次路由器重启往往拖出好几个断开事件，3 次挡不住，会被误报成 「密码错了」；10 次（MQTT 每 5 s 重试一次，约 50 s；WiFi 侧约 1~2 分钟）才能确认是 真连不上。连上即自动清除；功能开关关闭、离线运行、首次配网（从未存过凭据）都不算 异常，不提示。改过 MQTT 参数后旧告警立即作废清零。WiFi 告警优先于 MQTT —— 前者 是根因，后者多半是连带结果。

两点行为限制需知悉：

• MQTT 的重连在加热中会被跳过（预热/打印或加热占空比非 0 时不重连，避免与 PID 抢资源），因此打印过程中 broker 掉线，W-03/W-04 要等打印结束、重连尝试连续失败 10 次后才会出现。
• 告警本身发不进 MQTT：state 主题虽带 netAlert 字段，但 broker 连不上 （W-03/W-04）时发布不出去，WiFi 断了（W-01/W-02）时整个网络都不可用，所以远程只能 在恢复后从 /api/state 轮询看到。

排障速查

现象	先看	常见原因
屏上停在故障页，加热不动	顶栏 F 码	按上表查判据；热类故障复位后会先冷却，别急着断电
温度显示 -- 或 nan	F-01 / F-02	I²C 接线 / NTC 两芯线 / 供电；注意 Pin 39 is not ADC pin! 那类引脚错配（见 硬件接线与注意事项）
重启后仍是同一个故障	lastFault	热类故障会跨重启恢复锁定，拔电不能绕过，须长按复位
主屏日期位置变成一行提示	W 码	网络类问题，不影响打印；/api/state 的 netAlert 同步可见
明明连不上却没有任何提示	—	首次配网、功能开关关闭、离线运行都刻意不报警；也可能是失败次数还没攒够 10 次
COM4 上什么应用日志都没有	—	正常现象：USB-CDC 与 UART0 日志分流，见 联网功能