first commit

backend/apps/sync/apps.py

@@ -0,0 +1,8 @@
+from django.apps import AppConfig
+
+
+class SyncConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "apps.sync"
+    label = "sync"
+    verbose_name = "City sync registry"

backend/apps/sync/migrations/0001_initial.py

@@ -0,0 +1,52 @@
+# Generated manually for HQ city registry scaffold
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = []
+
+    operations = [
+        migrations.CreateModel(
+            name="CitySite",
+            fields=[
+                ("city_site_id", models.BigAutoField(primary_key=True, serialize=False)),
+                (
+                    "code",
+                    models.SlugField(
+                        help_text="Stable id, e.g. sukawarna",
+                        max_length=64,
+                        unique=True,
+                    ),
+                ),
+                ("name", models.CharField(max_length=120)),
+                (
+                    "api_base_url",
+                    models.URLField(
+                        help_text="City API root including /api/v1, e.g. https://site.example/api/v1",
+                        max_length=255,
+                    ),
+                ),
+                (
+                    "api_key",
+                    models.CharField(
+                        blank=True,
+                        help_text="X-API-Key for pulling from the city API (keep server-side only)",
+                        max_length=255,
+                    ),
+                ),
+                ("is_active", models.BooleanField(default=True)),
+                ("last_synced_at", models.DateTimeField(blank=True, null=True)),
+                ("last_sync_status", models.CharField(blank=True, default="", max_length=32)),
+                ("last_sync_message", models.TextField(blank=True, default="")),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+            ],
+            options={
+                "db_table": "city_sites",
+                "ordering": ["name"],
+            },
+        ),
+    ]

backend/apps/sync/migrations/0002_citysite_registered_by.py

@@ -0,0 +1,27 @@
+# Generated for city site ownership
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+        ("sync", "0001_initial"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="citysite",
+            name="registered_by",
+            field=models.ForeignKey(
+                blank=True,
+                help_text="GM / GM Admin who added this city dashboard URL",
+                null=True,
+                on_delete=django.db.models.deletion.SET_NULL,
+                related_name="registered_city_sites",
+                to=settings.AUTH_USER_MODEL,
+            ),
+        ),
+    ]

backend/apps/sync/models.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from django.conf import settings
+from django.db import models
+
+
+class CitySite(models.Model):
+    """
+    Registry of a city dashboard-cpsp deployment that HQ can mirror from.
+
+    Outbound API key is stored here for local/dev scaffolding. Prefer a secret
+    manager or encrypted field before production.
+    """
+
+    city_site_id = models.BigAutoField(primary_key=True)
+    code = models.SlugField(max_length=64, unique=True, help_text="Stable id, e.g. sukawarna")
+    name = models.CharField(max_length=120)
+    api_base_url = models.URLField(
+        max_length=255,
+        help_text="City API root including /api/v1, e.g. https://site.example/api/v1",
+    )
+    api_key = models.CharField(
+        max_length=255,
+        blank=True,
+        help_text="X-API-Key for pulling from the city API (keep server-side only)",
+    )
+    registered_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        null=True,
+        blank=True,
+        on_delete=models.SET_NULL,
+        related_name="registered_city_sites",
+        help_text="GM / GM Admin who added this city dashboard URL",
+    )
+    is_active = models.BooleanField(default=True)
+    last_synced_at = models.DateTimeField(null=True, blank=True)
+    last_sync_status = models.CharField(max_length=32, blank=True, default="")
+    last_sync_message = models.TextField(blank=True, default="")
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        db_table = "city_sites"
+        ordering = ["name"]
+
+    def __str__(self) -> str:
+        return f"{self.name} ({self.code})"

backend/apps/sync/serializers.py

