|
| 1 | +// Package daylog serves GET /api/v1/day-log — one vehicle's |
| 2 | +// local-calendar-day event timeline. |
| 3 | +// |
| 4 | +// # Taxonomy |
| 5 | +// |
| 6 | +// Every event carries {id, ts, type, layer, vehicle_id, ref_kind, |
| 7 | +// ref_id, payload}. Timestamps are UTC (RFC3339); ts values are the |
| 8 | +// source row's event time, never synthesised. Titles are NOT served |
| 9 | +// by this API: the frontend localises by type so i18n stays complete. |
| 10 | +// |
| 11 | +// Default layer (always on): |
| 12 | +// |
| 13 | +// type source table timestamp field payload (SI) deep link |
| 14 | +// drive_start drives started_at start_place, start_soc_pct /drives/:id |
| 15 | +// drive_end drives ended_at end_place, distance_m, duration_s, /drives/:id |
| 16 | +// energy_used_wh, end_soc_pct |
| 17 | +// charge_start charging_sessions started_at start_place, start_soc_pct /charging/:id |
| 18 | +// charge_end charging_sessions ended_at energy_added_wh, duration_s, /charging/:id |
| 19 | +// end_soc_pct |
| 20 | +// parked fsm_transitions ts from_state — |
| 21 | +// online fsm_transitions ts from_state — |
| 22 | +// asleep fsm_transitions ts from_state — |
| 23 | +// offline fsm_transitions ts from_state — |
| 24 | +// state_change fsm_transitions ts from_state, to_state (unknown target) — |
| 25 | +// locked security_events ts (locked=true) — — |
| 26 | +// unlocked security_events ts (locked=false)— — |
| 27 | +// lock_unknown security_events ts state (unparseable to_state) — |
| 28 | +// sentry_on security_events ts state (proto token, e.g. Armed) — |
| 29 | +// sentry_off security_events ts state (Off/Unknown token) — |
| 30 | +// sentry_unknown security_events ts state (missing to_state) — |
| 31 | +// remote_start_on signal_log ts — — |
| 32 | +// remote_start_off signal_log ts — — |
| 33 | +// sw_update software_updates created_at version, status — |
| 34 | +// sw_update_installed software_updates installed_at version — |
| 35 | +// |
| 36 | +// Optional layers (off by default, enabled via ?layers=): |
| 37 | +// |
| 38 | +// layer type(s) signal field(s) |
| 39 | +// turn_signals turn_signal {value} LightsTurnSignal (enum number, no label map) |
| 40 | +// lights hazards_on/off, high_beams_on/off LightsHazardsActive, LightsHighBeams |
| 41 | +// doors_windows door_open/closed {door}, window {window, value} DoorState*, Fd/Fp/Rd/RpWindow |
| 42 | +// hvac hvac_on {power_w} / hvac_off HvacPower (on = watts != 0) |
| 43 | +// gear gear {gear} drive_telemetry.gear (P/R/N/D) |
| 44 | +// homelink homelink_nearby_on/off, arrived/left_{home, HomelinkNearby, LocatedAtHome, |
| 45 | +// work,favorite} LocatedAtWork, LocatedAtFavorite |
| 46 | +// |
| 47 | +// # Source-of-truth decisions |
| 48 | +// |
| 49 | +// - Drive/charge boundaries come from session rows (drives, |
| 50 | +// charging_sessions), including in-progress rows (NULL end). FSM |
| 51 | +// transitions targeting driving/charging are suppressed: the session |
| 52 | +// tracker already materialised them, and emitting both would double |
| 53 | +// count every trip. FSM is authoritative only for |
| 54 | +// parked/online/asleep/offline. |
| 55 | +// - signal_log carries a change feed, not state. Only in-window |
| 56 | +// transitions become events; the first observation per field is the |
| 57 | +// baseline and emits nothing (state-at-midnight is not something |
| 58 | +// that "happened today"). |
| 59 | +// - user_present has NO source: no telemetry signal, no table, and the |
| 60 | +// legacy security_snapshots table is dropped (ADR-001). It is |
| 61 | +// reported as unavailable, never synthesised. |
| 62 | +// - ValetMode transitions exist in security_events but are out of v1 |
| 63 | +// scope and intentionally not mapped. |
| 64 | +// - Summary sums skip NULL measures; a sum with zero contributors is |
| 65 | +// null (unknown), never a fake 0 — except that counts are exact. |
| 66 | +// |
| 67 | +// # Bounds |
| 68 | +// |
| 69 | +// Output is hard-capped at dayLogEventCap events (truncated=true when |
| 70 | +// over). signal_log and drive_telemetry inputs are fetched with LIMITs; |
| 71 | +// hitting an input cap also sets truncated because edges may be lost. |
| 72 | +package daylog |
0 commit comments