统计体系整改 · 实现计划

todo #5 · 四端实时统计 + 多设备归因 + GB 配额 + 统计页重设计 · 阅读版

执行真相源（带 checkbox）：docs/superpowers/plans/2026-06-24-stats-overhaul.md。本 HTML 仅供阅读，不驱动执行。

目标

四端实时统计真生效（上传/下载/延迟/累计流量）+ 服务端按设备归因并按 GB 账户综合卡控 + 统计页按新设计（上聚合·下分设备）像素级还原。

已敲定决策：租户=用户账户（无需层级表）；配额改 GB、按账户综合卡；每设备独立 dp_uuid；分三期；页面改动先设计后开发、用真相源、四端统一元素。

Dart 契约（pangolin/vpn/stats）与 UI 都正确，缺口全在原生侧：

iOS：PacketTunnelProvider 起了 libbox 但 writeStatus/writeGroups 空实现，stats EventChannel 注册了无人 push → 0 数据。
macOS 原生：VpnChannel.swift 硬编码推 0；扩展回调全空。
Android：上下行已工作；延迟（writeGroups urltest）疑似 stale。
Windows：上下行已工作（Clash /connections）；延迟解析 /proxies urltest 疑似拿不到 URLTest 组。

记账链路通：agent V2Ray stats（按 dp_uuid）→ ReportUsage → dp_uuid→user_id → usage_daily(user_id,date)。
无法按设备归因：每账户仅一个 users.dp_uuid，devices 无 dp_uuid 列，usage_daily 无设备维度。
配额分钟制（plans.daily_minutes，连接时凭证 TTL 卡，非持续）。
多租户：user==account 已成立，JWT 全程隔离，无需新表。

现有 stats 设计在 mobile/tablet/desktop 仅聚合；分设备明细任何端都没设计 → Phase 3 必须 design-first。_MetricCard 私有于 stats_page，应提升为公共组件。

Phase 1 · 无 schema 改动

iOS/macOS（核心）：主 App 用 LibboxCommandClient 连 App Group 容器订阅扩展 CommandServer 的 writeStatus/writeGroups，转推 stats channel——对齐 Android StatsHandler 模型。
Android：修延迟（groups 订阅 + latestUrltest 刷新）。
Windows：修 extractUrltestResults() 解析 + 核下发配置含 URLTest 组。
服务端核实：节点 stats API 启用、agent 真上报，使累计流量/周柱有值。

Phase 2 · 后端重型

Schema（双驱动）：devices.dp_uuid 每设备凭证；新表 usage_device_daily；plans.daily_gb。
每设备 dp_uuid：注册时 mint，connect 按设备下发；控制面 dp_uuid→(user_id,device_id) 解析，双写设备表 + 账户 rollup。
GB 综合卡控：账户当日综合 GB 超额即拒；跨阈值 revoke 凭证近持续卡控。
API：暴露按设备用量。

Phase 3 · design-first

设计：走 design-distill，为分设备明细出 mobile/tablet/desktop 原型 + 更新 CONTRACT.md。
实现：提升 metric_card.dart、新增 device_stat_row.dart；四端接分设备 provider；语义 token；红线扫描。
验收：截图 diff + 新增分设备 golden。

先 Phase 1（见效快、零 schema 风险）→ 合并验收 → Phase 2（后端）→ Phase 3（设计可与 Phase 2 并行起草，实现接线依赖 Phase 2 API）。

不在本次范围：组织级多租户层级、协议选择（#8）、KillSwitch（#1/#2/#3）。