docs(robot): accept guided hotspot binding v1
This commit is contained in:
@@ -0,0 +1,74 @@
|
||||
# ADR-002: Robot V1 采用引导式热点配网并衔接六位绑定
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
Implementation status: planned; the capability must remain disabled by default until the pilot release gates pass.
|
||||
|
||||
## Date
|
||||
|
||||
2026-08-16
|
||||
|
||||
## Supersedes
|
||||
|
||||
- For V1 delivery only, this decision supersedes the proposed Security 2 / automatic-claim onboarding path in task `20260816-device-provisioning-flow-a4d91c`.
|
||||
- Authenticated BLE provisioning and automatic claim remain a deferred production-security direction, not a current implementation contract.
|
||||
|
||||
## Related
|
||||
|
||||
- Source proposal commit `14afe4a`: `.project-docs/10-decisions/proposals/20260816-minimal-firmware-onboarding-c3e8b7__guided-hotspot-binding-v1.md`
|
||||
- Current Robot binding implementation: `src/pages/AiHardware/index.tsx`, `src/lib/ai-hardware.ts`, `electron/api/routes/ai-hardware.ts`
|
||||
- Firmware audit target: `D:\Datas\HardwareProjects\xiaozhi-esp32-firmware` at audited commit `0449e51`
|
||||
|
||||
## Context
|
||||
|
||||
The audited firmware source enters Hotspot provisioning and serves its configuration portal, but the exact resolved component and shipped device image have not yet been verified. Makelore already provides the cloud Binding operation that accepts a six-digit activation code and an Agent. The firmware source does not expose a trusted nearby-device discovery/correlation protocol, and changing it to authenticated BLE plus automatic claim would require firmware, manufacturing identity, cloud, streaming, recovery, and physical-device contracts that are not ready.
|
||||
|
||||
The immediate product goal is therefore to put provisioning guidance inside the existing Robot binding experience while keeping firmware changes at zero.
|
||||
|
||||
## Decision
|
||||
|
||||
V1 is a Renderer-guided, Main-gated workflow:
|
||||
|
||||
`choose_path -> prepare_robot -> connect_device_ap -> configure_wifi -> reconnect_internet -> enter_activation_code -> binding -> bound`
|
||||
|
||||
- Makelore explains how to place the Robot in provisioning mode and connect the computer to the Robot's existing Wi-Fi hotspot through the operating system.
|
||||
- Electron Main alone may open the fixed system-browser portal `http://192.168.4.1/`; Renderer never supplies or receives an arbitrary portal URL.
|
||||
- After Wi-Fi provisioning, Makelore instructs the user to reconnect the computer to the internet and obtain the freshly issued six-digit activation code from the Robot.
|
||||
- Binding continues to use the existing `bindAiHardwareDevice(activationCode, agentId, { operationId })` cloud contract.
|
||||
- `bound` means account Binding succeeded. It does not prove the Robot is currently online or protocol-ready.
|
||||
|
||||
The guided path is controlled by a Main-owned `guidedHotspotBinding` capability. It is `false` by default. Public builds with the capability disabled retain the existing direct six-digit Binding flow.
|
||||
|
||||
The planned Host API surface is deliberately small:
|
||||
|
||||
- `GET /api/works/ai-hardware/provisioning-capabilities` has no body/query and succeeds with the standard Host envelope `{ success: true, data: { guided_hotspot_binding: boolean } }`.
|
||||
- `POST /api/works/ai-hardware/provisioning-portal/open` accepts the exact body `{}`, has no query, and succeeds with `{ success: true, data: { opened: true } }`.
|
||||
- Portal open must check the Main-owned capability before invoking the opener. Disabled access returns logical `403 / AI_HARDWARE_PROVISIONING_DISABLED`; opener failure returns logical `502 / AI_HARDWARE_PORTAL_OPEN_FAILED`. Like existing handled Host API errors, those logical failures use the standard envelope over outer HTTP 200.
|
||||
- Both operations are local Main actions and must return before acquiring a Works access token or contacting an upstream service.
|
||||
|
||||
## Security And Recovery Rules
|
||||
|
||||
- The current firmware hotspot and portal are open/plain HTTP. V1 is an internal pilot only; product copy must warn the user not to perform the flow in an untrusted public environment.
|
||||
- Wi-Fi SSID/password entry stays in the firmware portal. Makelore must not collect, log, persist, or proxy Wi-Fi credentials.
|
||||
- Cancel, back, and application restart never imply that Wi-Fi changes on the Robot were reverted. The user is guided to reconnect and restart provisioning if needed.
|
||||
- A same-process ambiguous Binding retry reuses the same operation ID. An invalid/expired/consumed activation code clears both code and retained operation ID; the next freshly issued code gets a new operation ID.
|
||||
- Main must project `ai_hardware_activation_code_invalid` as non-retryable even if an upstream response incorrectly marks it retryable.
|
||||
- After application restart, Makelore cannot correlate an earlier code or Binding outcome from the current overview DTO. It must not replay the old code or operation ID; the user obtains a fresh code or stops.
|
||||
|
||||
## Release Gates
|
||||
|
||||
The capability may be enabled only after all of the following are evidenced:
|
||||
|
||||
1. The exact shipped Robot component/image is confirmed to use the audited Hotspot portal flow and fixed portal address.
|
||||
2. The deployed activation issuer emits exactly six ASCII digits accepted by the existing Works Binding validator, with documented freshness and consumption behavior.
|
||||
3. Focused Renderer/Main route tests, Electron E2E through the real Host API seam, and a physical-device smoke all pass.
|
||||
4. The public/default configuration remains disabled until the open SoftAP/plain-HTTP risk is explicitly accepted for the intended pilot population.
|
||||
|
||||
## Consequences
|
||||
|
||||
- The first implementation is desktop-only and requires no firmware, BLE, manufacturing, or cloud-contract change.
|
||||
- V1 cannot truthfully advertise automatic nearby-device discovery or automatic device claim.
|
||||
- The UI becomes a single coherent onboarding journey while system Wi-Fi selection and firmware portal entry remain explicit user actions.
|
||||
- A later authenticated BLE/automatic-claim design requires a new accepted ADR and must not silently widen this V1 interface.
|
||||
@@ -5,6 +5,7 @@
|
||||
| ID | Decision | Status | Date | Applies To | Detail |
|
||||
|---|---|---|---|---|---|
|
||||
| ADR-001 | AI 绘画采用 Workspace / Conversation / Task 分层状态与服务端持久 Conversation Session | Accepted | 2026-08-11 | AI 绘画客户端、Main 适配器、Works Square API | `adr-001-ai-design-conversation-ownership.md` |
|
||||
| ADR-002 | Robot V1 采用 Main 门控的引导式热点配网并衔接现有六位 Binding | Accepted / planned, default off | 2026-08-16 | Robot Renderer、Host API、Electron Main、现有固件热点入口 | `adr-002-robot-guided-hotspot-binding-v1.md` |
|
||||
|
||||
## Superseded Decisions
|
||||
|
||||
|
||||
Reference in New Issue
Block a user