本文档仅为架构说明（设计真相源）。具体落地拆解（契约快照实现、前端 flow 用例、L4 冒烟脚本）走各自实现计划（writing-plans）。
+| 缺口 | 严重度 | 现状 & 为什么没测 | 何时 / 怎么补 |
|---|---|---|---|
| 前端统计「上屏数值对不对」 | +中·诉求半覆盖 | +最初诉求是「统计数据对不对」。后端记账已 L4 e2e（ReportUsage → /v1/usage 断言字节）；前端只到单测（device_usage_test/format_test 解析+格式化）。解析对 ≠ 渲染对——没有测试验证统计页拿到真实响应后上屏的数字/曲线是对的。 |
+ 可立即补：widget 级测试，用 e2e server 的真实 /v1/usage 响应喂 stats_page，断言关键数值/曲线上屏。闭合诉求最后一环。 |
+
| 真实流量数据路径 | +高·最大盲区 | +L4 e2e 是注入假 ReportUsage，不是「真 sing-box 出网 → v2ray stats 采集 → 上报记账」。真链路从未自动跑过——这是「我们其实不知道线上准不准」的根盲区。真出网那环仅 usage_v2ray.go 单测覆盖采集解析。 |
+ 贵且脆（单机 docker 真出网重、CI 跑不动）。留后续按需，或本地手动跑一次真连基准。 | +
| 原生隧道层 | +高 | +真正承载流量的代码——client/ios/Runner/VpnManager.swift、client/android/…/PangolinVpnService.kt、macOS 系统扩展——零自动化测试，全靠真机/模拟器手测。 |
+ 依赖真机/模拟器，难纯 CI 化。至少补「连上→可达性探针→断开」的半自动脚本。 | +
| 契约双份可能各自漂移 | +中 | +Dart 与 Go 各冻一份字段面快照，两边是各自独立的真相，理论上可各自漂移（OpenAPI 改了、只更了一边）。 | +真·单源（从 OpenAPI 生成两端契约）是大改，列入 C 类效率项后续做。 | +
| 缺口 | 严重度 | 现状 & 为什么 | 何时 / 怎么补 |
|---|---|---|---|
| CI 是单点 | +中·运维 | +整条 CI 吊在一台 mac（mac-pangolin-2）+ 依赖 jiu 的 relay + Docker Desktop。launchd 持久化尚未激活（见 docs/ci-runner.md 的一次性 ! 命令）——mac 一关/重启 CI 就全停。 |
+ 激活持久化（脚本已就位）；理想归宿是 NAS Linux host runner。 | +
| go-integration job 脆性 | +中 | +跑在裸宿主机（go1.26.1，非容器，testcontainers 要真 docker，DooD 在 Docker Desktop mac 网络不通）——宿主 go 版本漂移即挂；套件 ~5min；曾踩 ryuk 关闭→容器泄漏坑（已用默认 ryuk + -p 1 串行规避）。 |
+ 迁 NAS Linux host runner 可恢复容器化 hermetic；保持 ryuk 开启。 | +
| analyze 严格化（闸·B1） | +中·阻塞 | +去掉 --no-fatal-infos 让 info 变致命，会因 HEAD stats_page.dart 的 withOpacity info 当场红；而清 info 正动 stats-overhaul 在改的同一文件。 |
+ 被 stats-overhaul 耦合阻塞，其合并后立刻做。 | +
| golden 全集（闸·B2） | +中·阻塞 | +golden job 现只跑 components + auth；tablet/desktop-stats golden 与 tablet_pages_golden_test.dart 全是 dirty WIP，并入等于钉死未定稿基线。 |
+ stats-overhaul 合并后并入；连带补回临时摘除的 DeviceUsage 契约快照（Dart+Go）+ e2e /v1/usage/devices 断言。 |
+
| golden 本地难重生 | +低·摩擦 | +Linux 权威基线（mac 渲染不一致），开发机改 UI 后须 docker 起 flutter 容器重生基线，非纯本地。 | +scripts/update-goldens.sh 已封装，文档化即可，非真缺口。 |
+
维护约定：补上某项缺口后，从本表删去对应行（或标 已补）；新发现的盲区即时登记到此，使本节始终等于「当前真实缺口」。
+