feat(hunt): track walking distance via GPS, show live locations on map

Add foreground-only GPS distance tracking for hunts

shared/types/map.ts

@@ -0,0 +1,58 @@
+/**
+ * Shared DTO shapes for the organizer live map. Both endpoints return plain
+ * JSON (no SuperJSON) with `Date` fields serialized as ISO strings and Prisma
+ * `Decimal` coordinates coerced to numbers.
+ */
+
+export type MapUser = {
+  id: number;
+  name: string;
+  email: string;
+};
+
+export type MapTeam = {
+  id: number;
+  name: string;
+  owner: MapUser;
+  members: MapUser[];
+};
+
+export type MapPosition = {
+  userId: number;
+  lat: number;
+  lon: number;
+  accuracy: number | null;
+  recordedAt: string;
+};
+
+export type MapAnswer = {
+  id: number;
+  lat: number;
+  lon: number;
+  createdAt: string;
+  memberId: number;
+  teamId: number;
+  pictureUrl: string | null;
+  quest: {
+    id: number;
+    title_de: string;
+    title_en: string;
+  };
+};
+
+export type HuntMapData = {
+  teams: MapTeam[];
+  positions: MapPosition[];
+  answers: MapAnswer[];
+};
+
+export type TrailPoint = {
+  lat: number;
+  lon: number;
+  accuracy: number | null;
+  recordedAt: string;
+};
+
+export type UserTrail = {
+  points: TrailPoint[];
+};

shared/utils/geo.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, it } from 'bun:test';
+import { computeTrackDistance, haversine, type GeoPoint } from './geo';
+
+// One degree of latitude is ~111_195 m, so these small deltas give
+// predictable segment lengths: 0.0001° ≈ 11.12 m, 0.00001° ≈ 1.11 m.
+const DEG = 111_195;
+
+function pt(
+  lat: number,
+  lon: number,
+  seconds: number,
+  accuracy?: number | null
+): GeoPoint {
+  return { lat, lon, accuracy, recordedAt: new Date(seconds * 1000) };
+}
+
+describe('haversine', () => {
+  it('returns 0 for identical points', () => {
+    expect(haversine(pt(0, 0, 0), pt(0, 0, 0))).toBe(0);
+  });
+
+  it('measures one degree of latitude along a meridian', () => {
+    const d = haversine({ lat: 0, lon: 0 }, { lat: 1, lon: 0 });
+    expect(Math.abs(d - DEG)).toBeLessThan(1);
+  });
+
+  it('measures one degree of longitude along the equator', () => {
+    const d = haversine({ lat: 0, lon: 0 }, { lat: 0, lon: 1 });
+    expect(Math.abs(d - DEG)).toBeLessThan(1);
+  });
+
+  it('is symmetric', () => {
+    const a = { lat: 52.5, lon: 13.4 };
+    const b = { lat: 52.6, lon: 13.5 };
+    expect(haversine(a, b)).toBeCloseTo(haversine(b, a), 6);
+  });
+});
+
+describe('computeTrackDistance', () => {
+  it('returns 0 for empty input', () => {
+    expect(computeTrackDistance([])).toBe(0);
+  });
+
+  it('returns 0 for a single point', () => {
+    expect(computeTrackDistance([pt(0, 0, 0)])).toBe(0);
+  });
+
+  it('sums a normal multi-point walk', () => {
+    const points = [
+      pt(0, 0, 0),
+      pt(0.0001, 0, 10),
+      pt(0.0002, 0, 20),
+      pt(0.0003, 0, 30)
+    ];
+    // three ~11.12 m segments
+    const d = computeTrackDistance(points);
+    expect(d).toBeGreaterThan(32);
+    expect(d).toBeLessThan(35);
+  });
+
+  it('excludes fixes with accuracy worse than 50 m', () => {
+    const points = [
+      pt(0, 0, 0, 5),
+      // far off path, bad accuracy → dropped
+      pt(0, 0.001, 10, 100),
+      pt(0.0001, 0, 20, 5)
+    ];
+    const d = computeTrackDistance(points);
+    // only the ~11 m A→C segment counts, not the ~222 m detour via B
+    expect(d).toBeGreaterThan(10);
+    expect(d).toBeLessThan(50);
+  });
+
+  it('keeps accuracy of exactly 50 m', () => {
+    const points = [pt(0, 0, 0, 50), pt(0.0001, 0, 10, 50)];
+    const d = computeTrackDistance(points);
+    expect(d).toBeGreaterThan(10);
+    expect(d).toBeLessThan(13);
+  });
+
+  it('rejects teleport candidates and preserves the anchor', () => {
+    const points = [
+      pt(0, 0, 0),
+      // ~1112 m in 1 s → far above 7 m/s → rejected, anchor stays at A
+      pt(0.01, 0, 1),
+      // ~11 m from A over 2 s → 5.6 m/s → accepted
+      pt(0.0001, 0, 2)
+    ];
+    const d = computeTrackDistance(points);
+    expect(d).toBeGreaterThan(10);
+    expect(d).toBeLessThan(13);
+  });
+
+  it('ignores stationary jitter below 5 m', () => {
+    const jitter = [
+      pt(0, 0, 0),
+      pt(0.00001, 0, 10), // ~1.1 m
+      pt(0.00002, 0, 20) // ~2.2 m from anchor
+    ];
+    expect(computeTrackDistance(jitter)).toBe(0);
+
+    // a real move after the jitter is still measured from the original anchor
+    const withMove = [...jitter, pt(0.0002, 0, 30)];
+    const d = computeTrackDistance(withMove);
+    expect(d).toBeGreaterThan(21);
+    expect(d).toBeLessThan(24);
+  });
+
+  it('dedupes and sorts out-of-order points', () => {
+    const a = pt(0, 0, 0);
+    const b = pt(0.0001, 0, 10);
+    const c = pt(0.0002, 0, 20);
+    const shuffled = [c, a, b, a, c, b];
+    const d = computeTrackDistance(shuffled);
+    // two ~11.12 m segments after dedupe + sort
+    expect(d).toBeGreaterThan(21);
+    expect(d).toBeLessThan(24);
+  });
+
+  it('accepts string recordedAt values', () => {
+    const points: GeoPoint[] = [
+      { lat: 0, lon: 0, recordedAt: new Date(0).toISOString() },
+      { lat: 0.0001, lon: 0, recordedAt: new Date(10_000).toISOString() }
+    ];
+    const d = computeTrackDistance(points);
+    expect(d).toBeGreaterThan(10);
+    expect(d).toBeLessThan(13);
+  });
+
+  it('returns an integer number of meters', () => {
+    const points = [pt(0, 0, 0), pt(0.0001, 0, 10), pt(0.0002, 0, 20)];
+    expect(Number.isInteger(computeTrackDistance(points))).toBeTrue();
+  });
+});

