Extract status into an append only log

This gives us a history of the changes a clinic has gone through.

It does add a bit of friction with the ORM, because we can technically
create Clinic objects without a state now, but we can encapsulate this
in a service object.

Author: MatMoore

manage_breast_screening/clinics/fixtures/clinics.json

@@ -28,8 +28,7 @@
       "starts_at": "2025-04-01T09:00:00Z",
       "ends_at": "2025-04-04T17:00:00Z",
       "type": "SCREENING",
-      "risk_type": "ROUTINE_RISK",
-      "state": "IN_PROGRESS"
+      "risk_type": "ROUTINE_RISK"
     }
   },
   {
@@ -86,5 +85,14 @@
       "starts_at": "2025-05-01T13:00:00Z",
       "duration_in_minutes": 30
     }
+  },
+  {
+    "model": "clinics.clinicstatus",
+    "pk": "82da38f1-f39f-4692-8a76-d621630caa69",
+    "fields": {
+      "created_at": "2025-06-20T09:22:36.070Z",
+      "state": "IN_PROGRESS",
+      "clinic": "ce662c8b-92dc-4c82-9d5d-1ddcb201e2b6"
+    }
   }
 ]

manage_breast_screening/clinics/migrations/0013_move_clinic_state_to_table.py

@@ -0,0 +1,86 @@
+# Generated by Django 5.2.3 on 2025-06-17 12:51
+
+import uuid
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+def extract_status(apps, schema_editor):
+    Clinic = apps.get_model("clinics", "Clinic")
+    for clinic in Clinic.objects.all():
+        clinic.statuses.create(state=clinic.state)
+
+
+def revert_extract_status(apps, schema_editor):
+    Clinic = apps.get_model("clinics", "Clinic")
+    for clinic in Clinic.objects.all():
+        clinic.state = clinic.statuses.first().state
+        clinic.save()
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("clinics", "0012_remove_screeningepisode_participant_and_more"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="clinic",
+            name="state",
+            field=models.CharField(
+                choices=[
+                    ("SCHEDULED", "Scheduled"),
+                    ("IN_PROGRESS", "In progress"),
+                    ("CLOSED", "Closed"),
+                    ("CANCELLED", "Cancelled"),
+                ],
+                max_length=50,
+                null=True,
+            ),
+        ),
+        migrations.CreateModel(
+            name="ClinicStatus",
+            fields=[
+                (
+                    "id",
+                    models.UUIDField(
+                        default=uuid.uuid4,
+                        editable=False,
+                        primary_key=True,
+                        serialize=False,
+                    ),
+                ),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                (
+                    "state",
+                    models.CharField(
+                        choices=[
+                            ("SCHEDULED", "Scheduled"),
+                            ("IN_PROGRESS", "In progress"),
+                            ("CLOSED", "Closed"),
+                            ("CANCELLED", "Cancelled"),
+                        ],
+                        max_length=50,
+                    ),
+                ),
+                (
+                    "clinic",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.PROTECT,
+                        related_name="statuses",
+                        to="clinics.clinic",
+                    ),
+                ),
+            ],
+            options={
+                "ordering": ["-created_at"],
+            },
+        ),
+        migrations.RunPython(extract_status, revert_extract_status),
+        migrations.RemoveField(
+            model_name="clinic",
+            name="state",
+        ),
+    ]

manage_breast_screening/clinics/models.py

@@ -1,3 +1,4 @@
+import uuid
 from datetime import date
 from enum import StrEnum
 
