v7.4.0 — Route Plan with Milestones

New capability: existing saved routes can now generate a timed field
plan with milestones, sunrise/sunset overlay, and resupply candidates.

POST /api/maps/route-plan takes {route_id, pace_kmh, depart_iso,
corridor_km, people} and returns:

  - Timed milestones at every waypoint in the chain — cumulative
    distance + ETA ("At WP-Bravo by 14:30")
  - Sun overlay — sunrise / sunset for the departure + arrival days
    (using the simplified NOAA algorithm from tasks.py) so the plan
    shows which milestones fall in darkness
  - Corridor search — finds other waypoints within `corridor_km` of
    any route waypoint and surfaces them as resupply/shelter options
  - Per-person water + calorie estimate (3 L/day, 3500 kcal/day —
    same reference numbers used by the Kit Builder)

UI: new "Plan" button on each saved route card opens a modal with
pace/corridor/people/departure inputs. Results page shows a 5-stat
header (km, duration, ascent, water, kcal), the sun overlay, a
timeline of milestones with dark-window highlighting, and a nearby-
waypoint corridor list. Mobile-responsive.

Empty state: if no other waypoints fall in the corridor, UI prompts
user to widen the corridor or add more waypoints rather than showing
an empty div.

7 new tests: happy path (NYC→Philly distance check), single-waypoint
rejection, 404 on unknown route, pace affects duration, corridor
surfaces nearby, pace clamp on zero-input.

Tests: 861 passed (was 854).

Author: FOSSFOREVER

README.md

@@ -1,7 +1,7 @@
 <div align="center">
 <img src="nomad-mark.png" width="140" height="140"/>
 
-# NOMAD Field Desk v7.3.0
+# NOMAD Field Desk v7.4.0
 
 ### Your Personal Intelligence & Preparedness Command Center
 

config.py

@@ -36,7 +36,7 @@ class Config:
     """Central configuration with environment variable overrides."""
 
     # --- App Identity ---
-    VERSION = os.environ.get('NOMAD_VERSION', '7.3.0')
+    VERSION = os.environ.get('NOMAD_VERSION', '7.4.0')
 
     # --- Upload / Content Limits ---
     MAX_CONTENT_LENGTH = int(os.environ.get('NOMAD_MAX_CONTENT_LENGTH', 100 * 1024 * 1024))  # 100 MB

installer.iss

@@ -1,8 +1,8 @@
 ; NOMAD Field Desk Inno Setup Script
-; AppVersion: 7.3.0
+; AppVersion: 7.4.0
 
 #define MyAppName "NOMAD Field Desk"
-#define MyAppVersion "7.3.0"
+#define MyAppVersion "7.4.0"
 #define MyAppPublisher "SysAdminDoc"
 #define MyAppURL "https://github.com/SysAdminDoc/project-nomad-desktop"
 #define MyAppSupportURL "https://github.com/SysAdminDoc/project-nomad-desktop/issues"

tests/test_route_plan.py

