feat(trails): dados.gov.pt sync, v3 API, and deploy bootstrap

Sync Azores trail/POI open data via udata API and WFS, expose read endpoints,
enable the sao-miguel feature flag, and queue initial sync on deploy.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: hc-sousa

src/shared/management/commands/bootstrap_feed_syncs.py

@@ -11,11 +11,12 @@
 FEED_TASKS: tuple[tuple[str, str], ...] = (
     ('news', 'news.poll_sources'),
     ('seismic', 'seismic.sync_events'),
+    ('trails', 'trails.sync_open_data'),
 )
 
 
 class Command(BaseCommand):
-    help = 'Queue initial news and seismic feed sync tasks (runs after migrate on deploy).'
+    help = 'Queue initial news, seismic, and trails feed sync tasks (runs after migrate on deploy).'
 
     def handle(self, *args: object, **options: object) -> None:
         queued: list[str] = []
@@ -29,6 +30,10 @@ def handle(self, *args: object, **options: object) -> None:
                     from seismic.tasks import sync_events_task
 
                     sync_events_task.delay()
+                elif label == 'trails':
+                    from trails.tasks import sync_open_data_task
+
+                    sync_open_data_task.delay()
                 queued.append(task_name)
             except Exception:
                 logger.exception('bootstrap_feed_syncs failed to queue %s', task_name)

src/src/urls.py

@@ -18,6 +18,7 @@
     path('api/v3/transit/', include('transit.urls_v3')),
     path('api/v3/news/', include('news.urls_v3')),
     path('api/v3/seismic/', include('seismic.urls_v3')),
+    path('api/v3/trails/', include('trails.urls_v3')),
 ]
 
 if 'legal' in settings.INSTALLED_APPS:

src/tenancy/migrations/0007_enable_trails_feature_flag.py

@@ -0,0 +1,23 @@
+"""Enable trails module on default island."""
+
+from django.db import migrations
+
+
+def enable_trails(apps, schema_editor):
+    Island = apps.get_model('tenancy', 'Island')
+    for island in Island.objects.filter(key='sao-miguel'):
+        flags = dict(island.feature_flags or {})
+        if not flags.get('trails'):
+            flags['trails'] = True
+            island.feature_flags = flags
+            island.save(update_fields=['feature_flags'])
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ('tenancy', '0006_enable_seismic_feature_flag'),
+    ]
+
+    operations = [
+        migrations.RunPython(enable_trails, migrations.RunPython.noop),
+    ]

src/tenancy/tests/test_bootstrap.py

@@ -22,3 +22,19 @@ def test_enabled_modules_omits_seismic_when_flag_false(self):
         island.save(update_fields=['feature_flags'])
         modules = enabled_modules(island)
         self.assertNotIn('seismic', modules)
+
+    def test_enabled_modules_includes_trails_when_flag_set(self):
+        island = get_or_create_default_island()
+        island.feature_flags = {**island.feature_flags, 'trails': True, 'transit': True}
+        island.save(update_fields=['feature_flags'])
+        modules = enabled_modules(island)
+        self.assertIn('trails', modules)
+
+    def test_enabled_modules_omits_trails_when_flag_false(self):
+        island = get_or_create_default_island()
+        flags = dict(island.feature_flags or {})
+        flags['trails'] = False
+        island.feature_flags = flags
+        island.save(update_fields=['feature_flags'])
+        modules = enabled_modules(island)
+        self.assertNotIn('trails', modules)

src/trails/admin.py

@@ -18,6 +18,6 @@ class TrailAdmin(admin.ModelAdmin):
 
 @admin.register(POI)
 class POIAdmin(admin.ModelAdmin):
-    list_display = ('name', 'category', 'island')
+    list_display = ('name', 'category', 'source_ref', 'island')
     list_filter = ('island', 'category')
-    search_fields = ('name',)
+    search_fields = ('name', 'source_ref')

src/trails/api_v3.py