@@ -61,14 +62,11 @@ def completed(self):
         """
         return self.filter(starts_at__date__lt=date.today())
 
+    def with_statuses(self):
+        return self.prefetch_related("statuses")
 
-class Clinic(BaseModel):
-    class State:
-        SCHEDULED = "SCHEDULED"
-        IN_PROGRESS = "IN_PROGRESS"
-        CLOSED = "CLOSED"
-        CANCELLED = "CANCELLED"
 
+class Clinic(BaseModel):
     class RiskType:
         MIXED_RISK = "MIXED_RISK"
         ROUTINE_RISK = "ROUTINE_RISK"
@@ -83,13 +81,6 @@ class TimeOfDay:
         MORNING = "morning"
         AFTERNOON = "afternoon"
 
-    STATE_CHOICES = {
-        State.SCHEDULED: "Scheduled",
-        State.IN_PROGRESS: "In progress",
-        State.CLOSED: "Closed",
-        State.CANCELLED: "Cancelled",
-    }
-
     RISK_TYPE_CHOICES = {
         RiskType.MIXED_RISK: "Mixed risk",
         RiskType.ROUTINE_RISK: "Routine risk",
@@ -103,10 +94,12 @@ class TimeOfDay:
     ends_at = models.DateTimeField()
     type = models.CharField(choices=TYPE_CHOICES, max_length=50)
     risk_type = models.CharField(choices=RISK_TYPE_CHOICES, max_length=50)
-    state = models.CharField(choices=STATE_CHOICES, max_length=50)
 
     objects = ClinicQuerySet.as_manager()
 
+    def current_status(self):
+        return self.statuses.first()
+
     def session_type(self):
         start_hour = self.starts_at.hour
         duration = (self.ends_at - self.starts_at).seconds
@@ -137,3 +130,27 @@ class ClinicSlot(BaseModel):
     )
     starts_at = models.DateTimeField()
     duration_in_minutes = models.IntegerField()
+
+
+class ClinicStatus(models.Model):
+    SCHEDULED = "SCHEDULED"
+    IN_PROGRESS = "IN_PROGRESS"
+    CLOSED = "CLOSED"
+    CANCELLED = "CANCELLED"
+
+    STATE_CHOICES = [
+        (SCHEDULED, "Scheduled"),
+        (IN_PROGRESS, "In progress"),
+        (CLOSED, "Closed"),
+        (CANCELLED, "Cancelled"),
+    ]
+
+    class Meta:
+        ordering = ["-created_at"]
+
+    id = models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+    state = models.CharField(choices=STATE_CHOICES, max_length=50)
+    clinic = models.ForeignKey(
+        Clinic, on_delete=models.PROTECT, related_name="statuses"
+    )

manage_breast_screening/clinics/presenters.py

@@ -1,6 +1,6 @@
 from ..core.utils.date_formatting import format_date, format_time_range
 from ..core.utils.string_formatting import sentence_case
-from .models import Clinic
+from .models import ClinicStatus
 
 
 class ClinicsPresenter:
@@ -23,9 +23,9 @@ def heading(self):
 
 class ClinicPresenter:
     STATUS_COLORS = {
-        Clinic.State.SCHEDULED: "blue",  # default blue
-        Clinic.State.IN_PROGRESS: "blue",
-        Clinic.State.CLOSED: "grey",
+        ClinicStatus.SCHEDULED: "blue",  # default blue
+        ClinicStatus.IN_PROGRESS: "blue",
+        ClinicStatus.CLOSED: "grey",
     }
 
     def __init__(self, clinic):
@@ -40,7 +40,11 @@ def __init__(self, clinic):
 
     @property
     def state(self):
+        status = self._clinic.current_status()
+        value = status.state
+        text = status.get_state_display()
+
         return {
-            "text": self._clinic.get_state_display(),
-            "classes": "nhsuk-tag--" + self.STATUS_COLORS[self._clinic.state],
+            "text": text,
+            "classes": "nhsuk-tag--" + self.STATUS_COLORS[value],
         }

manage_breast_screening/clinics/tests/factories.py

@@ -1,6 +1,7 @@
 from datetime import datetime, timedelta, timezone
 
-from factory.declarations import LazyAttribute, Sequence, SubFactory
+from factory import post_generation
+from factory.declarations import LazyAttribute, RelatedFactoryList, Sequence, SubFactory
 from factory.django import DjangoModelFactory
 from factory.fuzzy import FuzzyChoice
 
@@ -24,20 +25,41 @@ class Meta:
     provider = SubFactory(ProviderFactory)
 
 
+class ClinicStatusFactory(DjangoModelFactory):
+    class Meta:
+        model = models.ClinicStatus
+
+    clinic = None
+    state = models.ClinicStatus.SCHEDULED
+
+
 class ClinicFactory(DjangoModelFactory):
     class Meta:
         model = models.Clinic
         django_get_or_create = ("starts_at", "ends_at")
 
     type = FuzzyChoice(models.Clinic.TYPE_CHOICES)
     risk_type = FuzzyChoice(models.Clinic.RISK_TYPE_CHOICES)
-    state = models.Clinic.State.SCHEDULED
     starts_at = Sequence(
         lambda n: datetime(2025, 1, 1, 9, tzinfo=timezone.utc) + timedelta(hours=n)
     )
     ends_at = LazyAttribute(lambda o: o.starts_at + timedelta(minutes=30))
     setting = SubFactory(SettingFactory)
 
+    # Create a status by default
+    statuses = RelatedFactoryList(
+        ClinicStatusFactory, size=1, factory_related_name="clinic"
+    )
+
+    # Allow passing an explicit status
+    # e.g. `current_status=ClinicStatus.IN_PROGRESS`
+    @post_generation
+    def current_status(obj, create, extracted, **kwargs):
+        if not create or not extracted:
+            return
+
+        obj.statuses.add(ClinicStatusFactory.create(state=extracted, clinic=obj))
+
 
 class ClinicSlotFactory(DjangoModelFactory):
     class Meta:

manage_breast_screening/clinics/tests/test_models.py

@@ -10,9 +10,10 @@
 from .factories import ClinicFactory
 
 
-def test_clinic_is_scheduled():
-    factory = ClinicFactory.build()
-    assert factory.state == models.Clinic.State.SCHEDULED
+@pytest.mark.django_db
+def test_clinic_current_status():
+    clinic = ClinicFactory.create(current_status=models.ClinicStatus.SCHEDULED)
+    assert clinic.current_status().state == models.ClinicStatus.SCHEDULED
 
 
 @pytest.mark.django_db

manage_breast_screening/clinics/tests/test_presenters.py

@@ -6,6 +6,7 @@
 from manage_breast_screening.clinics.presenters import ClinicPresenter
 
 from ..models import Clinic
+from .factories import ClinicStatusFactory
 
 
 @pytest.fixture
@@ -22,6 +23,7 @@ def mock_clinic():
     }
     mock.get_type_display.return_value = "Screening"
     mock.get_risk_type_display.return_value = "Routine"
+    mock.current_status.return_value = ClinicStatusFactory.build()
 
     return mock
 
@@ -36,3 +38,7 @@ def test_clinic_presenter(mock_clinic):
     assert presenter.time_range == "9am to 3pm"
     assert presenter.type == "Screening"
     assert presenter.risk_type == "Routine"
+    assert presenter.state == {
+        "classes": "nhsuk-tag--blue",
+        "text": "Scheduled",
+    }

manage_breast_screening/clinics/views.py

@@ -4,12 +4,6 @@
 
 from .models import Clinic
 
-STATUS_COLORS = {
-    Clinic.State.SCHEDULED: "blue",  # default blue
-    Clinic.State.IN_PROGRESS: "blue",
-    Clinic.State.CLOSED: "grey",
-}
-
 
 def clinic_list(request, filter="today"):
     clinics = Clinic.objects.prefetch_related("setting").by_filter(filter)