@@ -0,0 +1,101 @@
+"""Tests for the Route Plan endpoint (v7.4.0).
+
+Covers the happy path, error paths, pace scaling, and corridor search.
+"""
+
+
+def _create_route_with_waypoints(client, coords, name='Test Route'):
+    """Create waypoints, then a route that references them in order.
+    Returns (route_id, waypoint_ids)."""
+    wp_ids = []
+    for i, (lat, lng) in enumerate(coords):
+        resp = client.post('/api/waypoints', json={
+            'name': f'WP-{i}', 'lat': lat, 'lng': lng,
+            'category': 'other', 'elevation_m': 100 + i * 10,
+        })
+        wp_ids.append(resp.get_json()['id'])
+    import json
+    resp = client.post('/api/maps/routes', json={
+        'name': name,
+        'waypoint_ids': json.dumps(wp_ids),
+    })
+    return resp.get_json()['id'], wp_ids
+
+
+class TestRoutePlan:
+    def test_missing_route_id(self, client):
+        resp = client.post('/api/maps/route-plan', json={})
+        assert resp.status_code == 400
+
+    def test_unknown_route(self, client):
+        resp = client.post('/api/maps/route-plan', json={'route_id': 99999})
+        assert resp.status_code == 404
+
+    def test_single_waypoint_rejected(self, client):
+        """A route with fewer than 2 waypoints can't be planned."""
+        rid, _ = _create_route_with_waypoints(client, [(40.0, -74.0)])
+        resp = client.post('/api/maps/route-plan', json={'route_id': rid})
+        assert resp.status_code == 400
+
+    def test_happy_path(self, client):
+        # NYC → Philadelphia approx 130 km
+        rid, _ = _create_route_with_waypoints(client, [
+            (40.7128, -74.0060),
+            (39.9526, -75.1652),
+        ])
+        resp = client.post('/api/maps/route-plan', json={
+            'route_id': rid, 'pace_kmh': 60, 'people': 2,
+        })
+        assert resp.status_code == 200
+        data = resp.get_json()
+        assert data['route_id'] == rid
+        assert len(data['milestones']) == 2
+        assert data['totals']['distance_km'] > 100
+        assert data['totals']['distance_km'] < 200
+        # 2 people → 2× water
+        assert data['totals']['water_l_total'] > 0
+        # Sun data present
+        assert len(data['sun']) >= 1
+
+    def test_pace_affects_duration(self, client):
+        rid, _ = _create_route_with_waypoints(client, [
+            (40.0, -74.0), (41.0, -74.0),  # ~111 km north
+        ])
+        slow = client.post('/api/maps/route-plan', json={
+            'route_id': rid, 'pace_kmh': 5,
+        }).get_json()
+        fast = client.post('/api/maps/route-plan', json={
+            'route_id': rid, 'pace_kmh': 50,
+        }).get_json()
+        # Slower pace → longer duration
+        assert slow['totals']['duration_hours'] > fast['totals']['duration_hours']
+
+    def test_corridor_surfaces_nearby_waypoints(self, client):
+        rid, _ = _create_route_with_waypoints(client, [
+            (40.0, -74.0), (41.0, -74.0),
+        ])
+        # Create an off-route waypoint close to the start waypoint.
+        # The corridor search measures from route waypoints (not segment
+        # midpoints) so the candidate should be within the corridor of at
+        # least one waypoint.
+        client.post('/api/waypoints', json={
+            'name': 'Resupply Alpha', 'lat': 40.05, 'lng': -74.05,
+            'category': 'supply',
+        })
+        resp = client.post('/api/maps/route-plan', json={
+            'route_id': rid, 'corridor_km': 20,
+        })
+        data = resp.get_json()
+        names = [n['name'] for n in data.get('nearby_waypoints', [])]
+        assert 'Resupply Alpha' in names
+
+    def test_pace_clamped(self, client):
+        rid, _ = _create_route_with_waypoints(client, [
+            (40.0, -74.0), (40.1, -74.0),
+        ])
+        # Zero pace → clamped to 0.5 km/h minimum (not div/0)
+        resp = client.post('/api/maps/route-plan', json={
+            'route_id': rid, 'pace_kmh': 0,
+        })
+        assert resp.status_code == 200
+        assert resp.get_json()['params']['pace_kmh'] >= 0.5

web/blueprints/maps.py

@@ -831,6 +831,254 @@ def api_elevation_profile(route_id):
             'total_descent': round(total_descent, 1),
             'total_distance_m': round(total_dist),
         })
