feat(trails): enrich from Visit Azores only and drop azores-hub

hc-sousa · cursoragent · hc-sousa · commit f2100de980e3 · 2026-06-02T14:43:19.000Z
Extend Trail with shape, duration, bilingual descriptions, download URLs,
waypoints, and start coords parsed from trails.visitazores.com + GPX.
Expose enriched v3 list/detail filters and nearest bus stop; remove all
azores-hub.net feed merging from the sync pipeline.

Co-authored-by: Cursor &lt;cursoragent@cursor.com&gt;
diff --git a/src/trails/api_v3.py b/src/trails/api_v3.py
@@ -29,14 +29,42 @@ def trails_list_view(request: Request) -> Response:
         return err
 
     difficulty = request.GET.get('difficulty', '').strip()
+    shape = request.GET.get('shape', '').strip()
+    min_length = None
+    max_length = None
+    min_length_raw = request.GET.get('min_length', '').strip()
+    max_length_raw = request.GET.get('max_length', '').strip()
+    if min_length_raw:
+        try:
+            min_length = float(min_length_raw)
+        except ValueError:
+            return Response(
+                {'error': {'code': 'invalid_min_length', 'message': 'min_length must be a number'}},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+    if max_length_raw:
+        try:
+            max_length = float(max_length_raw)
+        except ValueError:
+            return Response(
+                {'error': {'code': 'invalid_max_length', 'message': 'max_length must be a number'}},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
     limit_raw = request.GET.get('limit', '50').strip()
     try:
         limit = int(limit_raw)
     except ValueError:
         limit = 50
 
     with for_island(request.island):
-        payload = list_trails(difficulty=difficulty, limit=limit)
+        payload = list_trails(
+            difficulty=difficulty,
+            shape=shape,
+            min_length=min_length,
+            max_length=max_length,
+            limit=limit,
+        )
     return Response(payload)
 
 
diff --git a/src/trails/migrations/0004_trail_enrichment.py b/src/trails/migrations/0004_trail_enrichment.py
@@ -0,0 +1,67 @@
+"""Trail enrichment fields from Visit Azores."""
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ('trails', '0003_periodic_task_sync_open_data'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='trail',
+            name='shape',
+            field=models.CharField(blank=True, default='', max_length=32),
+        ),
+        migrations.AddField(
+            model_name='trail',
+            name='duration_min',
+            field=models.PositiveIntegerField(blank=True, null=True),
+        ),
+        migrations.AddField(
+            model_name='trail',
+            name='description_pt',
+            field=models.TextField(blank=True, default=''),
+        ),
+        migrations.AddField(
+            model_name='trail',
+            name='description_en',
+            field=models.TextField(blank=True, default=''),
+        ),
+        migrations.AddField(
+            model_name='trail',
+            name='gpx_url',
+            field=models.CharField(blank=True, default='', max_length=500),
+        ),
+        migrations.AddField(
+            model_name='trail',
+            name='kml_url',
+            field=models.CharField(blank=True, default='', max_length=500),
+        ),
+        migrations.AddField(
+            model_name='trail',
+            name='map_image_url',
+            field=models.CharField(blank=True, default='', max_length=500),
+        ),
+        migrations.AddField(
+            model_name='trail',
+            name='leaflet_url',
+            field=models.CharField(blank=True, default='', max_length=500),
+        ),
+        migrations.AddField(
+            model_name='trail',
+            name='start_lat',
+            field=models.FloatField(blank=True, null=True),
+        ),
+        migrations.AddField(
+            model_name='trail',
+            name='start_lon',
+            field=models.FloatField(blank=True, null=True),
+        ),
+        migrations.AddField(
+            model_name='trail',
+            name='waypoints',
+            field=models.JSONField(blank=True, default=list),
+        ),
+    ]
diff --git a/src/trails/models.py b/src/trails/models.py
@@ -12,6 +12,17 @@ class Trail(TenantScopedModel):
     name = models.CharField(max_length=200)
     difficulty = models.CharField(max_length=32, blank=True, default='')
     distance_km = models.FloatField(null=True, blank=True)
+    shape = models.CharField(max_length=32, blank=True, default='')
+    duration_min = models.PositiveIntegerField(null=True, blank=True)
+    description_pt = models.TextField(blank=True, default='')
+    description_en = models.TextField(blank=True, default='')
+    gpx_url = models.CharField(max_length=500, blank=True, default='')
+    kml_url = models.CharField(max_length=500, blank=True, default='')
+    map_image_url = models.CharField(max_length=500, blank=True, default='')
+    leaflet_url = models.CharField(max_length=500, blank=True, default='')
+    start_lat = models.FloatField(null=True, blank=True)
+    start_lon = models.FloatField(null=True, blank=True)
+    waypoints = models.JSONField(default=list, blank=True)
     geojson = models.JSONField(default=dict, blank=True)
 
     class Meta:
diff --git a/src/trails/services.py b/src/trails/services.py
@@ -529,12 +529,39 @@ def sync_all_open_data(*, island_key: str | None = None) -> dict[str, int]:
     return totals
 
 
+def nearest_stop(island: Island, lat: float | None, lng: float | None) -> dict[str, Any] | None:
+    if lat is None or lng is None:
+        return None
+
+    from transit.models import Stop
+
+    best: Stop | None = None
+    best_dist = float('inf')
+    for stop in Stop.objects.filter(island=island):
+        dist = _haversine_km(lat, lng, stop.latitude, stop.longitude)
+        if dist < best_dist:
+            best_dist = dist
+            best = stop
+
+    if best is None:
+        return None
+
+    return {
+        'name': best.name,
+        'distanceKm': round(best_dist, 2),
+        'lat': best.latitude,
+        'lng': best.longitude,
+    }
+
+
 def serialize_trail_summary(trail: Trail) -> dict[str, Any]:
     return {
         'id': trail.id,
         'name': trail.name,
         'difficulty': trail.difficulty,
         'distanceKm': trail.distance_km,
+        'shape': trail.shape,
+        'durationMin': trail.duration_min,
     }
 
 
@@ -548,8 +575,19 @@ def serialize_trail_detail(trail: Trail) -> dict[str, Any]:
         }
         for stage in trail.stages.order_by('sequence')
     ]
