From 58227608a7e9c4f75fe09e04b7ca0c94fb3a0096 Mon Sep 17 00:00:00 2001
From: kfj001 <kfj001@gmail.com>
Date: Fri, 16 Oct 2026 01:36:27 +0000
Subject: [PATCH] =?UTF-8?q?Document=20direct-connect=20return=20flow=20(?=
 =?UTF-8?q?=C2=A714):=20manual=20join=20to=20socketQueryDeviceInfo?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/RE_DART_FINDINGS.md | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/docs/RE_DART_FINDINGS.md b/docs/RE_DART_FINDINGS.md
index e0a5bd5..4747e10 100644
--- a/docs/RE_DART_FINDINGS.md
+++ b/docs/RE_DART_FINDINGS.md
@@ -285,6 +285,37 @@ the meaning of `1102` (no pool cmd maps to `0x44E`), and the 17-char
 `equipNo` (sub-device? battery unit? reply convention?). Current probes
 use socket-space ids (`1101/1307/1705/1707`) via `scripts/host_probe3.py`.
 
+## 14. Direct-connect flow (manual AP join → return to app)
+
+`sections/menus/direct_connect/` owns the SoftAP onboarding path:
+
+- The *manual connect* button (`hotspot_guide_widget.dart`) calls
+  `goToSystemWifiSettings()` → `OpenSystemWifiSetting` method channel →
+  OS Wi-Fi picker. The app goes to background.
+- On return, the page (`viewDidLoad`, plus the provider-state listener in
+  `direct_connect.dart`) re-evaluates: with a device SN selected it calls
+  `DirectConnectProvider.socketQueryDeviceInfo()` (also fired from
+  `onSelectHotspot` once wifi state settles).
+- `socketQueryDeviceInfo` first awaits `CommunicationService.directConnect()`,
+  which is true when `connectedFhpAp()` (current SSID is the FHP AP) **or** a
+  BLE device is connected — otherwise it aborts silently.
+- It then issues `queryDeviceInfo` in the *current* transport mode
+  (`_queryDeviceInfoFuture`, args `{"minProtocolVer": "V1.00.00"}`, or
+  `{"installInfo": 2}` for mqtt mode which is HTTP-forwarded instead).
+  In socket mode `_connectBeforeRequest` dials
+  `getWifiGatewayIP():18000` (`"10.100.1.1"` fallback) with ~2 retries.
+- On the reply it updates the device model
+  (`updateFromDeviceInfoInitDataEntity`) and continues with
+  `_queryTrustedDeviceModel` → `_checkConnectedNotTrustedAp`.
+- The `communicate` factory always seeds socket payloads with `"opt"`
+  (operation type, `0` for query), so the on-air discovery frame is shaped
+  `{"opt": 0, "minProtocolVer": "V1.00.00"}` (§3).
+
+Implication: on the SoftAP the app speaks **only** to the gateway IP,
+port **18000**. Port `9000` appears nowhere in the app; `18000` is closed
+on the tested unit, so even the app's own socket path cannot work there —
+consistent with all-silent probes.
+
 ## 9. Bluetooth (BLE) transport — `communication_center/bluetooth`
 
 - `BluetoothManager` (singleton), `BluetoothStatus`: `closed / connected / connecting / interrupted`.