Introduce Case model for image reading cases

It's useful to have an entity representing a thing to be read, that
exists prior to us assigning it to a reader. The models we have now
don't quite fit:

- A `Reading` is not created until the opinion is given
- A `ReadingSessionItem` is not created until it is assigned to a reading session.
- A `Study` logically has 2 cases, the first read and the second read

We have to ensure that each set of images gets assigned and read exactly
2 times (prior to arbitration, which we haven't implemented yet)

I think the simplest way to handle this constraint is to have a separate
`Case` queue, push 2 cases into it per study, and then grab the oldest
case whenever we need to assign one to a reading session. We also
refer to cases in the UI.

Later we might decide to give each case a type (1st read/2nd read) so we
can do further filtering on the image reading dashboard.

When assigning to a reading session, we will link the `ReadingSessionItem`
to the `Case`.

Note: there is a second constraint that a reader can only read the same
study once, and only cases belonging to the current provider will be
visible, so it will actually be a filtered subset of this table that
is available for assigning to a reading session.

Author: MatMoore

manage_breast_screening/dicom/migrations/0010_auto_20260430_1359.py

@@ -0,0 +1,51 @@
+# Generated by Django 6.0.4 on 2026-04-30 12:59
+
+import uuid
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dicom', '0009_rename_order_readingsessionitem_reading_order_and_more'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Case',
+            fields=[
+                ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('study', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='cases', to='dicom.study')),
+            ],
+            options={
+                'abstract': False,
+            },
+        ),
+        migrations.RunSQL(
+            sql='TRUNCATE TABLE dicom_readingsession CASCADE',
+            reverse_sql='TRUNCATE table dicom_readingsession CASCADE',
+        ),
+        migrations.AlterField(
+            model_name='reading',
+            name='study',
+            field=models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='readings', to='dicom.study'),
+        ),
+        migrations.RemoveField(
+            model_name='readingsessionitem',
+            name='reading',
+        ),
+        migrations.RemoveField(
+            model_name='readingsessionitem',
+            name='study',
+        ),
+        migrations.AddField(
+            model_name='readingsessionitem',
+            name='case',
+            field=models.OneToOneField(on_delete=django.db.models.deletion.PROTECT, related_name='reading_session_item', to='dicom.case'),
+            preserve_default=False,
+        )
+    ]

manage_breast_screening/dicom/migrations/max_migration.txt

@@ -1 +1 @@
-0009_rename_order_readingsessionitem_reading_order_and_more
+0010_auto_20260430_1359

manage_breast_screening/dicom/models.py

@@ -4,6 +4,7 @@
 from django.contrib.postgres.fields import ArrayField
 from django.core.files.storage import storages
 from django.db import models
