feat(local-unit): Add local unit status field and migration script (#2528)

* feat(model): add local unit status field and migration script
* fix(migration): replace migration script with migration operation

Author: sudip-khanal

local_units/admin.py

@@ -55,6 +55,7 @@ class LocalUnitAdmin(CompareVersionAdmin, admin.OSMGeoAdmin):
     )
     readonly_fields = (
         "validated",
+        "status",
         "is_locked",
         "is_new_local_unit",
     )

local_units/enums.py

@@ -4,4 +4,5 @@
     "deprecate_reason": models.LocalUnit.DeprecateReason,
     "validation_status": models.LocalUnitChangeRequest.Status,
     "validators": models.Validator,
+    "status": models.LocalUnit.Status,
 }

local_units/filterset.py

@@ -4,6 +4,11 @@
 
 
 class LocalUnitFilters(filters.FilterSet):
+    status = filters.ChoiceFilter(
+        choices=LocalUnit.Status.choices,
+        label="Status",
+    )
+
     class Meta:
         model = LocalUnit
         fields = (
@@ -14,6 +19,7 @@ class Meta:
             "draft",
             "validated",
             "is_locked",
+            "status",
         )
 
 

local_units/management/commands/notify_validators.py

@@ -8,8 +8,8 @@
 from local_units.models import LocalUnit, Validator
 from local_units.utils import (
     get_email_context,
-    get_global_validators_by_type,
-    get_region_validators_by_type,
+    get_local_unit_global_validators,
+    get_local_unit_region_validators,
 )
 from main.sentry import SentryMonitor
 from notifications.notification import send_notification
@@ -24,15 +24,15 @@ def handle(self, *args, **options):
 
         # Regional Validators: 14 days
         queryset_for_regional_validators = LocalUnit.objects.filter(
-            validated=False,
+            status__in=[LocalUnit.Status.UNVALIDATED, LocalUnit.Status.PENDING_EDIT_VALIDATION],
             is_deprecated=False,
             last_sent_validator_type=Validator.LOCAL,
             created_at__lte=timezone.now() - timedelta(days=7),
         )
 
         # Global Validators: 28 days
         queryset_for_global_validators = LocalUnit.objects.filter(
-            validated=False,
+            status__in=[LocalUnit.Status.UNVALIDATED, LocalUnit.Status.PENDING_EDIT_VALIDATION],
             is_deprecated=False,
             last_sent_validator_type=Validator.REGIONAL,
             created_at__lte=timezone.now() - timedelta(days=14),
@@ -45,7 +45,7 @@ def handle(self, *args, **options):
             email_subject = "Action Required: Local Unit Pending Validation"
             email_type = "Local Unit"
 
-            for region_admin_validator in get_region_validators_by_type(local_unit):
+            for region_admin_validator in get_local_unit_region_validators(local_unit):
                 try:
                     email_context["full_name"] = region_admin_validator.get_full_name()
                     email_body = render_to_string("email/local_units/local_unit.html", email_context)
@@ -67,7 +67,7 @@ def handle(self, *args, **options):
             email_subject = "Action Required: Local Unit Pending Validation"
             email_type = "Local Unit"
 
-            for global_validator in get_global_validators_by_type(local_unit):
+            for global_validator in get_local_unit_global_validators(local_unit):
                 try:
                     email_context["full_name"] = global_validator.get_full_name()
                     email_body = render_to_string("email/local_units/local_unit.html", email_context)

local_units/migrations/0023_localunit_status.py

@@ -0,0 +1,35 @@
+# Generated by Django 4.2.19 on 2025-08-07 06:23
+
+from django.db import migrations, models
+
+
+def migrate_validated_to_status(apps, schema_editor):
+    """
+    Update all validated field values to corresponding status values
+    """
+    LocalUnit = apps.get_model("local_units", "LocalUnit")
+    LocalUnit.objects.filter(validated=True).update(status=1)
+    LocalUnit.objects.filter(validated=False).update(status=2)
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("local_units", "0022_localunit_is_new_local_unit"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="localunit",
+            name="status",
+            field=models.IntegerField(
+                choices=[(1, "Validated"), (2, "Unvalidated"), (3, "Pending Edit Validation")],
+                default=2,
+                verbose_name="Validation Status",
+            ),
+        ),
+        migrations.RunPython(
+            migrate_validated_to_status,
+            reverse_code=migrations.RunPython.noop,
+        ),
+    ]

local_units/models.py

@@ -291,6 +291,12 @@ class DeprecateReason(models.IntegerChoices):
         SECURITY_CONCERNS = 3, _("Security concerns")
         OTHER = 4, _("Other")
 