@@ -0,0 +1,60 @@
+from rest_framework import serializers
+
+from apps.sync.models import CitySite
+
+
+class CitySiteSerializer(serializers.ModelSerializer):
+    id = serializers.IntegerField(source="pk", read_only=True)
+    # Never echo the outbound city API key back to the browser by default.
+    has_api_key = serializers.SerializerMethodField()
+    registered_by_name = serializers.CharField(
+        source="registered_by.user_name", read_only=True, allow_null=True
+    )
+
+    class Meta:
+        model = CitySite
+        fields = [
+            "id",
+            "code",
+            "name",
+            "api_base_url",
+            "has_api_key",
+            "registered_by",
+            "registered_by_name",
+            "is_active",
+            "last_synced_at",
+            "last_sync_status",
+            "last_sync_message",
+            "created_at",
+            "updated_at",
+        ]
+        read_only_fields = [
+            "id",
+            "has_api_key",
+            "registered_by",
+            "registered_by_name",
+            "last_synced_at",
+            "last_sync_status",
+            "last_sync_message",
+            "created_at",
+            "updated_at",
+        ]
+
+    def get_has_api_key(self, obj: CitySite) -> bool:
+        return bool(obj.api_key)
+
+
+class CitySiteWriteSerializer(serializers.ModelSerializer):
+    id = serializers.IntegerField(source="pk", read_only=True)
+
+    class Meta:
+        model = CitySite
+        fields = [
+            "id",
+            "code",
+            "name",
+            "api_base_url",
+            "api_key",
+            "is_active",
+        ]
+        extra_kwargs = {"api_key": {"write_only": True, "required": False}}

backend/apps/sync/urls.py

@@ -0,0 +1,11 @@
+from django.urls import include, path
+from rest_framework.routers import DefaultRouter
+
+from apps.sync.views import CitySiteViewSet
+
+router = DefaultRouter()
+router.register("city-sites", CitySiteViewSet, basename="city-site")
+
+urlpatterns = [
+    path("", include(router.urls)),
+]

backend/apps/sync/views.py

@@ -0,0 +1,77 @@
+from rest_framework import status, viewsets
+from rest_framework.decorators import action
+from rest_framework.response import Response
+
+from apps.accounts.permissions import CanRegisterCitySite, IsExecutive, can_sync
+from apps.accounts.scoping import filter_city_sites_queryset
+from apps.farms.services.city_registry import ensure_hq_site_for_city
+from apps.sync.models import CitySite
+from apps.sync.serializers import CitySiteSerializer, CitySiteWriteSerializer
+
+
+class CitySiteViewSet(viewsets.ModelViewSet):
+    """
+    List/read: scoped (director all; BUH managed GMs; GM own).
+    Create/update/delete: GM and GM Admin.
+    Sync: GM and GM Admin only (stubs until mirror pull is implemented).
+
+    Creating a city site also attaches (or creates) an HQ Site so farm data
+    appears in the executive view list.
+    """
+
+    executive_sync_action = True
+
+    def get_queryset(self):
+        qs = CitySite.objects.select_related("registered_by").all()
+        return filter_city_sites_queryset(qs, self.request.user)
+
+    def get_permissions(self):
+        if self.action in {"create", "update", "partial_update", "destroy"}:
+            return [CanRegisterCitySite()]
+        return [IsExecutive()]
+
+    def get_serializer_class(self):
+        if self.action in {"create", "update", "partial_update"}:
+            return CitySiteWriteSerializer
+        return CitySiteSerializer
+
+    def perform_create(self, serializer):
+        city = serializer.save(registered_by=self.request.user)
+        ensure_hq_site_for_city(city)
+
+    def perform_update(self, serializer):
+        city = serializer.save()
+        if city.is_active:
+            ensure_hq_site_for_city(city)
+
+    @action(detail=True, methods=["post"], url_path="sync")
+    def sync(self, request, pk=None):
+        if not can_sync(request.user):
+            return Response({"detail": "Sync not allowed."}, status=status.HTTP_403_FORBIDDEN)
+        city = self.get_object()
+        if not city.is_active:
+            return Response(
+                {"detail": "City site is inactive."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+        return Response(
+            {
+                "detail": "City sync not implemented yet.",
+                "city_site": CitySiteSerializer(city).data,
+            },
+            status=status.HTTP_501_NOT_IMPLEMENTED,
+        )
+
+    @action(detail=False, methods=["post"], url_path="sync-all")
+    def sync_all(self, request):
+        if not can_sync(request.user):
+            return Response({"detail": "Sync not allowed."}, status=status.HTTP_403_FORBIDDEN)
+        cities = list(self.get_queryset().filter(is_active=True))
+        return Response(
+            {
+                "detail": "City sync-all not implemented yet.",
+                "city_count": len(cities),
+                "cities": CitySiteSerializer(cities, many=True).data,
+            },
+            status=status.HTTP_501_NOT_IMPLEMENTED,
+        )