+    nearest = nearest_stop(trail.island, trail.start_lat, trail.start_lon)
     return {
         **serialize_trail_summary(trail),
+        'descriptionPt': trail.description_pt,
+        'descriptionEn': trail.description_en,
+        'gpxUrl': trail.gpx_url,
+        'kmlUrl': trail.kml_url,
+        'mapImageUrl': trail.map_image_url,
+        'leafletUrl': trail.leaflet_url,
+        'startLat': trail.start_lat,
+        'startLng': trail.start_lon,
+        'waypoints': trail.waypoints or [],
+        'nearestStop': nearest,
         'geojson': trail.geojson,
         'stages': stages,
         'attribution': trails_attribution(),
@@ -575,10 +613,23 @@ def trails_attribution() -> str:
         return OPEN_DATA_ATTRIBUTION
 
 
-def list_trails(*, difficulty: str = '', limit: int = 50) -> dict[str, Any]:
+def list_trails(
+    *,
+    difficulty: str = '',
+    shape: str = '',
+    min_length: float | None = None,
+    max_length: float | None = None,
+    limit: int = 50,
+) -> dict[str, Any]:
     qs = Trail.objects.order_by('name')
     if difficulty:
         qs = qs.filter(difficulty__iexact=difficulty.strip())
+    if shape:
+        qs = qs.filter(shape__iexact=shape.strip())
+    if min_length is not None:
+        qs = qs.filter(distance_km__gte=min_length)
+    if max_length is not None:
+        qs = qs.filter(distance_km__lte=max_length)
     limit = max(1, min(limit, 100))
     return {
         'trails': [serialize_trail_summary(trail) for trail in qs[:limit]],
diff --git a/src/trails/tests/test_api_v3.py b/src/trails/tests/test_api_v3.py
@@ -4,6 +4,7 @@
 from rest_framework.test import APIClient
 
 from trails.models import POI, Trail
+from transit.models import Stop
 from tenancy.services import get_or_create_default_island
 
 
@@ -24,6 +25,14 @@ def setUp(self):
             name='Alpha Trail',
             difficulty='easy',
             distance_km=3.2,
+            shape='circular',
+            duration_min=90,
+            description_en='Alpha EN',
+            description_pt='Alpha PT',
+            gpx_url='https://example.test/a.gpx',
+            start_lat=37.78,
+            start_lon=-25.50,
+            waypoints=[{'name': 'Start', 'lat': 37.78, 'lng': -25.50}],
             geojson={'type': 'LineString', 'coordinates': [[-25.5, 37.78], [-25.49, 37.79]]},
         )
         self.trail_b = Trail.objects.create(
@@ -32,6 +41,8 @@ def setUp(self):
             name='Beta Trail',
             difficulty='hard',
             distance_km=8.0,
+            shape='linear',
+            duration_min=240,
             geojson={'type': 'LineString', 'coordinates': [[-25.51, 37.77], [-25.48, 37.80]]},
         )
         self.poi = POI.objects.create(
@@ -42,6 +53,13 @@ def setUp(self):
             latitude=37.78,
             longitude=-25.50,
         )
+        Stop.objects.create(
+            island=self.island,
+            name='Ponta Delgada',
+            cleaned_name='ponta delgada',
+            latitude=37.781,
+            longitude=-25.501,
+        )
 
     def test_list_trails_ordered_by_name(self):
         response = self.client.get('/api/v3/trails/', **self.headers)
@@ -60,13 +78,38 @@ def test_list_trails_difficulty_filter(self):
         self.assertEqual(len(trails), 1)
         self.assertEqual(trails[0]['id'], self.trail_b.id)
 
-    def test_detail_includes_geojson(self):
+    def test_list_trails_shape_and_length_filters(self):
+        response = self.client.get('/api/v3/trails/?shape=circular&max_length=5', **self.headers)
+        self.assertEqual(response.status_code, 200)
+        trails = response.json()['trails']
+        self.assertEqual(len(trails), 1)
+        self.assertEqual(trails[0]['id'], self.trail_a.id)
+        self.assertEqual(trails[0]['shape'], 'circular')
+        self.assertEqual(trails[0]['durationMin'], 90)
+
+    def test_list_trails_invalid_length_returns_400(self):
+        response = self.client.get('/api/v3/trails/?min_length=abc', **self.headers)
+        self.assertEqual(response.status_code, 400)
+
+    def test_detail_includes_enriched_fields(self):
         response = self.client.get(f'/api/v3/trails/{self.trail_a.id}', **self.headers)
         self.assertEqual(response.status_code, 200)
         body = response.json()
         self.assertEqual(body['geojson']['type'], 'LineString')
         self.assertEqual(body['stages'], [])
         self.assertIn('attribution', body)
+        self.assertEqual(body['descriptionEn'], 'Alpha EN')
+        self.assertEqual(body['descriptionPt'], 'Alpha PT')
+        self.assertEqual(body['gpxUrl'], 'https://example.test/a.gpx')
+        self.assertEqual(body['startLat'], 37.78)
+        self.assertEqual(len(body['waypoints']), 1)
+        self.assertEqual(body['nearestStop']['name'], 'Ponta Delgada')
+
+    def test_detail_includes_geojson(self):
+        response = self.client.get(f'/api/v3/trails/{self.trail_a.id}', **self.headers)
+        self.assertEqual(response.status_code, 200)
+        body = response.json()
+        self.assertEqual(body['geojson']['type'], 'LineString')
 
     def test_detail_not_found(self):
         response = self.client.get('/api/v3/trails/99999', **self.headers)
diff --git a/src/trails/tests/test_services.py b/src/trails/tests/test_services.py
@@ -7,12 +7,14 @@
 from trails.models import POI, Trail
 from trails.services import (
     feature_in_island,
+    nearest_stop,
     parse_poi_feature,
     parse_trail_feature,
     sync_open_data_for_island,
     sync_pois_for_island,
     sync_trails_for_island,
 )
+from transit.models import Stop
 from tenancy.services import get_or_create_default_island
 
 SAMPLE_TRAIL_COLLECTION = {
@@ -134,3 +136,26 @@ def test_fetch_dataset_geojson_http_error(self, mock_dataset):
             from trails.services import fetch_dataset_geojson
 
             fetch_dataset_geojson('test-dataset')
+
+    def test_nearest_stop_returns_closest(self):
+        Stop.objects.create(
+            island=self.island,
+            name='Far Stop',
+            cleaned_name='far stop',
+            latitude=37.70,
+            longitude=-25.60,
+        )
+        near = Stop.objects.create(
+            island=self.island,
+            name='Near Stop',
+            cleaned_name='near stop',
+            latitude=37.781,
+            longitude=-25.501,
+        )
+        result = nearest_stop(self.island, 37.78, -25.50)
+        assert result is not None
+        self.assertEqual(result['name'], near.name)
+        self.assertLess(result['distanceKm'], 5)
+
+    def test_nearest_stop_none_without_coords(self):
+        self.assertIsNone(nearest_stop(self.island, None, -25.5))
diff --git a/src/trails/tests/test_visitazores_sync.py b/src/trails/tests/test_visitazores_sync.py
diff --git a/src/trails/visitazores_sync.py b/src/trails/visitazores_sync.py