+    class Status(models.IntegerChoices):
+        # NOTE: Tracks the status of LocalUnit entries to manage validation workflows.
+        VALIDATED = 1, "Validated"
+        UNVALIDATED = 2, "Unvalidated"
+        PENDING_EDIT_VALIDATION = 3, "Pending Edit Validation"
+
     # added to track health local unit data (Table B)
     health = models.ForeignKey(
         HealthData, on_delete=models.SET_NULL, verbose_name=_("Health Data"), related_name="health_data", null=True, blank=True
@@ -329,7 +335,10 @@ class DeprecateReason(models.IntegerChoices):
         auto_now=False,
     )
     draft = models.BooleanField(default=False, verbose_name=_("Draft"))
-    validated = models.BooleanField(default=False, verbose_name=_("Validated"))
+    validated = models.BooleanField(default=False, verbose_name=_("Validated"))  # NOTE: This field might be deprecated soon.
+    status = models.IntegerField(
+        choices=Status.choices, default=Status.UNVALIDATED, verbose_name=_("Validation Status")
+    )  # NOTE: Replacement of validated field for better status tracking
     visibility = models.IntegerField(choices=VisibilityChoices.choices, verbose_name=_("visibility"), default=2)  # 2:IFRC
     source_en = models.CharField(max_length=500, blank=True, null=True, verbose_name=_("Source in Local Language"))
     source_loc = models.CharField(max_length=500, blank=True, null=True, verbose_name=_("Source in English"))

local_units/serializers.py

@@ -199,7 +199,7 @@ class LocalUnitDetailSerializer(serializers.ModelSerializer):
     health = HealthDataSerializer(required=False, allow_null=True)
     location_geojson = serializers.SerializerMethodField()
     visibility_display = serializers.CharField(source="get_visibility_display", read_only=True)
-    validated = serializers.BooleanField(read_only=True)
+    status_details = serializers.CharField(source="get_status_display", read_only=True)
 
     class Meta:
         model = LocalUnit
@@ -211,7 +211,8 @@ class Meta:
             "created_at",
             "modified_at",
             "draft",
-            "validated",
+            "status",
+            "status_details",
             "postcode",
             "address_loc",
             "address_en",
@@ -250,7 +251,7 @@ class PrivateLocalUnitDetailSerializer(NestedCreateMixin, NestedUpdateMixin):
     # NOTE: location_geojson contains the geojson of the location
     location_geojson = serializers.SerializerMethodField(read_only=True)
     visibility_display = serializers.CharField(source="get_visibility_display", read_only=True)
-    validated = serializers.BooleanField(read_only=True)
+    status_details = serializers.CharField(source="get_status_display", read_only=True)
     location_json = LocationSerializer(required=True)
     location = serializers.CharField(required=False)
     modified_by_details = LocalUnitMiniUserSerializer(source="modified_by", read_only=True)
@@ -271,7 +272,8 @@ class Meta:
             "modified_at",
             "modified_by",
             "draft",
-            "validated",
+            "status",
+            "status_details",
             "postcode",
             "address_loc",
             "address_en",
@@ -393,7 +395,7 @@ class LocalUnitSerializer(serializers.ModelSerializer):
     country_details = LocalUnitCountrySerializer(source="country", read_only=True)
     type_details = LocalUnitTypeSerializer(source="type", read_only=True)
     health_details = MiniHealthDataSerializer(read_only=True, source="health")
-    validated = serializers.BooleanField(read_only=True)
+    status_details = serializers.CharField(source="get_status_display", read_only=True)
 
     class Meta:
         model = LocalUnit
@@ -404,7 +406,8 @@ class Meta:
             "english_branch_name",
             "location_geojson",
             "type",
-            "validated",
+            "status",
+            "status_details",
             "address_loc",
             "address_en",
             "country_details",
@@ -423,7 +426,7 @@ class PrivateLocalUnitSerializer(serializers.ModelSerializer):
     country_details = LocalUnitCountrySerializer(source="country", read_only=True)
     type_details = LocalUnitTypeSerializer(source="type", read_only=True)
     health_details = MiniHealthDataSerializer(read_only=True, source="health")
-    validated = serializers.BooleanField(read_only=True)
+    status_details = serializers.CharField(source="get_status_display", read_only=True)
     modified_by_details = LocalUnitMiniUserSerializer(source="modified_by", read_only=True)
     is_locked = serializers.BooleanField(read_only=True)
 
@@ -436,7 +439,8 @@ class Meta:
             "english_branch_name",
             "location_geojson",
             "type",
-            "validated",
+            "status",
+            "status_details",
             "address_loc",
             "address_en",
             "country_details",

