新增 Flutter BLE 客户端与三页控制

.github/workflows/flutter-stage-a.yml

@@ -0,0 +1,28 @@
+name: Flutter Stage A
+on:
+  push:
+    paths: ["flutter_app/**", ".github/workflows/flutter-stage-a.yml"]
+  pull_request:
+    paths: ["flutter_app/**", ".github/workflows/flutter-stage-a.yml"]
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: flutter_app
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '17'
+      - uses: subosito/flutter-action@v2
+        with:
+          flutter-version: '3.44.9'
+          channel: stable
+          cache: true
+      - run: flutter pub get
+      - run: dart format --output=none --set-exit-if-changed lib test tool
+      - run: flutter analyze
+      - run: flutter test
+      - run: flutter build apk --debug

README.md

@@ -1,5 +1,7 @@
 # SatoriManager 项目
 
+Flutter/Android 重构与三页界面位于 [flutter_app](flutter_app/README.md)。旧 Qt 工程仍保留；Flutter 版的真实设备与锁屏运行尚待验收。
+
 ## 项目简介
 SatoriManager 是一个基于 Qt 和 QML 的小型机器人控制项目，用户可以通过移动端远程操控机器人。项目支持模式切换（如自动模式、睡眠模式、人脸识别等）以及机器人头部的旋转和眨眼控制，包含移动端控制客户端和机器人服务器端的通信功能。
 

design-qa.md

@@ -0,0 +1,14 @@
+# SatoriManager 移动端设计验收
+
+final result: passed
+
+- 目标：选定的「柔光仪表」视觉方向，390 × 844 Android 手机尺寸。对照先前确认的控制、动作、设置视觉稿检查。BLE 文案和连接状态按现有实现更新。
+- 浅色与深色：跟随系统亮度切换。两套配色均保留柔和紫色层级；检查背景、文字、摇杆、状态、电量、滑杆、按钮、导航和故障提示。
+- 控制：圆形摇杆、自动／手动切换、松手回中、眼皮滑杆（拖动时发送、松手补发最终值）和眨眼入口均已呈现；没有眼睛图示、摇杆电量环、指令预览、目标数值或发送眼皮按钮。
+- 动作：仅显示轻眨一下与连眨两下两种预设；播放中可取消，持续行为留在控制页。
+- 设置：单设备 BLE 自动发现与连接；没有设备选择列表、可编辑安全范围、Wi-Fi 文案或未实现功能入口。保留配对管理与故障诊断。
+- 截图：`flutter_app/docs/ui_previews/` 收录控制、动作、设置的浅色与深色预览；`flutter_app/build/design_preview/` 下的浅色 `manual.png`、`automatic.png`、`disconnected.png`、`actions.png`、`device.png`、`device_setup.png`，及对应 `dark_` 前缀截图。逐张检查 390 × 844 预览；另检查 320 × 700 布局不溢出。
+- 验证：`flutter analyze` 无问题；Flutter 测试通过；Android debug APK 构建成功。
+- 实机 BLE 连接与机械动作尚未在此环境验证；截图使用预览状态。
+
+P3 后续：动作页的行高比视觉稿略紧；设置页在首屏保留了固件相关配对操作，便于现有 BLE 功能继续使用。

docs/protocol/compatibility.json

@@ -0,0 +1,10 @@
+{
+  "protocol": "SatoriEye BLE v1.2",
+  "source": "ESP-3RDEYE/docs/ble/v1",
+  "files": {
+    "satori-ble-v1.md": "13e6c166aa938bb8904dd58e30645c7dcce7678d977afa472c1075a84e1ec462",
+    "satori_ble_v1_golden_vectors.json": "9f6a9d4b9759c9b36a7ef9c7f6aa0412f15ec8a81cd96128faec62917edbb14e",
+    "satori_ble_v1_1_management_vectors.json": "a8d2869740b370af3e003f086e0f076c1db16ef42ef95222f1bb543493d2ad8a",
+    "satori_ble_v1_2_shared_pairing_vectors.json": "0550f136fb109da8769a9a32ff3dfeb25f095e85419d9961e87a7c6a8982b9a7"
+  }
+}

docs/protocol/satori_ble_v1_1_management_vectors.json

