improve cases series handling in collection

atlas/models.py

@@ -2217,6 +2217,29 @@ class CaseDetail(models.Model):
         help_text="Optional per-case override for additional answer-only time in seconds after case view lock.",
     )
 
+    class SeriesVisibility(models.TextChoices):
+        ALWAYS = "AL", _("Show all the time")
+        REVIEW = "RE", _("Show on review")
+        HIDDEN = "NO", _("Do not show")
+
+    series_visibility_config = models.JSONField(
+        default=dict,
+        blank=True,
+        help_text="Per-series visibility map for this case in this collection.",
+    )
+
+    learner_comment = models.TextField(
+        blank=True,
+        default="",
+        help_text="Comment shown to the learner while taking the case and on review.",
+    )
+
+    learner_review_comment = models.TextField(
+        blank=True,
+        default="",
+        help_text="Comment shown to the learner only on review.",
+    )
+
     class Meta:
         ordering = ("sort_order",)
 
@@ -2270,23 +2293,72 @@ class CaseDetail(models.Model):
             return self.override_history
         return self.case.history or "No history provided"
 
-    def get_case_series_nested(self, include_priors=True):
-        case_series_images = self.case.get_series_images_nested(as_json=False)
+    def get_series_visibility_map(self) -> dict[str, str]:
+        raw_map = self.series_visibility_config or {}
+        if not isinstance(raw_map, dict):
+            return {}
+
+        valid_values = {
+            self.SeriesVisibility.ALWAYS,
+            self.SeriesVisibility.REVIEW,
+            self.SeriesVisibility.HIDDEN,
+        }
+        cleaned = {}
+        for key, value in raw_map.items():
+            key_str = str(key)
+            value_str = str(value)
+            if value_str in valid_values:
+                cleaned[key_str] = value_str
+        return cleaned
+
+    def get_series_visibility_for(self, series, review_mode: bool = False) -> str:
+        visibility = self.get_series_visibility_map().get(
+            str(series.pk), self.SeriesVisibility.ALWAYS
+        )
+        if visibility == self.SeriesVisibility.REVIEW and not review_mode:
+            return self.SeriesVisibility.HIDDEN
+        return visibility
+
+    def get_visible_case_series(self, review_mode: bool = False):
+        visible = []
+        for series in self.case.get_ordered_series():
+            visibility = self.get_series_visibility_for(series, review_mode=review_mode)
+            if visibility != self.SeriesVisibility.HIDDEN:
+                visible.append(series)
+        return visible
+
+    def get_case_series_nested(self, include_priors=True, review_mode: bool = False):
+        case_series_images = []
+        for series in self.get_visible_case_series(review_mode=review_mode):
+            case_series_images.append([
+                image.image.url
+                for image in series.images.filter(removed=False)
+                if image.image
+            ])
 
         if include_priors:
             logger.debug(f"Checking for prior cases for case {self.case}")
             logger.debug(f"Found {self.case.prior_case.count()} prior cases for case {self.case}")
 
             for prior in self.caseprior_set.all():
+                if prior.prior_visibility == CasePrior.PriorVisibility.NONE:
+                    continue
+                if prior.prior_visibility == CasePrior.PriorVisibility.REVIEW and not review_mode:
+                    continue
                 logger.debug(f"Adding prior case {prior.prior_case} to case {self.case}")
                 case_series_images.extend(prior.prior_case.get_series_images_nested(as_json=False))
 
         return json.dumps(case_series_images)
 
-    def get_case_named_stacks(self, include_priors=True):
+    def get_case_named_stacks(self, include_priors=True, review_mode: bool = False):
         def build_stacks_for(case_obj, prefix=None):
             stacks = []
-            for series in case_obj.get_ordered_series():
+            if case_obj == self.case:
+                series_iterable = self.get_visible_case_series(review_mode=review_mode)
+            else:
+                series_iterable = case_obj.get_ordered_series()
+
+            for series in series_iterable:
                 series_images = list(series.get_images())
                 series_images_with_urls = [(img, f"{REMOTE_URL}{img.image.url}") for img in series_images]
                 images = [url for _, url in series_images_with_urls]
@@ -2316,6 +2388,10 @@ class CaseDetail(models.Model):
         # include priors as separate entries
         if include_priors:
             for prior in self.caseprior_set.all():
+                if prior.prior_visibility == CasePrior.PriorVisibility.NONE:
+                    continue
+                if prior.prior_visibility == CasePrior.PriorVisibility.REVIEW and not review_mode:
+                    continue
                 prior_case = prior.prior_case
                 results.append(
                     {