+
+
+# ─── Route Plan with Milestones (v7.4.0) ───────────────────────────
+#
+# Takes an existing saved route (ordered waypoint chain) + a pace + a
+# departure time, and returns:
+#   - Timed milestones at every waypoint ("you'll be at X by 14:30")
+#   - Sunrise / sunset along the way so the planner can see if they're
+#     moving in darkness on any leg
+#   - Resupply / shelter candidates from other waypoints within a
+#     configurable corridor around each leg (doesn't have to be
+#     on the route — just nearby)
+#   - Per-person water + calorie estimate for the trip
+#
+# This is deterministic math on the existing elevation_profile pipeline.
+# No external services, no routing engine — we just walk the waypoint
+# chain the user already built.
+
+def _haversine_km(lat1, lng1, lat2, lng2):
+    """Great-circle distance in km."""
+    R = 6371.0
+    p1, p2 = math.radians(lat1), math.radians(lat2)
+    dlat = math.radians(lat2 - lat1)
+    dlng = math.radians(lng2 - lng1)
+    a = math.sin(dlat / 2) ** 2 + math.cos(p1) * math.cos(p2) * math.sin(dlng / 2) ** 2
+    return 2 * R * math.asin(math.sqrt(a))
+
+
+def _sun_times_for(lat, lng, when):
+    """Compute sunrise/sunset in UTC ISO-8601 for a given date + coord.
+
+    Simplified from tasks.py:_sun_times — uses the same NOAA algorithm
+    but scoped to one day so the import graph stays trivial. Returns
+    ``{sunrise_iso, sunset_iso}``, or ``None`` for polar day/night.
+    """
+    from datetime import datetime, timezone, timedelta
+    # Convert date to Julian day (NOAA formula)
+    y, m, d = when.year, when.month, when.day
+    if m <= 2:
+        y, m = y - 1, m + 12
+    a = y // 100
+    b = 2 - a + a // 4
+    jd = int(365.25 * (y + 4716)) + int(30.6001 * (m + 1)) + d + b - 1524.5
+
+    def _zenith(rising):
+        # Official zenith for sunrise/sunset = 90° 50'
+        zen = 90.833
+        lng_hr = lng / 15.0
+        t = jd + ((6 if rising else 18) - lng_hr) / 24
+        M = (0.9856 * t) - 3.289
+        L = M + (1.916 * math.sin(math.radians(M))) + (0.020 * math.sin(math.radians(2 * M))) + 282.634
+        L = L % 360
+        RA = math.degrees(math.atan(0.91764 * math.tan(math.radians(L)))) % 360
+        Lq = math.floor(L / 90) * 90
+        RAq = math.floor(RA / 90) * 90
+        RA = (RA + (Lq - RAq)) / 15
+        sinDec = 0.39782 * math.sin(math.radians(L))
+        cosDec = math.cos(math.asin(sinDec))
+        try:
+            cosH = (math.cos(math.radians(zen)) - (sinDec * math.sin(math.radians(lat)))) / (cosDec * math.cos(math.radians(lat)))
+        except ZeroDivisionError:
+            return None
+        if cosH > 1 or cosH < -1:
+            return None  # Polar day/night
+        if rising:
+            H = 360 - math.degrees(math.acos(cosH))
+        else:
+            H = math.degrees(math.acos(cosH))
+        H = H / 15
+        T = H + RA - (0.06571 * t) - 6.622
+        UT = (T - lng_hr) % 24
+        return UT
+
+    def _ut_to_iso(ut, day):
+        if ut is None:
+            return None
+        hours = int(ut)
+        minutes = int((ut - hours) * 60)
+        minutes = max(0, min(59, minutes))
+        base = datetime(day.year, day.month, day.day, 0, 0, 0, tzinfo=timezone.utc)
+        return (base + timedelta(hours=hours, minutes=minutes)).isoformat()
+
+    return {
+        'sunrise_iso': _ut_to_iso(_zenith(True), when),
+        'sunset_iso':  _ut_to_iso(_zenith(False), when),
+    }
+
+
+@maps_bp.route('/api/maps/route-plan', methods=['POST'])
+def api_maps_route_plan():
+    """Return a planned schedule for an existing route.
+
+    Body:
+        {route_id, pace_kmh, depart_iso, corridor_km, people}
+
+    All fields optional except ``route_id``. Defaults:
+        pace_kmh=5 (walking), depart_iso=now UTC, corridor_km=5, people=1
+    """
+    from datetime import datetime, timezone, timedelta
+
+    data = request.get_json() or {}
+    route_id = data.get('route_id')
+    if not isinstance(route_id, int):
+        try: route_id = int(route_id)
+        except (TypeError, ValueError):
+            return jsonify({'error': 'route_id required'}), 400
+
+    try:
+        pace_kmh = float(data.get('pace_kmh') or 5.0)
+    except (TypeError, ValueError):
+        pace_kmh = 5.0
+    pace_kmh = max(0.5, min(pace_kmh, 120.0))  # walking pace floor, vehicle ceiling
+
+    try:
+        corridor_km = float(data.get('corridor_km') or 5.0)
+    except (TypeError, ValueError):
+        corridor_km = 5.0
+    corridor_km = max(0.5, min(corridor_km, 50.0))
+
+    try:
+        people = max(1, min(int(data.get('people') or 1), 50))
+    except (TypeError, ValueError):
+        people = 1
+
+    depart_iso = data.get('depart_iso')
+    try:
+        depart = datetime.fromisoformat((depart_iso or '').replace('Z', '+00:00'))
+        if depart.tzinfo is None:
+            depart = depart.replace(tzinfo=timezone.utc)
+    except (TypeError, ValueError):
+        depart = datetime.now(timezone.utc)
+
+    with db_session() as db:
+        route = db.execute('SELECT * FROM map_routes WHERE id = ?', (route_id,)).fetchone()
+        if not route:
+            return jsonify({'error': 'Route not found'}), 404
+        wp_ids = _safe_id_list(route['waypoint_ids'])
+        if len(wp_ids) < 2:
+            return jsonify({'error': 'Route needs at least 2 waypoints'}), 400
+
+        placeholders = ','.join('?' for _ in wp_ids)
+        order_case = ' '.join(f'WHEN id = ? THEN {i}' for i, _ in enumerate(wp_ids))
+        waypoints = db.execute(
+            f'SELECT id, name, lat, lng, elevation_m, category FROM waypoints '
+            f'WHERE id IN ({placeholders}) ORDER BY CASE {order_case} END',
+            wp_ids + wp_ids,
+        ).fetchall()
+        waypoints = [dict(w) for w in waypoints]
+
+        # All other waypoints (candidates for resupply/shelter corridor)
+        all_wps = db.execute(
+            'SELECT id, name, lat, lng, category FROM waypoints LIMIT 2000'
+        ).fetchall()
+        route_id_set = set(wp_ids)
+        candidates = [dict(w) for w in all_wps if w['id'] not in route_id_set]
+
+    # Walk the chain — compute cumulative distance, ETA, leg-level info
+    milestones = []
+    cumulative_km = 0.0
+    cumulative_ascent_m = 0.0
+    prev = None
+    for wp in waypoints:
+        if prev is not None:
+            seg_km = _haversine_km(prev['lat'], prev['lng'], wp['lat'], wp['lng'])
+            cumulative_km += seg_km
+            delta = (wp.get('elevation_m') or 0) - (prev.get('elevation_m') or 0)
+            if delta > 0:
+                cumulative_ascent_m += delta
+        eta = depart + timedelta(hours=(cumulative_km / pace_kmh))
+        milestones.append({
+            'waypoint_id': wp['id'],
+            'name': wp['name'],
+            'lat': wp['lat'],
+            'lng': wp['lng'],
+            'category': wp.get('category') or '',
+            'cumulative_km': round(cumulative_km, 2),
+            'eta_iso': eta.isoformat(),
+            'eta_hours_in': round((eta - depart).total_seconds() / 3600, 2),
+        })
+        prev = wp
+
+    total_km = round(cumulative_km, 2)
+    total_hours = round(cumulative_km / pace_kmh, 2)
+
+    # Find nearby candidates — within corridor_km of ANY waypoint on the route
+    nearby = []
+    for cand in candidates:
+        best_km = None
+        best_wp = None
+        for wp in waypoints:
+            d = _haversine_km(wp['lat'], wp['lng'], cand['lat'], cand['lng'])
+            if best_km is None or d < best_km:
+                best_km = d
+                best_wp = wp
+        if best_km is not None and best_km <= corridor_km:
+            nearby.append({
+                'waypoint_id': cand['id'],
+                'name': cand['name'],
+                'category': cand.get('category') or '',
+                'lat': cand['lat'],
+                'lng': cand['lng'],
+                'nearest_route_wp': best_wp['name'] if best_wp else '',
+                'distance_from_route_km': round(best_km, 2),
+            })
+    nearby.sort(key=lambda c: c['distance_from_route_km'])
+    nearby = nearby[:30]
+
+    # Sunrise / sunset overlay — use the start coord on the depart date,
+    # and the end coord on the arrival date. For most routes these are
+    # the same day; two days of sun data is enough signal.
+    sun = []
+    days_spanned = set([depart.date()])
+    arrive_at = depart + timedelta(hours=total_hours)
+    days_spanned.add(arrive_at.date())
+    start_lat, start_lng = waypoints[0]['lat'], waypoints[0]['lng']
+    for day in sorted(days_spanned):
+        st = _sun_times_for(start_lat, start_lng, datetime.combine(day, datetime.min.time()))
+        sun.append({'date': day.isoformat(), 'lat': start_lat, 'lng': start_lng, **st})
+
+    # Resource burn estimate — reuse the Kit Builder water model without
+    # importing the blueprint (keeps maps → kit_builder coupling clean).
+    # Assume temperate + bug-out for pace-based movement.
+    water_l_per_person = 3.0 * max(1.0, total_hours / 24)
+    kcal_per_person = 3500 * max(1.0, total_hours / 24)
+
+    return jsonify({
+        'route_id': route_id,
+        'route_name': route['name'],
+        'params': {
+            'pace_kmh': pace_kmh,
+            'corridor_km': corridor_km,
+            'people': people,
+            'depart_iso': depart.isoformat(),
+        },
+        'milestones': milestones,
+        'totals': {
+            'distance_km': total_km,
+            'duration_hours': total_hours,
+            'ascent_m': round(cumulative_ascent_m, 0),
+            'water_l_total': round(water_l_per_person * people, 1),
+            'kcal_total': round(kcal_per_person * people, 0),
+            'arrive_iso': arrive_at.isoformat(),
+        },
+        'nearby_waypoints': nearby,
+        'sun': sun,
+    })
+
+
 @maps_bp.route('/api/maps/annotations')
 def api_map_annotations_list():
     try: