完善设备端体验与微信校验支持

docs/architecture/05-location-flow.md

@@ -0,0 +1,88 @@
+# Location Flow
+
+## Device-Sourced Location
+
+The mini-program location page displays the bound device's reported location.
+It is not the same as reading the parent's phone location.
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant Device as TalkingQ device
+  participant MQTT as MQTT broker
+  participant Handler as TalkingQMQTTService
+  participant Location as Location service
+  participant Current as child_location_current
+  participant History as child_location_history
+  participant Mini as banban-mini location page
+  participant API as /banban/devices/{device_id}/location
+
+  Device->>MQTT: msg_id=000 with latitude/longitude or GPS response
+  MQTT->>Handler: deliver device event/response
+  Handler->>Location: report_mqtt_device_location(...)
+  Location->>Location: resolve active child binding
+  Location->>Current: upsert latest location
+  Location->>History: insert location history point
+  Handler-->>MQTT: success event_resp
+
+  Mini->>API: GET current location
+  API->>Current: read current row for bound child/device
+  API-->>Mini: current location, accuracy, battery, address fields
+
+  Mini->>API: GET trajectory
+  API->>History: read recent/today points
+  API-->>Mini: trajectory points
+```
+
+## Data Model
+
+```mermaid
+erDiagram
+  device_auth ||--o{ child_location_current : device
+  children ||--o{ child_location_current : child
+  device_auth ||--o{ child_location_history : device
+  children ||--o{ child_location_history : child
+  device_bindings ||--o{ child_location_current : active_binding_source
+
+  child_location_current {
+    int id PK
+    int child_id FK
+    varchar device_id FK
+    decimal lat
+    decimal lng
+    varchar coord_type
+    decimal accuracy_m
+    int battery_pct
+    datetime device_time
+    datetime server_time
+    varchar address
+  }
+
+  child_location_history {
+    int id PK
+    int child_id FK
+    varchar device_id FK
+    decimal lat
+    decimal lng
+    varchar coord_type
+    datetime device_time
+    datetime server_time
+  }
+```
+
+## Review / Audit Wording
+
+```text
+Location is sourced from the bound child device and shown to the parent for
+device tracking, trajectory, and alarm context. It is not used to get the
+parent phone's current location unless a separate phone-location feature is
+added later.
+```
+
+## Source Anchors
+
+- Mini-program location page: `banban-mini/src/pages/location/index.tsx`
+- Location API client: `banban-mini/src/services/location.ts`
+- Device location routes: `talkingq-url/banban/routers/devices.py`
+- Location service: `talkingq-url/banban/service/location.py`
+- MQTT persistence: `talkingq-url/handlers/mqtt_handler.py`