Add ReadingSessionService for assigning cases to sessions

The first method is to begin a new session and assign a case to it.

If there are no available cases, raise an exception, `NoImagesToRead`.

This service should ensure the following:

1. A reader can only see cases linked to their current provider
2. The same case should not be assigned more than once

At Case creation time, we will ensure that there are exactly 2 cases per
study (not implemented yet).

To avoid race conditions, I've used `SELECT... FOR UPDATE` to get the
most recent item from the Case queue.

This holds a lock on the selected table, so that concurrent executions
cannot select the same case in between querying the most recent case
and using it to create the session. `skip_locked` means that instead of
blocking on concurrent access, it will skip over the locked row[1].

[1]. https://www.postgresql.org/docs/current/sql-select.html

Author: MatMoore

manage_breast_screening/clinics/models.py

@@ -9,6 +9,8 @@
 from django.db import models
 from django.db.models import OuterRef, Subquery
 
+from manage_breast_screening.dicom.models import Case
+
 from ..auth.models import Role
 from ..core.models import BaseModel
 from ..participants.models import Appointment, Participant
@@ -34,6 +36,12 @@ def participants(self):
             screeningepisode__appointment__clinic_slot__clinic__setting__provider=self
         ).distinct()
 
+    @property
+    def image_reading_cases(self):
+        return Case.objects.filter(
+            study__appointment__clinic_slot__clinic__setting__provider=self
+        )
+
     def get_config(self) -> "ProviderConfig":
         config, _ = ProviderConfig.objects.get_or_create(provider=self)
         return config

manage_breast_screening/config/settings/base.py

@@ -384,3 +384,5 @@ def list_env(key):
 }
 
 BYPASS_API_TOKEN_AUTH = boolean_env("BYPASS_API_TOKEN_AUTH", default=False)
+
+READING_SESSION_DEFAULT_SIZE = 50

manage_breast_screening/reading/services/__init__.py

@@ -0,0 +1,34 @@
+from django.conf import settings
+from django.db import transaction
+
+from ...dicom.models import ReadingSession, ReadingSessionItem
+
+
+class NoImagesToRead(Exception):
+    pass
+
+
+class ReadingSessionService:
+    def __init__(self, reader, provider):
+        self.reader = reader
+        self.provider = provider
+
+    @transaction.atomic
+    def assign_item_to_new_session(self) -> ReadingSessionItem:
+        queue = (
+            self.provider.image_reading_cases.unassigned()
+            .where_same_study_has_not_been_assigned_to_reader(self.reader)
+            .order_by("created_at", "id")
+            .select_for_update(skip_locked=True)
+        )
+
+        case = queue.first()
+        if case is None:
+            raise NoImagesToRead
+
+        session = ReadingSession.objects.create(
+            reader=self.reader, session_size=settings.READING_SESSION_DEFAULT_SIZE
+        )
+        item = session.items.create(session=session, case=case, reading_order=1)
+
+        return item

manage_breast_screening/reading/services/reading_session_service.py

@@ -0,0 +1,96 @@
+from datetime import datetime
+from datetime import timezone as tz
+
+import pytest
+import time_machine
+
+from manage_breast_screening.dicom.models import Study
+from manage_breast_screening.dicom.tests.factories import (
+    ReadingSessionItemFactory,
+    StudyFactory,
+)
+from manage_breast_screening.reading.services.reading_session_service import (
+    NoImagesToRead,
+    ReadingSessionService,
+)
+
+
+@pytest.mark.django_db
+class TestSessionService:
+    @pytest.fixture
+    def older_study(self, current_provider):
+        with time_machine.travel(datetime(2026, 1, 1, 9, 0, 0, tzinfo=tz.utc)):
+            return StudyFactory.create(
+                appointment__clinic_slot__clinic__setting__provider=current_provider,
+            )
+
+    @pytest.fixture
+    def newer_study(self, current_provider):
+        with time_machine.travel(datetime(2026, 1, 1, 10, 0, 0, tzinfo=tz.utc)):
+            return StudyFactory.create(
+                appointment__clinic_slot__clinic__setting__provider=current_provider,
+            )
+
+    def test_create_with_one_study(self, user, current_provider):
+        assert Study.objects.count() == 0
+        study = StudyFactory.create(
+            appointment__clinic_slot__clinic__setting__provider=current_provider,
+        )
+
+        item = ReadingSessionService(
+            user, current_provider
+        ).assign_item_to_new_session()
+
+        assert item.study == study
+        assert item.session.items.count() == 1
+
+    def test_create_with_zero_studies(self, user, current_provider):
+        with pytest.raises(NoImagesToRead):
+            ReadingSessionService(user, current_provider).assign_item_to_new_session()
+
+    def test_create_with_many_studies(
+        self, user, current_provider, older_study, newer_study
+    ):
+        item = ReadingSessionService(
+            user, current_provider
+        ).assign_item_to_new_session()
+        assert item.study == older_study
+
+    def test_create_excludes_studies_already_assigned_to_me(
+        self, user, current_provider, older_study, newer_study
+    ):
+        """
+        A study could be assigned to another session, in which case we should ignore it when starting a new session.
+        """
+        ReadingSessionItemFactory.create(
+            case=older_study.cases.first(), session__reader=user
+        )
+
+        item = ReadingSessionService(
+            user, current_provider
+        ).assign_item_to_new_session()
+        assert item.study == newer_study
+
+    def test_create_includes_studies_with_one_case_assigned(
+        self, user, current_provider, older_study, newer_study
+    ):
+        ReadingSessionItemFactory(case=older_study.cases.first())
+
+        item = ReadingSessionService(
+            user, current_provider
+        ).assign_item_to_new_session()
+        assert item.study == older_study
+
+    def test_create_excludes_studies_with_all_cases_assigned(
+        self, user, current_provider, older_study, newer_study
+    ):
+        ReadingSessionItemFactory(case=older_study.cases.first())
+        ReadingSessionItemFactory(case=older_study.cases.last())
+
+        item = ReadingSessionService(
+            user, current_provider
+        ).assign_item_to_new_session()
+        assert item.study == newer_study
+
+
+#