+from django.db.models import Exists, OuterRef
 
 from manage_breast_screening.core.models import BaseModel
 from manage_breast_screening.manual_images.models import (
@@ -162,10 +163,10 @@ class BreastOpinions(models.TextChoices):
 
 class Reading(BaseModel):
     """
-    One reader's opinion of a study. All of the opinions feed into the consensus read.
+    One reader's opinion of a study.
     """
 
-    study = models.ForeignKey(Study, on_delete=models.PROTECT, related_name="opinions")
+    study = models.ForeignKey(Study, on_delete=models.PROTECT, related_name="readings")
     reader = models.ForeignKey(
         settings.AUTH_USER_MODEL, on_delete=models.PROTECT, related_name="readings"
     )
@@ -217,9 +218,37 @@ class RecallForAssessmentDetails(BaseModel):
     left_breast_comment = models.CharField(null=False, blank=True, default="")
 
 
+class CaseQueryset(models.QuerySet):
+    def unassigned(self):
+        return self.filter(
+            ~Exists(ReadingSessionItem.objects.filter(case=OuterRef("id")))
+        )
+
+    def where_same_study_has_not_been_assigned_to_reader(self, reader):
+        return self.filter(
+            ~Exists(
+                ReadingSessionItem.objects.filter(
+                    case__study=OuterRef("study_id"),
+                    session__reader=reader,
+                )
+            )
+        )
+
+
+class Case(BaseModel):
+    """
+    A first or second read that needs doing for a study. These form the queue of cases
+    that can be picked up by an image reader.
+    """
+
+    objects = CaseQueryset.as_manager()
+
+    study = models.ForeignKey(Study, on_delete=models.CASCADE, related_name="cases")
+
+
 class ReadingSession(BaseModel):
     """
-    A grouping of studies that are read by a reader in a single session
+    A grouping of cases to be read by a reader in a single session
     """
 
     reader = models.ForeignKey(
@@ -232,22 +261,20 @@ class ReadingSession(BaseModel):
 
 class ReadingSessionItem(BaseModel):
     """
-    Assigns a study to a particular reading session, with an ordering.
+    An assignment of a pending reading to a reading session
     """
 
     session = models.ForeignKey(
         ReadingSession, on_delete=models.CASCADE, related_name="items"
     )
-    study = models.ForeignKey(
-        Study, on_delete=models.PROTECT, related_name="reading_session_items"
+    case = models.OneToOneField(
+        Case, on_delete=models.PROTECT, related_name="reading_session_item"
     )
     reading_order = models.IntegerField()
-    reading = models.OneToOneField(
-        Reading,
-        on_delete=models.PROTECT,
-        related_name="reading_session_item",
-        null=True,
-    )
 
     class Meta:
         unique_together = [("session", "reading_order")]
+
+    @property
+    def study(self):
+        return self.case.study

manage_breast_screening/dicom/tests/factories.py

@@ -16,6 +16,7 @@
 class StudyFactory(DjangoModelFactory):
     class Meta:
         model = models.Study
+        skip_postgeneration_save = True
 
     study_instance_uid = Sequence(lambda n: f"STUDY{n:04d}")
     source_message_id = uuid.uuid4()
@@ -26,6 +27,15 @@ class Meta:
         AppointmentFactory, current_status=AppointmentStatusNames.SCREENED
     )
 
+    case_1 = RelatedFactory(
+        "manage_breast_screening.dicom.tests.factories.CaseFactory",
+        factory_related_name="study",
+    )
+    case_2 = RelatedFactory(
+        "manage_breast_screening.dicom.tests.factories.CaseFactory",
+        factory_related_name="study",
+    )
+
 
 class StudyWithImagesFactory(StudyFactory):
     class Meta:
@@ -106,11 +116,22 @@ class Params:
         )
 
 
+class CaseFactory(DjangoModelFactory):
+    class Meta:
+        model = models.Case
+
+    study = SubFactory(StudyFactory)
+
+
 class ReadingSessionItemFactory(DjangoModelFactory):
     class Meta:
         model = models.ReadingSessionItem
+        skip_postgeneration_save = True
 
-    study = SubFactory(StudyFactory)
+    case = SubFactory(CaseFactory)
+    session = SubFactory(
+        "manage_breast_screening.dicom.tests.factories.ReadingSessionFactory"
+    )
     reading_order = Sequence(lambda i: i)
 
 

manage_breast_screening/nonprod/management/commands/seed_demo_data.py

@@ -16,6 +16,7 @@
     SettingFactory,
     UserAssignmentFactory,
 )
+from manage_breast_screening.dicom.models import Case
 from manage_breast_screening.dicom.tests.factories import (
     ImageFactory as DicomImageFactory,
 )
@@ -403,7 +404,17 @@ def create_reading_session(self, session_key):
             else:
                 reading = None
 
-            ReadingSessionItemFactory(session=session, reading=reading, **item)
+            study_id = item.pop("study_id")
+            case = Case.objects.unassigned().filter(study_id=study_id).first()
+
+            ReadingSessionItemFactory(
+                session=session,
+                case=case,
+                **item,
+            )
+
+            case.reading = reading
+            case.save()
 
     def create_reading(self, reader, reading_key):
         retake_requests = reading_key.pop("retake_requests", [])