local_units/test_views.py

@@ -385,7 +385,6 @@ def test_create_local_unit_administrative(self):
             "type": type.id,
             "country": country.id,
             "draft": False,
-            "validated": True,
             "postcode": "4407",
             "address_loc": "4407",
             "address_en": "",
@@ -416,6 +415,7 @@ def test_create_local_unit_administrative(self):
         data["english_branch_name"] = "Test branch name"
         response = self.client.post("/api/v2/local-units/", data=data, format="json")
         self.assertEqual(response.status_code, 201)
+        self.assertEqual(response.data["status"], LocalUnit.Status.UNVALIDATED)
 
         # Checking the request changes for the local unit is created or not
         request_change = LocalUnitChangeRequest.objects.all()
@@ -438,7 +438,6 @@ def test_create_update_local_unit_health(self):
             "created_at": "2024-05-13T06:53:14.978083Z",
             "modified_at": "2024-05-13T06:53:14.978099Z",
             "draft": False,
-            "validated": True,
             "postcode": "",
             "address_loc": "Silele Clinic is is in Hosea Inkhundla under the Shiselweni, Sigombeni is in Nkom'iyahlaba Inkhundla under the Manzini region and Mahwalala is in the Mbabane West Inkhundla under the Hhohho region.",  # noqa: E501
             "address_en": "",
@@ -506,6 +505,7 @@ def test_create_update_local_unit_health(self):
         self.assertEqual(response.status_code, 201)
         self.assertEqual(LocalUnitChangeRequest.objects.count(), 1)
         self.assertEqual(response.data["is_locked"], True)
+        self.assertEqual(response.data["status"], LocalUnit.Status.UNVALIDATED)
         # Locked local unit should not be updated, until it is unlocked
         local_unit_id = response.data["id"]
         response = self.client.put(f"/api/v2/local-units/{local_unit_id}/", data=data, format="json")
@@ -529,7 +529,6 @@ def test_revert_local_unit(self):
             "created_at": "2024-05-13T06:53:14.978083Z",
             "modified_at": "2024-05-13T06:53:14.978099Z",
             "draft": False,
-            "validated": True,
             "postcode": "",
             "address_loc": "Silele Clinic is is in Hosea Inkhundla under the Shiselweni, Sigombeni is in Nkom'iyahlaba Inkhundla under the Manzini region and Mahwalala is in the Mbabane West Inkhundla under the Hhohho region.",  # noqa: E501
             "address_en": "",
@@ -579,8 +578,8 @@ def test_revert_local_unit(self):
         response = self.client.post(f"/api/v2/local-units/{local_unit_id}/validate/")
         self.assert_200(response)
         self.assertEqual(response.data["is_locked"], False)
-        self.assertEqual(response.data["validated"], True)
-
+        # self.assertEqual(response.data["validated"], True)
+        self.assertEqual(response.data["status"], LocalUnit.Status.VALIDATED)
         # saving the previous data
         previous_data = response.data
 
@@ -591,7 +590,6 @@ def test_revert_local_unit(self):
         response = self.client.put(f"/api/v2/local-units/{local_unit_id}/", data=data, format="json")
         self.assert_200(response)
         self.assertEqual(response.data["local_branch_name"], data["local_branch_name"])
-
         # Reverting the local unit
         revert_data = {
             "reason": "Reverting the local unit test",
@@ -609,7 +607,7 @@ def test_revert_local_unit(self):
         self.assertEqual(local_unit_change_request.rejected_reason, revert_data["reason"])
         # Checking if the local unit is unlocked
         self.assertEqual(local_unit.is_locked, False)
-        self.assertEqual(local_unit.validated, True)
+        self.assertEqual(local_unit.status, LocalUnit.Status.VALIDATED)
 
     def test_latest_changes(self):
         region = Region.objects.create(name=2)
@@ -627,7 +625,7 @@ def test_latest_changes(self):
             "country": country.id,
             "created_at": "2024-05-13T06:53:14.978083Z",
             "modified_at": "2024-05-13T06:53:14.978099Z",
-            "validated": True,
+            "status": LocalUnit.Status.VALIDATED,
             "date_of_data": "2024-05-13",
             "level": level.id,
             "address_loc": "Silele Clinic is is in Hosea Inkhundla under the Shiselweni, Sigombeni is in Nkom'iyahlaba Inkhundla under the Manzini region and Mahwalala is in the Mbabane West Inkhundla under the Hhohho region.",  # noqa: E501
@@ -687,7 +685,7 @@ def test_validate_local_unit(self):
         self.authenticate()
         response = self.client.post("/api/v2/local-units/", data=data, format="json")
         self.assert_201(response)
-
+        self.assertEqual(response.data["status"], LocalUnit.Status.UNVALIDATED)
         local_unit_id = response.data["id"]
         self.authenticate(self.global_validator_user)
         # validating the local unit by the Global validator
@@ -697,6 +695,7 @@ def test_validate_local_unit(self):
             local_unit=local_unit_id, status=LocalUnitChangeRequest.Status.APPROVED
         ).last()
         self.assertEqual(local_unit_request.current_validator, Validator.GLOBAL)
