73 lines
5.4 KiB
Markdown
73 lines
5.4 KiB
Markdown
# ADR-003: Robot 配网页内连接 Windows 与 macOS 热点
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
Implementation status: implemented and enabled with Guided Hotspot Binding. Exact environment value `NIANCODE_AI_HARDWARE_GUIDED_HOTSPOT_BINDING=0` disables the complete guided path and preserves direct six-digit Binding.
|
|
|
|
## Date
|
|
|
|
2026-08-16
|
|
|
|
## Supersedes
|
|
|
|
- Supersedes only ADR-002's requirement that the user leave Makelore and select the Robot hotspot in the operating-system Wi-Fi panel.
|
|
- Preserves ADR-002's firmware-zero-change, fixed Portal, Wi-Fi credential isolation, Activation, six-digit Binding, `bound` semantics, and exact `=0` rollback.
|
|
|
|
## Context
|
|
|
|
ADR-002 delivered a coherent firmware-zero-change journey, but its `connect_device_ap` step remained manual. The user explicitly requested that Makelore show connectable Robot hotspots and connect the selected hotspot inside the binding dialog on both Windows and macOS.
|
|
|
|
The current firmware exposes an open `Xiaozhi-*` provisioning hotspot. Its SSID prefix is only a convenience filter: it does not authenticate Robot identity, ownership, account Binding, or online readiness. Exact shipped-image and physical-device behavior remain release evidence rather than assumptions.
|
|
|
|
## Decision
|
|
|
|
Electron Main owns a Robot Hotspot Module with platform Adapters:
|
|
|
|
- Windows uses the native WLAN API for open-network scanning, temporary discovery connection, and exact current-SSID verification. It does not parse `netsh` output or persist a Wi-Fi profile.
|
|
- macOS uses CoreWLAN for scanning, association, and exact current-SSID verification. Main owns CoreLocation authorization; CoreWLAN work runs in an abortable worker that owns its Objective-C objects.
|
|
- Unsupported platforms fail safely to the existing system-Wi-Fi/manual fallback.
|
|
|
|
Renderer accesses only two typed Host operations:
|
|
|
|
- `POST /api/works/ai-hardware/provisioning-hotspots/scan` accepts exact body `{}` and returns bounded `{ candidate_id, ssid, signal_percent, connected }` projections.
|
|
- `POST /api/works/ai-hardware/provisioning-hotspots/connect` accepts exact body `{ candidate_id }` and succeeds only after the current SSID exactly matches the selected candidate.
|
|
|
|
Both routes authenticate through the normal loopback Host boundary, check the Main-owned capability, and finish locally before Works credentials or upstream access. Native diagnostics, BSSID, interface names, profiles, and location data never cross into Renderer.
|
|
|
|
Entering `connect_device_ap` starts a scan. Makelore displays nearby eligible hotspots and requires the user to choose one explicitly; it never auto-connects the strongest candidate. A verified connection advances to the existing fixed-Portal step. Permission denial, no candidates, timeout, unsupported platform, or connection failure retains a safe retry and manual system-Wi-Fi path.
|
|
|
|
## Candidate And Operation Rules
|
|
|
|
- Only explicitly open, connectable, printable `Xiaozhi-*` SSIDs no longer than 32 UTF-8 bytes are eligible.
|
|
- Duplicate SSIDs collapse to the strongest candidate. BSSID never leaves Main.
|
|
- Candidate IDs are unpredictable and valid only for the latest bounded Main snapshot; rescan, clear, process restart, or the 60-second TTL invalidates them.
|
|
- Scan and connect are mutually exclusive and bounded. Abort or dialog-session replacement prevents stale permission, worker, or UI continuation.
|
|
- Discovery and association are unauthenticated convenience signals. They must not be presented as trusted physical identity, automatic claim, or protocol-online proof.
|
|
|
|
## Security And Privacy
|
|
|
|
- Main is the only native-network owner. Renderer cannot submit an arbitrary SSID, BSSID, interface, profile, command, or URL.
|
|
- Makelore handles no Robot-hotspot password and no home-network credential. Home Wi-Fi SSID/password remain inside the firmware Portal.
|
|
- Logs and safe errors exclude BSSID, interface/profile details, native diagnostics, Wi-Fi credentials, and location data.
|
|
- The current open SoftAP/plain-HTTP risk and public-environment warning remain. Default-on does not make the channel authenticated.
|
|
|
|
## Verification And Release Gates
|
|
|
|
The implementation passed focused Renderer/Main/native tests, the full unit suite, typecheck, lint, production build, Windows Electron/Koffi/WLAN definition loading, a Windows permission-denied native probe, and independent Standards/Spec review.
|
|
|
|
Before claiming complete two-platform hardware acceptance, release evidence must still include:
|
|
|
|
1. A Windows physical Robot scan, selection, connection, exact-SSID verification, Portal, and Binding smoke with location/Wi-Fi access enabled.
|
|
2. Signed packaged macOS x64 and arm64 permission, scan, association, worker/ASAR/Koffi loading, current-SSID, Portal, and Binding smoke.
|
|
3. Electron E2E through the real Host API and native platform seam for success and recovery outcomes.
|
|
4. Exact shipped-firmware hotspot naming/open-network behavior, fixed Portal, and six-digit issuer/validator compatibility.
|
|
|
|
## Consequences
|
|
|
|
- Users can select and connect a Robot provisioning hotspot without first leaving Makelore, while the manual system path remains available.
|
|
- The firmware, fixed Portal, cloud Binding contract, and credential boundary remain unchanged.
|
|
- Packaging now includes a native Koffi dependency and macOS location usage descriptions, expanding signing and platform acceptance work.
|
|
- Trusted discovery, automatic claim, or new firmware provisioning still requires a separate authenticated protocol and accepted ADR.
|