@@ -0,0 +1,102 @@
+{
+  "schema_version": 1,
+  "protocol": "SatoriEye BLE v1.1 owner management",
+  "warning": "All codes are synthetic test inputs, never actual device secrets.",
+  "commands": [
+    {
+      "name": "set_pairing_code",
+      "opcode": 8,
+      "sequence": 2,
+      "token": 305419896,
+      "code": 654321,
+      "hex": "01080200000078563412f1fb0900000000000000"
+    },
+    {
+      "name": "set_leading_zero_code",
+      "opcode": 8,
+      "sequence": 3,
+      "token": 305419896,
+      "code": 42,
+      "hex": "010803000000785634122a000000000000000000"
+    },
+    {
+      "name": "open_transfer",
+      "opcode": 9,
+      "sequence": 4,
+      "token": 305419896,
+      "hex": "0109040000007856341200000000000000000000"
+    },
+    {
+      "name": "cancel_transfer",
+      "opcode": 10,
+      "sequence": 5,
+      "token": 305419896,
+      "hex": "010a050000007856341200000000000000000000"
+    }
+  ],
+  "rejection_cases": [
+    {
+      "name": "default_code_forbidden",
+      "expected_result": 4,
+      "hex": "0108020000007856341240e20100000000000000"
+    },
+    {
+      "name": "code_too_large",
+      "expected_result": 4,
+      "hex": "0108020000007856341240420f00000000000000"
+    },
+    {
+      "name": "code_reserved_nonzero",
+      "expected_result": 4,
+      "hex": "01080200000078563412f1fb0900010000000000"
+    },
+    {
+      "name": "open_reserved_nonzero",
+      "expected_result": 4,
+      "hex": "0109020000007856341201000000000000000000"
+    },
+    {
+      "name": "cancel_reserved_nonzero",
+      "expected_result": 4,
+      "hex": "010a020000007856341201000000000000000000"
+    },
+    {
+      "name": "wrong_token",
+      "expected_result": 6,
+      "hex": "01080200000001000000f1fb0900000000000000"
+    }
+  ],
+  "events": [
+    {
+      "name": "set_code_ok",
+      "hex": "018802000000785634120001000000000cff0000"
+    },
+    {
+      "name": "open_transfer_ok",
+      "hex": "018904000000785634120001040000000cff0000"
+    },
+    {
+      "name": "cancel_transfer_ok",
+      "hex": "018a05000000785634120001040000000cff0000"
+    }
+  ],
+  "scenarios": [
+    "empty_device_default_bootstrap",
+    "existing_identity_never_overwritten",
+    "partial_nvs_fails_closed",
+    "only_owner_changes_code",
+    "persist_failure_preserves_code",
+    "duplicate_set_does_not_rewrite",
+    "code_change_keeps_bond",
+    "default_code_cannot_open_transfer",
+    "open_halts_before_ack",
+    "retry_does_not_extend_window",
+    "stranger_denied_outside_window",
+    "timeout_retains_old_owner",
+    "reboot_closes_window",
+    "new_owner_commit_before_old_bond_delete",
+    "failed_commit_retains_old_owner",
+    "cancel_keeps_old_owner",
+    "new_phone_claim_stays_paused"
+  ]
+}

docs/protocol/satori_ble_v1_2_shared_pairing_vectors.json

@@ -0,0 +1,73 @@
+{
+  "schema_version": 1,
+  "protocol": "SatoriEye BLE v1.2 shared pairing",
+  "warning": "Synthetic test inputs only; no real device secrets.",
+  "reads": [
+    {
+      "name": "shared_device_info",
+      "hex": "010200020201df0100001414d007701702030000",
+      "protocol_minor": 2,
+      "capabilities": 479,
+      "security_policy": 2,
+      "max_bonds": 8
+    }
+  ],
+  "rejection_cases": [
+    {
+      "name": "open_transfer_unsupported",
+      "hex": "0109020000007856341200000000000000000000",
+      "expected_result": 3
+    },
+    {
+      "name": "cancel_transfer_unsupported",
+      "hex": "010a020000007856341200000000000000000000",
+      "expected_result": 3
+    }
+  ],
+  "scenarios": [
+    "three_phones_same_code_bonds_retained",
+    "only_one_connection_no_takeover",
+    "disconnect_reenables_advertising",
+    "failed_connect_reenables_advertising",
+    "changed_code_retains_existing_bonds",
+    "old_code_cannot_enroll_new_phone",
+    "eight_bonds_full_no_eviction",
+    "non_sc_or_unbonded_denied",
+    "upgrade_keeps_existing_bonds",
+    "every_connection_auto_arms_configured_output",
+    "reconnect_auto_arms_without_action_replay",
+    "invalid_explicit_configuration_stays_connected_paused",
+    "pause_cancels_inflight_auto_start",
+    "no_user_configuration_uses_built_in_profile",
+    "maintenance_overrides_preserved",
+    "malformed_configuration_not_hidden_by_defaults",
+    "pause_during_reconnect_backoff_persists_across_retries",
+    "release_lost_ack_replayed_with_default_retry_timing",
+    "release_window_starts_at_completion_and_does_not_extend"
+  ],
+  "built_in_profile": {
+    "id": "satori_c3_v1",
+    "logical_minimum": [
+      500,
+      500,
+      500
+    ],
+    "logical_maximum": [
+      2500,
+      2500,
+      2500
+    ],
+    "startup": [
+      1500,
+      1500,
+      1500
+    ],
+    "source": "Qt mobileclient.h MIN_PWM_VALUE/MAX_PWM_VALUE; mobileclient.cpp currentCH1/2/3"
+  },
+  "timing": {
+    "command_timeout_ms": 500,
+    "command_max_retries": 3,
+    "release_ack_window_ms": 3000,
+    "release_ack_window_origin": "action_completion"
+  }
+}