# 穿山甲 · Pangolin — Flutter 客户端

跨平台网络加速客户端。UI 以 `design/ui_kits/`(mobile + tablet)React 原型为像素基准,
令牌同源自 `design/colors_and_type.css`(Dart 镜像见 `lib/pangolin_theme.dart`)。

## 运行

```bash
flutter pub get
flutter run
# main.dart 已串好:登录 → 引导 → 主框架(连接/节点/统计/账户)
```

## 工程结构

```
lib/
  pangolin_theme.dart      语义 token + 明/暗 ThemeData(零硬编码十六进制,改令牌与 css 两处同改)
  l10n/                    文案资源(单显:任一时刻只渲染中文或英文)
    app_text.dart          抽象契约 + AppLang 枚举
    strings_zh.dart        中文资源        ← CI 红线词扫描目标
    strings_en.dart        英文资源        ← CI 红线词扫描目标
  models/node.dart         节点模型(2 字母码块,无 emoji 国旗)
  state/                   Riverpod 状态层(UI 与数据解耦,mock 数据,接 API 不动 UI)
    app_providers.dart     语言 / 主题 / 套餐视角
    connection_provider.dart 连接状态机(严格三态,禁止乐观显示)
    quota_provider.dart    免费额度状态机(剩余分钟 + 看广告解锁)
    nodes_provider.dart    节点清单 + 智能选择(AUTO 取最低延迟)
  widgets/                 原子组件(连接键三态 / 推荐卡 / 额度卡 / 国家码块 / Tab 滑动仲裁 …)
  screens/                 4 个主页面(同一份代码按断点自适应)
```

## 关键实现要点

- **连接键三态**:`off` 暖灰底+虚线轨道环 / `connecting` clay 实底+旋转弧 / `on` 绿底满环+圆内计时+光晕。
  过渡只走 `box-shadow`/背景色,不做全属性动画。状态严格来自 `connectionProvider`,点击只派发事件——**禁止乐观显示**。
- **智能选择推荐卡**:节点页置顶常驻,accent-subtle 底 + clay 渐变 zap 图标 + 「推荐」胶囊,默认选中。
- **免费额度卡**:剩余分钟 + 进度条(≤3 分钟切 warning 色)+「看广告开始使用」→ 解锁后变绿。
- **Tab 滑动切换**:`HorizontalSwipeArea` 仅接横向拖拽;纵向滚动由列表的纵向识别器在手势竞技场胜出,
  子页滚动区域不会误触发(`DirectionalTabSwitcher` 做 200ms 方向感知滑入)。
- **iPad/宽屏断点**:`LayoutBuilder` 在宽度 ≥900 时切左侧栏分栏(导航行高 ≥48),
  连接页双栏、节点页双列网格——**复用同一批原子组件,仅布局开关,不 fork 页面**。
- **文案全部走 l10n**,界面无红线词(铁律 13),由 `ci/scan-redline.sh` 在 CI 防回归。

## 测试

```bash
flutter analyze                       # 期望零警告
flutter test test/unit test/widget    # 状态机单测 + 组件行为测试
flutter test --update-goldens test/golden   # 首次生成 golden 基准图
flutter test test/golden              # 之后做 golden 回归(连接键三态/推荐卡/额度卡 × 明暗)
```

> golden 基准图依赖本机字体渲染,首次须用 `--update-goldens` 生成并提交;CI 默认只跑 unit + widget。