# Device location history and manual positioning

Implementation checkpoint: 26 September 2026.

## Current and historical location

Device overview shows the last valid coordinate separately from its history. Each history record stores customer, device, assignment epoch, latitude, longitude, accuracy when reported, source, optional label, actor for manual entries and UTC time. Location access follows the same customer boundary as the device.

Reported device telemetry is authoritative. When a valid telemetry coordinate arrives:

- it becomes the current position;
- a new history row is added only when it is at least 100 metres from the previous position;
- smaller movements update the current/latest point without adding precision-noise rows;
- any previous manual position remains historical but no longer controls the current display.

The map never treats a general default view as a terminal coordinate. A missing fix is labelled clearly. A last-known position includes its source and timestamp and is not described as live tracking.

## Manual location

Operators with Device Write access can set a location only while the terminal has no valid reported coordinate. The editor supports:

1. searching for an address;
2. choosing or dragging a point on the map;
3. entering latitude and longitude directly.

The server rechecks the device and permission when Save is selected. If valid reported coordinates appeared while the dialog was open, the save is rejected so a manual value cannot overwrite telemetry. Manual changes under 100 metres update the last manual point; changes of 100 metres or more create another history row. The audit log records the actor, device, source and changed coordinates without exposing credentials.

Address search is proxied by the portal through a configurable Nominatim-compatible endpoint. It is intentionally submit-based rather than autocomplete. Results are cached for 24 hours; uncached requests are limited globally to one per second and per user to ten per minute. The UI displays OpenStreetMap attribution. Banks that cannot send address text to a public geocoder must configure an approved internal endpoint or use coordinates/map placement.

## Retention and privacy

Location can identify a terminal placement and must be treated as customer data. Customer administrators see only their own devices and history; SuperAdmins can work across authorized customer context. Do not include precise location in broad exports or support logs unless the task requires it. A production retention period must be agreed with each customer and implemented before long-term fleet rollout.

## Operational checks

- Verify map tiles and geocoder access from the server network, including proxy/firewall policy.
- Verify Device Write is required to set or change a manual location.
- Verify a telemetry fix replaces a manual current position.
- Verify movements below 100 metres do not flood history.
- Verify English and Spanish labels, source names and audit operations.
- Record map/geocoder dependency availability separately from device MQTT health.