shared/utils/geo.ts

@@ -0,0 +1,94 @@
+/**
+ * Shared, pure geo math used by both the client accumulator and the
+ * server-side distance recompute. Distances are in meters; the aggregate
+ * is stored as an Int (rounded) to avoid float drift in the database.
+ */
+
+/** Mean earth radius in meters (WGS-84 volumetric mean). */
+const EARTH_RADIUS_M = 6_371_000;
+
+/** Fixes reporting an accuracy worse than this are dropped (anchor unchanged). */
+export const MAX_ACCURACY_M = 50;
+/** A candidate implying a speed above this is a teleport (anchor unchanged). */
+export const MAX_SPEED_MPS = 7;
+/** Segments shorter than this are treated as stationary jitter (not added). */
+export const MIN_SEGMENT_M = 5;
+
+export type GeoPoint = {
+  lat: number;
+  lon: number;
+  accuracy?: number | null;
+  recordedAt: Date | string;
+};
+
+export type GeoCoord = Pick<GeoPoint, 'lat' | 'lon'>;
+
+/** Great-circle distance between two coordinates in meters. */
+export function haversine(a: GeoCoord, b: GeoCoord): number {
+  const toRad = (deg: number) => (deg * Math.PI) / 180;
+  const dLat = toRad(b.lat - a.lat);
+  const dLon = toRad(b.lon - a.lon);
+  const lat1 = toRad(a.lat);
+  const lat2 = toRad(b.lat);
+
+  const h =
+    Math.sin(dLat / 2) ** 2 +
+    Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLon / 2) ** 2;
+
+  return 2 * EARTH_RADIUS_M * Math.asin(Math.min(1, Math.sqrt(h)));
+}
+
+function toTime(recordedAt: Date | string): number {
+  return new Date(recordedAt).getTime();
+}
+
+/**
+ * Derive the walked distance (Int meters) from a set of raw fixes.
+ *
+ * Points are deduped (by `recordedAt` + coords) and sorted by `recordedAt`,
+ * then walked with an "anchor". For each candidate:
+ *  - accuracy worse than {@link MAX_ACCURACY_M} → dropped, anchor unchanged;
+ *  - implied speed above {@link MAX_SPEED_MPS} → teleport, anchor unchanged;
+ *  - segment shorter than {@link MIN_SEGMENT_M} → jitter, anchor unchanged;
+ *  - otherwise the segment is added and the anchor advances.
+ */
+export function computeTrackDistance(points: GeoPoint[]): number {
+  const seen = new Set<string>();
+  const normalized: (GeoPoint & { time: number })[] = [];
+
+  for (const p of points) {
+    const time = toTime(p.recordedAt);
+    if (Number.isNaN(time)) continue;
+    const key = `${time}|${p.lat}|${p.lon}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    normalized.push({ ...p, time });
+  }
+
+  normalized.sort((a, b) => a.time - b.time);
+
+  let total = 0;
+  let anchor: { lat: number; lon: number; time: number } | null = null;
+
+  for (const p of normalized) {
+    if (p.accuracy != null && p.accuracy > MAX_ACCURACY_M) continue;
+
+    if (anchor === null) {
+      anchor = { lat: p.lat, lon: p.lon, time: p.time };
+      continue;
+    }
+
+    const dtSeconds = (p.time - anchor.time) / 1000;
+    // Non-positive time delta is ambiguous (duplicate timestamps) → skip.
+    if (dtSeconds <= 0) continue;
+
+    const distance = haversine(anchor, p);
+    if (distance / dtSeconds > MAX_SPEED_MPS) continue; // teleport
+    if (distance < MIN_SEGMENT_M) continue; // stationary jitter
+
+    total += distance;
+    anchor = { lat: p.lat, lon: p.lon, time: p.time };
+  }
+
+  return Math.round(total);
+}