# Link Health 插件修正（离线版）

## 范围
本次离线变更只覆盖 `luci-app-tr3000-status`：
- 后端只读探测与三态语义
- 前端显示与轮询
- 静态审计、合成 fixture、安装/回滚脚本
- 文档

明确**不**做：
- 不改 `/etc/config/network` `firewall` `dhcp` `wireless`
- 不动 `rc.local`、VXLAN/MSS hotplug、nft include
- 不操作 WG/VXLAN 隧道、MTU、kill switch、MSS
- 不重载 `network` `firewall` `wireless`
- 不登录或修改办公室 OpenWrt `192.168.1.1`
- 不替换 `libc` `rpcd` `ucode` `netifd` `fw4` `mt76` `kmod-*` 等核心包

## 变更摘要

### 后端
- `luci.tr3000_status` 的 `get` 现在返回 `schema_version: 2`。
- 新增字段：
  - `wireguard.interface_up` ∈ `{true, false, null}`
  - `vxlan.invariants.{master_ok, mtu_ok, vni_ok, port_ok, nolearning_ok, local_ok, remote_ok}`
  - `vxlan.all_invariants_ok`
  - `acceleration.*.status` ∈ `{enabled, enabled_unverified, disabled, disabled_by_design, unavailable, healthy, ok, degraded}`
  - `summary.{ok, status, wg_ok, link_ok, route_ok, vxlan_ok, invariant_ok, wg_status}`
- 探测命令统一为只读 `ip -j` + `nft -j`，不再使用目标 query 语法。
- 移除 `wg show wg0 dump`。
- “按设计禁用” (flowtable / HNAT / WARP / full-cone / masquerade) 不再误报为 `unavailable`，而是 `disabled_by_design`。

### 前端
- 三态徽章：`Pass` / `Fail` / `Unknown`。
- 顶栏新增 `summary.status` 总览徽章。
- 加速卡标题改为 `Data path & TCP`。
- 删掉原先的 `wg0:fail` 重复摘要。
- “Active interfaces” 在 link JSON 不可用时显示 `Unavailable`，不再显示误导性的 `0 / 2`。

### 审计
- `tests/audit_tr3000_status.py`：
  - 禁止模式：`wg dump`、`ifup/ifdown`、`ip link set`、`uci set/commit`、`network/firewall/wifi restart`、`reload`、`fs.exec`/`fs.write`/`fs.remove`/`fs.mkdir`、`writefile/unlink/rename`、敏感 key literal、MAC literal。
  - 强制包含的只读命令、ACL 仅 `get`、菜单依赖 `luci-app-tr3000-status`、Makefile 依赖项。
  - 当前结果：`OK: luci-app-tr3000-status passes static audit`。

### 合成 fixture
- `tests/fixtures/` 12 份期望，覆盖：
  1. `all_healthy`
  2. `wg_interface_down`
  3. `wg_stale_handshake`
  4. `route_missing`
  5. `vxlan_missing`
  6. `vxlan_wrong_vni`
  7. `nft_unavailable`
  8. `no_hwmon`
  9. `ip_unavailable`
  10. `malformed_json`
  11. `mss_missing`
  12. `design_invariant_violation`

### 安装与回滚
- `tests/install_preview.sh`：仅升级 `luci-app-tr3000-status`；备份 `/etc/config/*` 与 hotplug；`opkg install --force-reinstall`；仅 `rpcd` + `uhttpd` reload；调用 `ubus call luci.tr3000_status get` 冒烟。
- `tests/rollback_preview.sh`：根据 `prev_version` 还原。
- `tests/verify_immutable.sh`：升级前后必须维持 v46 frozen hash。

## 待执行（受工具限制暂未跑）
1. `scp` 同步源码到 build server `package/custom/luci-app-tr3000-status`。
2. build server 重新编译 `luci-app-tr3000-status` IPK。
3. 把 IPK 与 frozen hash 拉到本机。
4. 在路由器执行 `install_preview.sh`，记录 `ubus call luci.tr3000_status get` 完整输出。
5. 在路由器执行 `verify_immutable.sh`，确认零漂移。
6. 浏览器强制刷新 `/admin/status/tr3000`，记录截图。
7. 若 `summary.status` ≠ `healthy` 或不可变文件 hash 漂移，执行 `rollback_preview.sh`。

## 风险
- 升级期间若 `rpcd` 重启瞬间有浏览器轮询，理论上会造成一次 RPC 失败；前端 `L.resolveDefault(callStatus(), {})` 已吞掉此失败。
- 若 `install_preview.sh` 备份脚本因权限或 BusyBox 限制失败，需要先解决再继续；不要在没有 backup 的情况下继续。

## 不变项
- v46 frozen network/firewall/dhcp/wireless、rc.local、hotplug、MSS 1330、br-lan master、wg0/WG 路线、VXLAN 10/4789/nolearning/MTU 1500、kill switch 均不修改。