@@ -0,0 +1,76 @@
+"""Trails v3 API."""
+
+from __future__ import annotations
+
+from rest_framework import status
+from rest_framework.decorators import api_view, permission_classes
+from rest_framework.permissions import AllowAny
+from rest_framework.request import Request
+from rest_framework.response import Response
+
+from tenancy.services import for_island
+from trails.services import get_trail, list_pois, list_trails
+
+
+def _require_island(request: Request) -> Response | None:
+    if request.island is None:
+        return Response(
+            {'error': {'code': 'island_required', 'message': 'Island context required'}},
+            status=status.HTTP_400_BAD_REQUEST,
+        )
+    return None
+
+
+@api_view(['GET'])
+@permission_classes([AllowAny])
+def trails_list_view(request: Request) -> Response:
+    err = _require_island(request)
+    if err:
+        return err
+
+    difficulty = request.GET.get('difficulty', '').strip()
+    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)
+    return Response(payload)
+
+
+@api_view(['GET'])
+@permission_classes([AllowAny])
+def trails_pois_view(request: Request) -> Response:
+    err = _require_island(request)
+    if err:
+        return err
+
+    category = request.GET.get('category', '').strip()
+    limit_raw = request.GET.get('limit', '50').strip()
+    try:
+        limit = int(limit_raw)
+    except ValueError:
+        limit = 50
+
+    with for_island(request.island):
+        payload = list_pois(category=category, limit=limit)
+    return Response(payload)
+
+
+@api_view(['GET'])
+@permission_classes([AllowAny])
+def trail_detail_view(request: Request, trail_id: int) -> Response:
+    err = _require_island(request)
+    if err:
+        return err
+
+    with for_island(request.island):
+        payload = get_trail(trail_id)
+    if payload is None:
+        return Response(
+            {'error': {'code': 'not_found', 'message': 'Trail not found'}},
+            status=status.HTTP_404_NOT_FOUND,
+        )
+    return Response(payload)

src/trails/migrations/0002_poi_source_ref.py

@@ -0,0 +1,34 @@
+"""Add source_ref to POI for idempotent open-data sync."""
+
+from django.db import migrations, models
+
+
+def backfill_poi_source_refs(apps, schema_editor):
+    POI = apps.get_model('trails', 'POI')
+    for poi in POI.objects.filter(source_ref__isnull=True):
+        poi.source_ref = f'legacy-{poi.pk}'
+        poi.save(update_fields=['source_ref'])
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ('trails', '0001_initial'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='poi',
+            name='source_ref',
+            field=models.CharField(max_length=128, null=True),
+        ),
+        migrations.RunPython(backfill_poi_source_refs, migrations.RunPython.noop),
+        migrations.AlterField(
+            model_name='poi',
+            name='source_ref',
+            field=models.CharField(max_length=128),
+        ),
+        migrations.AlterUniqueTogether(
+            name='poi',
+            unique_together={('island', 'source_ref')},
+        ),
+    ]

src/trails/migrations/0003_periodic_task_sync_open_data.py

@@ -0,0 +1,43 @@
+"""Register daily trails open-data sync task."""
+
+from django.db import migrations
+
+
+def _daily_schedule(apps):
+    CrontabSchedule = apps.get_model('django_celery_beat', 'CrontabSchedule')
+    schedule, _ = CrontabSchedule.objects.get_or_create(
+        minute='0',
+        hour='3',
+        day_of_week='*',
+        day_of_month='*',
+        month_of_year='*',
+        defaults={'timezone': 'Atlantic/Azores'},
+    )
+    if schedule.timezone != 'Atlantic/Azores':
+        schedule.timezone = 'Atlantic/Azores'
+        schedule.save(update_fields=['timezone'])
+    return schedule
+
+
+def register_sync_task(apps, schema_editor):
+    PeriodicTask = apps.get_model('django_celery_beat', 'PeriodicTask')
+    daily = _daily_schedule(apps)
+    PeriodicTask.objects.update_or_create(
+        name='trails.sync_open_data',
+        defaults={
+            'task': 'trails.sync_open_data',
+            'crontab': daily,
+            'enabled': True,
+        },
+    )
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ('trails', '0002_poi_source_ref'),
+        ('django_celery_beat', '__latest__'),
+    ]
+
+    operations = [
+        migrations.RunPython(register_sync_task, migrations.RunPython.noop),
+    ]

src/trails/models.py

@@ -36,13 +36,15 @@ def __str__(self) -> str:
 
 
 class POI(TenantScopedModel):
+    source_ref = models.CharField(max_length=128)
     name = models.CharField(max_length=200)
     category = models.CharField(max_length=64, blank=True, default='')
     latitude = models.FloatField()
     longitude = models.FloatField()
 
     class Meta:
         ordering = ['name']
+        unique_together = [('island', 'source_ref')]
         verbose_name = 'POI'
         verbose_name_plural = 'POIs'