+        self.assertEqual(response.data["status"], LocalUnit.Status.VALIDATED)
 
         # Testing For the local unit admin/country validator
         self.authenticate(self.country_validator_user)
@@ -709,6 +708,7 @@ def test_validate_local_unit(self):
             local_unit=local_unit_id, status=LocalUnitChangeRequest.Status.APPROVED
         ).last()
         self.assertEqual(local_unit_request.current_validator, Validator.LOCAL)
+        self.assertEqual(response.data["status"], LocalUnit.Status.VALIDATED)
 
         # Testing For the regional validator
         self.authenticate(self.region_validator_user)
@@ -720,6 +720,7 @@ def test_validate_local_unit(self):
             local_unit=local_unit_id, status=LocalUnitChangeRequest.Status.APPROVED
         ).last()
         self.assertEqual(local_unit_request.current_validator, Validator.REGIONAL)
+        self.assertEqual(response.data["status"], LocalUnit.Status.VALIDATED)
 
         # Testing for Root User/Global validator
         self.authenticate(self.root_user)
@@ -731,6 +732,7 @@ def test_validate_local_unit(self):
             local_unit=local_unit_id, status=LocalUnitChangeRequest.Status.APPROVED
         ).last()
         self.assertEqual(local_unit_request.current_validator, Validator.GLOBAL)
+        self.assertEqual(response.data["status"], LocalUnit.Status.VALIDATED)
 
 
 class TestExternallyManagedLocalUnit(APITestCase):

local_units/views.py

@@ -66,7 +66,7 @@ class PrivateLocalUnitViewSet(viewsets.ModelViewSet):
             "level",
         )
         .exclude(is_deprecated=True)
-        .order_by("validated")
+        .order_by("status")
     )
     filterset_class = LocalUnitFilters
     search_fields = (
@@ -109,13 +109,13 @@ def update(self, request, *args, **kwargs):
         # NOTE: Locking the local unit after the change request is created
         previous_data = PrivateLocalUnitDetailSerializer(local_unit, context={"request": request}).data
         local_unit.is_locked = True
-        local_unit.validated = False
+        local_unit.status = LocalUnit.Status.PENDING_EDIT_VALIDATION
         local_unit.update_reason_overview = update_reason
         local_unit.is_new_local_unit = False
         local_unit.save(
             update_fields=[
                 "is_locked",
-                "validated",
+                "status",
                 "update_reason_overview",
                 "is_new_local_unit",
             ]
@@ -164,12 +164,12 @@ def get_validate(self, request, pk=None, version=None):
         change_request_instance.save(update_fields=["status", "updated_by", "updated_at", "current_validator"])
 
         # Validate the local unit
-        local_unit.validated = True
+        local_unit.status = LocalUnit.Status.VALIDATED
         local_unit.is_locked = False
         local_unit.is_new_local_unit = False
         local_unit.save(
             update_fields=[
-                "validated",
+                "status",
                 "is_locked",
                 "is_new_local_unit",
             ]
@@ -189,7 +189,7 @@ def get_validate(self, request, pk=None, version=None):
     def get_revert(self, request, pk=None, version=None):
         local_unit = self.get_object()
 
-        if local_unit.validated:
+        if local_unit.status == LocalUnit.Status.VALIDATED:
             return bad_request("Local unit is already validated and cannot be reverted")
 
         rejected_data = PrivateLocalUnitDetailSerializer(local_unit, context={"request": request}).data
@@ -233,9 +233,9 @@ def get_revert(self, request, pk=None, version=None):
 
         # NOTE: Unlocking the reverted local unit
         local_unit.is_locked = False
-        local_unit.validated = True
+        local_unit.status = LocalUnit.Status.VALIDATED
         local_unit.is_new_local_unit = False
-        local_unit.save(update_fields=["is_locked", "validated", "is_new_local_unit"])
+        local_unit.save(update_fields=["is_locked", "status", "is_new_local_unit"])
 
         # reverting the previous data of change request to local unit by passing through serializer
         serializer = PrivateLocalUnitDetailSerializer(