banban/docs/architecture/05-location-flow.md

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.

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

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

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