endoreg-db 0.8.8.0__py3-none-any.whl → 0.8.9.2__py3-none-any.whl

endoreg_db/models/media/pdf/raw_pdf.py

@@ -13,7 +13,11 @@ from django.db import models
 
 from endoreg_db.utils.file_operations import get_uuid_filename
 from endoreg_db.utils.hashs import get_pdf_hash
-from endoreg_db.utils.paths import PDF_DIR
+from endoreg_db.utils.paths import (
+    ANONYM_REPORT_DIR,
+    IMPORT_REPORT_DIR,
+    SENSITIVE_REPORT_DIR,
+)
 from endoreg_db.utils.storage import (
     delete_field_file,
     ensure_local_file,
@@ -26,7 +30,6 @@ if TYPE_CHECKING:
 
     from endoreg_db.models.state import RawPdfState
 
-# setup logging to pdf_import.log
 import logging
 from pathlib import Path
 
@@ -67,14 +70,14 @@ class RawPdfFile(models.Model):
     text = models.TextField(blank=True, null=True)
     date_created = models.DateTimeField(auto_now_add=True)
     date_modified = models.DateTimeField(auto_now=True)
-    anonymized = models.BooleanField(default=False, help_text="True if the PDF has been anonymized.")
+
     file = models.FileField(
-        # Use the relative path from the specific PDF_DIR
-        upload_to=PDF_DIR.name,
+        # Use the relative path from the specific REPORT_DIR
+        upload_to=SENSITIVE_REPORT_DIR.name,
         validators=[FileExtensionValidator(allowed_extensions=["pdf"])],
     )
-    anonymized_file = models.FileField(
-        upload_to=PDF_DIR.name,
+    processed_file = models.FileField(
+        upload_to=ANONYM_REPORT_DIR.name,
         validators=[FileExtensionValidator(allowed_extensions=["pdf"])],
         null=True,
         blank=True,
@@ -130,9 +133,11 @@ class RawPdfFile(models.Model):
         state: models.ForeignKey["RawPdfState | None"]
         patient: models.ForeignKey["Patient | None"]
         sensitive_meta: models.ForeignKey["SensitiveMeta | None"]
-        anonym_examination_report: models.OneToOneField["AnonymExaminationReport | None"]
+        anonym_examination_report: models.OneToOneField[
+            "AnonymExaminationReport | None"
+        ]
         file = cast(FieldFile, file)
-        anonymized_file = cast(FieldFile, anonymized_file)
+        processed_file = cast(FieldFile, processed_file)
 
     @property
     def uuid(self):
@@ -147,7 +152,7 @@ class RawPdfFile(models.Model):
     @property
     def file_path(self) -> Path | None:
         """
-        Returns the file path of the stored PDF file if available; otherwise, returns None.
+        Returns the file path of the stored report file if available; otherwise, returns None.
         """
         from django.db.models.fields.files import FieldFile
 
@@ -162,7 +167,7 @@ class RawPdfFile(models.Model):
 
     def set_file_path(self, file_path: Path):
         """
-        Sets the file path of the stored PDF file.
+        Sets the file path of the stored report file.
         """
         if not file_path.exists():
             raise FileNotFoundError(f"File path does not exist: {file_path}")
@@ -173,30 +178,30 @@ class RawPdfFile(models.Model):
     @property
     def anonymized_file_path(self) -> Path | None:
         """
-        Returns the file path of the anonymized PDF file if available; otherwise, returns None.
+        Returns the file path of the anonymized report file if available; otherwise, returns None.
         """
-        if self.anonymized_file and self.anonymized_file.name:
+        if self.processed_file and self.processed_file.name:
             try:
-                return Path(self.anonymized_file.path)
+                return Path(self.processed_file.path)
             except (ValueError, AttributeError, NotImplementedError):
                 return None
         return None
 
     def set_anonymized_file_path(self, file_path: Path):
         """
-        Sets the file path of the anonymized PDF file.
+        Sets the file path of the anonymized report file.
         """
         if not file_path.exists():
             raise FileNotFoundError(f"File path does not exist: {file_path}")
 
-        save_local_file(self.anonymized_file, file_path, name=file_path.name, save=False)
-        self.save(update_fields=["anonymized_file"])
+        save_local_file(self.processed_file, file_path, name=file_path.name, save=False)
+        self.save(update_fields=["processed_file"])
 
     def get_raw_file_path(self) -> Optional[Path]:
         """
-        Get the path to the raw PDF file, searching common locations.
+        Get the path to the raw report file, searching common locations.
 
-        This method attempts to find the original raw PDF file by checking:
+        This method attempts to find the original raw report file by checking:
         1. Direct hash-based path in raw_pdfs/
         2. Scanning raw_pdfs/ directory for files matching the hash
         3. Checking the file field if it exists
@@ -211,17 +216,17 @@ class RawPdfFile(models.Model):
             try:
                 file_path = Path(self.file.path)
                 if file_path.exists():
-                    logger.debug(f"Found raw PDF via file field: {file_path}")
+                    logger.debug(f"Found raw report via file field: {file_path}")
                     return file_path
             except (ValueError, AttributeError, NotImplementedError):
                 pass
 
         # Define potential raw directories
         raw_dirs = [
-            PDF_DIR / "sensitive",  # Files might be in sensitive dir
-            Path(settings.BASE_DIR) / "data" / "raw_pdfs",
+            SENSITIVE_REPORT_DIR,  # Files might be in sensitive dir
+            Path(settings.BASE_DIR) / "data" / "temporary_reports",
             Path(settings.BASE_DIR) / "data" / "pdfs" / "raw",
-            PDF_DIR,  # General PDF directory
+            IMPORT_REPORT_DIR,  # General report directory
         ]
 
         # Check direct hash-based name in each directory
@@ -231,7 +236,7 @@ class RawPdfFile(models.Model):
 
             hash_path = raw_dir / f"{self.pdf_hash}.pdf"
             if hash_path.exists():
-                logger.debug(f"Found raw PDF at: {hash_path}")
+                logger.debug(f"Found raw report at: {hash_path}")
                 return hash_path
 
         # Scan directories for matching hash
@@ -243,19 +248,19 @@ class RawPdfFile(models.Model):
                 try:
                     file_hash = get_pdf_hash(file_path)
                     if file_hash == self.pdf_hash:
-                        logger.debug(f"Found matching PDF by hash: {file_path}")
+                        logger.debug(f"Found matching report by hash: {file_path}")
                         return file_path
                 except Exception as e:
                     logger.debug(f"Error checking {file_path}: {e}")
                     continue
 
-        logger.warning(f"No raw file found for PDF hash: {self.pdf_hash}")
+        logger.warning(f"No raw file found for report hash: {self.pdf_hash}")
         return None
 
     @property
     def file_url(self):
         """
-        Returns the URL of the stored PDF file if available; otherwise, returns None.
+        Returns the URL of the stored report file if available; otherwise, returns None.
         """
         try:
             return self.file.url if self.file and self.file.name else None
@@ -265,16 +270,20 @@ class RawPdfFile(models.Model):
     @property
     def anonymized_file_url(self):
         """
-        Returns the URL of the stored PDF file if available; otherwise, returns None.
+        Returns the URL of the stored report file if available; otherwise, returns None.
         """
         try:
-            return self.anonymized_file.url if self.anonymized_file and self.anonymized_file.name else None
+            return (
+                self.processed_file.url
+                if self.processed_file and self.processed_file.name
+                else None
+            )
         except (ValueError, AttributeError):
             return None
 
     def __str__(self):
         """
-        Return a string representation of the RawPdfFile, including its PDF hash, type, and center.
+        Return a string representation of the RawPdfFile, including its report hash, type, and center.
         """
         str_repr = f"{self.pdf_hash} ({self.pdf_type}, {self.center})"
         return str_repr
@@ -283,19 +292,57 @@ class RawPdfFile(models.Model):
         """
         Deletes the RawPdfFile instance from the database and removes the associated file from storage if it exists.
 
-        This method ensures that the physical PDF file is deleted from the file system after the database record is removed. Logs warnings or errors if the file cannot be found or deleted.
+        This method ensures that the physical report file is deleted from the file system after the database record is removed. Logs warnings or errors if the file cannot be found or deleted.
         """
         primary_name = self.file.name if self.file and self.file.name else None
-        anonymized_name = self.anonymized_file.name if self.anonymized_file and self.anonymized_file.name else None
+        anonymized_name = (
+            self.processed_file.name
+            if self.processed_file and self.processed_file.name
+            else None
+        )
 
         if delete_field_file(self.file, missing_ok=True, save=False):
             logger.info("Original file removed from storage: %s", primary_name)
-        if delete_field_file(self.anonymized_file, missing_ok=True, save=False):
+        if delete_field_file(self.processed_file, missing_ok=True, save=False):
             logger.info("Anonymized file removed from storage: %s", anonymized_name)
 
         super().delete(*args, **kwargs)
 
-    def validate_metadata_annotation(self, extracted_data_dict: Optional[dict] = None) -> bool:
+        # --- Convenience state/meta helpers used in tests and admin workflows ---
+
+    def mark_sensitive_meta_processed(self, *, save: bool = True) -> "RawPdfFile":
+        """
+        Mark this video's processing state as having its sensitive meta fully processed.
+        This proxies to the related VideoState and persists by default.
+        """
+        sm = self.sensitive_meta
+        from endoreg_db.models.metadata.sensitive_meta import SensitiveMeta
+
+        if not isinstance(sm, SensitiveMeta):
+            raise AttributeError()
+        state = self.get_or_create_state()
+        state.mark_sensitive_meta_processed(save=save)
+        return self
+
+    def mark_sensitive_meta_verified(self) -> "RawPdfFile":
+        """
+        Mark the associated SensitiveMeta as verified by setting both DOB and names as verified.
+        Ensures the SensitiveMeta and its state exist.
+        """
+        sm = self.sensitive_meta
+        # Use SensitiveMeta methods to update underlying SensitiveMetaState
+        from endoreg_db.models.metadata.sensitive_meta import SensitiveMeta
+
+        if not isinstance(sm, SensitiveMeta):
+            raise AttributeError()
+
+        sm.mark_dob_verified()
+        sm.mark_names_verified()
+        return self
+
+    def validate_metadata_annotation(
+        self, extracted_data_dict: Optional[dict] = None
+    ) -> bool:
         """
         Validate the metadata of the RawPdf instance.
 
@@ -303,9 +350,8 @@ class RawPdfFile(models.Model):
         It also ensures the video file is properly saved after the metadata update.
         """
 
-        if not self.sensitive_meta:
-            logger.error("No sensitive meta data associated with this PDF file.")
-            return False
+        self.mark_sensitive_meta_processed()
+        self.mark_sensitive_meta_verified()
 
         if not extracted_data_dict:
             logger.error("No extracted data provided for validation.")
@@ -322,16 +368,22 @@ class RawPdfFile(models.Model):
         # Save the RawPdfFile instance to ensure all changes are saved
         self.save()
 
-        logger.info(f"Metadata for PDF {self.pk} validated and updated successfully.")
+        logger.info(
+            f"Metadata for report {self.pk} validated and updated successfully."
+        )
 
         deleted_original = delete_field_file(self.file, missing_ok=True, save=False)
-        deleted_anonymized = delete_field_file(self.anonymized_file, missing_ok=True, save=False)
+        deleted_anonymized = delete_field_file(
+            self.processed_file, missing_ok=True, save=False
+        )
         self.get_or_create_state().mark_anonymization_validated()
 
         if deleted_original or deleted_anonymized:
-            self.save(update_fields=["file", "anonymized_file"])  # Persist cleared fields
+            self.save(
+                update_fields=["file", "processed_file"]
+            )  # Persist cleared fields
 
-        logger.info(f"Files for PDF {self.pk} deleted successfully.")
+        logger.info(f"Files for report {self.pk} deleted successfully.")
         return True
 
     @classmethod
@@ -345,8 +397,8 @@ class RawPdfFile(models.Model):
         Creates a RawPdfFile instance from a file and center name, ensuring an associated RawPdfState exists.
 
         Parameters:
-            file_path (Path): Path to the source PDF file.
-            center_name (str): Name of the center to associate with the PDF.
+            file_path (Path): Path to the source report file.
+            center_name (str): Name of the center to associate with the report.
             delete_source (bool): Whether to delete the source file after processing. Defaults to True.
 
         Returns:
@@ -370,12 +422,12 @@ class RawPdfFile(models.Model):
         delete_source=True,
     ):
         """
-        Creates or retrieves a RawPdfFile instance from a given PDF file path and center name.
+        Creates or retrieves a RawPdfFile instance from a given report file path and center name.
 
-        If a RawPdfFile with the same PDF hash already exists, verifies the file exists in storage and restores it if missing. Otherwise, creates a new RawPdfFile, assigns the file, and saves it to storage. Optionally deletes the source file after processing.
+        If a RawPdfFile with the same report hash already exists, verifies the file exists in storage and restores it if missing. Otherwise, creates a new RawPdfFile, assigns the file, and saves it to storage. Optionally deletes the source file after processing.
 
         Parameters:
-            file_path (Path): Path to the source PDF file.
+            file_path (Path): Path to the source report file.
             center_name (str): Name of the center to associate with the file.
             save (bool, optional): Deprecated; saving occurs internally.
             delete_source (bool, optional): Whether to delete the source file after processing (default True).
@@ -386,7 +438,7 @@ class RawPdfFile(models.Model):
         Raises:
             FileNotFoundError: If the source file does not exist.
             Center.DoesNotExist: If the specified center is not found.
-            ValueError: If the PDF hash cannot be calculated.
+            ValueError: If the report hash cannot be calculated.
             IOError: If the file fails to save to storage.
         """
         from endoreg_db.models.administration import Center
@@ -427,9 +479,13 @@ class RawPdfFile(models.Model):
                         )
                         # Re-save the file from the source to potentially fix it
                         with file_path.open("rb") as f:
-                            django_file = File(f, name=Path(_file.name).name)  # Use existing name if possible
+                            django_file = File(
+                                f, name=Path(_file.name).name
+                            )  # Use existing name if possible
                             existing_pdf_file.file = django_file
-                            existing_pdf_file.save(update_fields=["file"])  # Only update file field
+                            existing_pdf_file.save(
+                                update_fields=["file"]
+                            )  # Only update file field
                     else:
                         pass
                         # logger.debug("File for existing RawPdfFile %s already exists in storage.", pdf_hash)
@@ -485,7 +541,9 @@ class RawPdfFile(models.Model):
                     "File was not saved correctly to storage path %s after model save.",
                     _file.name,
                 )
-                raise IOError(f"File not found at expected storage path after save: {_file.name}")
+                raise IOError(
+                    f"File not found at expected storage path after save: {_file.name}"
+                )
 
             try:
                 logger.info("File saved to absolute path: %s", _file.path)
@@ -496,14 +554,18 @@ class RawPdfFile(models.Model):
                 )
 
         except Exception as e:
-            logger.error("Error processing or saving file %s for new record: %s", file_path, e)
+            logger.error(
+                "Error processing or saving file %s for new record: %s", file_path, e
+            )
             raise
 
         # Delete source file *after* successful save and verification
         if delete_source:
             try:
                 file_path.unlink()
-                logger.info("Deleted source file %s after creating new record.", file_path)
+                logger.info(
+                    "Deleted source file %s after creating new record.", file_path
+                )
             except OSError as e:
                 logger.error("Error deleting source file %s: %s", file_path, e)
 
@@ -514,15 +576,17 @@ class RawPdfFile(models.Model):
         # Ensure hash is calculated before the first save if possible and not already set
         # This is primarily a fallback if instance created manually without using create_from_file
         """
-        Saves the RawPdfFile instance, ensuring the PDF hash is set and related fields are derived from metadata.
+        Saves the RawPdfFile instance, ensuring the report hash is set and related fields are derived from metadata.
 
-        If the PDF hash is missing, attempts to calculate it from the file before saving. Validates that the file has a `.pdf` extension. If related fields such as patient, examination, center, or examiner are unset but available in the associated sensitive metadata, they are populated accordingly before saving.
+        If the report hash is missing, attempts to calculate it from the file before saving. Validates that the file has a `.pdf` extension. If related fields such as patient, examination, center, or examiner are unset but available in the associated sensitive metadata, they are populated accordingly before saving.
         """
         if not self.pk and not self.pdf_hash and self.file:
             try:
                 with ensure_local_file(self.file) as local_path:
                     self.pdf_hash = get_pdf_hash(local_path)
-                    logger.info("Calculated hash during pre-save for %s", self.file.name)
+                    logger.info(
+                        "Calculated hash during pre-save for %s", self.file.name
+                    )
             except Exception as exc:
                 logger.warning(
                     "Could not calculate hash before initial save for %s: %s",
@@ -531,7 +595,7 @@ class RawPdfFile(models.Model):
                 )
 
         if self.file and not self.file.name.endswith(".pdf"):
-            raise ValidationError("Only PDF files are allowed")
+            raise ValidationError("Only report files are allowed")
 
         # If hash is still missing after potential creation logic (e.g., direct instantiation)
         # and the file exists in storage, try calculating it from storage path.
@@ -539,7 +603,9 @@ class RawPdfFile(models.Model):
         if not self.pdf_hash and self.pk and self.file and file_exists(self.file):
             try:
                 with ensure_local_file(self.file) as local_path:
-                    logger.warning("Hash missing for saved file %s. Recalculating.", self.file.name)
+                    logger.warning(
+                        "Hash missing for saved file %s. Recalculating.", self.file.name
+                    )
                     self.pdf_hash = get_pdf_hash(local_path)
             except Exception as exc:
                 logger.error(
@@ -585,7 +651,7 @@ class RawPdfFile(models.Model):
         # This method might still be useful if called explicitly, but create_from_file now handles restoration
         # Ensure fallback_file is a Path object.
         """
-        Checks if the stored PDF file exists in storage and attempts to restore it from a fallback file path if missing.
+        Checks if the stored report file exists in storage and attempts to restore it from a fallback file path if missing.
 
         Parameters:
             fallback_file: Path or string representing the fallback file location to restore from if the stored file is missing.
@@ -597,12 +663,18 @@ class RawPdfFile(models.Model):
         assert _file is not None
         try:
             if not _file.field.storage.exists(_file.name):
-                logger.warning(f"File missing at storage path {_file.name}. Attempting copy from fallback {fallback_file}")
+                logger.warning(
+                    f"File missing at storage path {_file.name}. Attempting copy from fallback {fallback_file}"
+                )
                 if fallback_file.exists():
                     with fallback_file.open("rb") as f:
                         # Use save method which handles storage backend
-                        _file.save(Path(_file.name).name, File(f), save=True)  # Re-save the file content
-                    logger.info(f"Successfully restored file from fallback {fallback_file} to {_file.name}")
+                        _file.save(
+                            Path(_file.name).name, File(f), save=True
+                        )  # Re-save the file content
+                    logger.info(
+                        f"Successfully restored file from fallback {fallback_file} to {_file.name}"
+                    )
                 else:
                     logger.error(f"Fallback file {fallback_file} does not exist.")
         except Exception as e:
@@ -678,8 +750,8 @@ class RawPdfFile(models.Model):
         return settings_dict
 
     @staticmethod
-    def get_pdf_by_id(pdf_id: int) -> "RawPdfFile":
+    def get_pdf_by_pk(pk: int) -> "RawPdfFile":
         try:
-            return RawPdfFile.objects.get(pk=pdf_id)
+            return RawPdfFile.objects.get(pk=pk)
         except RawPdfFile.DoesNotExist:
-            raise ValueError(f"PDF with ID {pdf_id} does not exist.")
+            raise ValueError(f"report with ID {pdf_id} does not exist.")

endoreg_db/models/media/pdf/report_reader/report_reader_config.py

@@ -12,21 +12,41 @@ if TYPE_CHECKING:
 
 class ReportReaderConfig(models.Model):
     """
-    Configuration settings for parsing PDF reports (ReportReader).
+    Configuration settings for parsing report reports (ReportReader).
 
     Stores locale, name lists, date format, and flags used to identify key information lines
     and text sections to ignore.
     """
 
     locale = models.CharField(default="de_DE", max_length=10)
-    first_names = models.ManyToManyField("FirstName", related_name="report_reader_configs")
-    last_names = models.ManyToManyField("LastName", related_name="report_reader_configs")
+    first_names = models.ManyToManyField(
+        "FirstName", related_name="report_reader_configs"
+    )
+    last_names = models.ManyToManyField(
+        "LastName", related_name="report_reader_configs"
+    )
     text_date_format = models.CharField(default="%d.%m.%Y", max_length=10)
-    patient_info_line_flag = models.ForeignKey("ReportReaderFlag", related_name="report_reader_configs_patient_info_line", on_delete=models.CASCADE)
-    endoscope_info_line_flag = models.ForeignKey("ReportReaderFlag", related_name="report_reader_configs_endoscope_info_line", on_delete=models.CASCADE)
-    examiner_info_line_flag = models.ForeignKey("ReportReaderFlag", related_name="report_reader_configs_examiner_info_line", on_delete=models.CASCADE)
-    cut_off_below = models.ManyToManyField("ReportReaderFlag", related_name="report_reader_configs_cut_off_below")
-    cut_off_above = models.ManyToManyField("ReportReaderFlag", related_name="report_reader_configs_cut_off_above")
+    patient_info_line_flag = models.ForeignKey(
+        "ReportReaderFlag",
+        related_name="report_reader_configs_patient_info_line",
+        on_delete=models.CASCADE,
+    )
+    endoscope_info_line_flag = models.ForeignKey(
+        "ReportReaderFlag",
+        related_name="report_reader_configs_endoscope_info_line",
+        on_delete=models.CASCADE,
+    )
+    examiner_info_line_flag = models.ForeignKey(
+        "ReportReaderFlag",
+        related_name="report_reader_configs_examiner_info_line",
+        on_delete=models.CASCADE,
+    )
+    cut_off_below = models.ManyToManyField(
+        "ReportReaderFlag", related_name="report_reader_configs_cut_off_below"
+    )
+    cut_off_above = models.ManyToManyField(
+        "ReportReaderFlag", related_name="report_reader_configs_cut_off_above"
+    )
 
     if TYPE_CHECKING:
         patient_info_line_flag = models.ForeignKey["ReportReaderFlag"]
@@ -35,8 +55,12 @@ class ReportReaderConfig(models.Model):
 
         first_names = cast(models.manager.RelatedManager["FirstName"], first_names)
         last_names = cast(models.manager.RelatedManager["LastName"], last_names)
-        cut_off_below = cast(models.manager.RelatedManager["ReportReaderFlag"], cut_off_below)
-        cut_off_above = cast(models.manager.RelatedManager["ReportReaderFlag"], cut_off_above)
+        cut_off_below = cast(
+            models.manager.RelatedManager["ReportReaderFlag"], cut_off_below
+        )
+        cut_off_above = cast(
+            models.manager.RelatedManager["ReportReaderFlag"], cut_off_above
+        )
 
     def __str__(self):
         """Returns a string representation including the locale and primary key."""

endoreg_db/models/media/processing_history/__init__.py

@@ -0,0 +1,5 @@
+from .processing_history import ProcessingHistory
+
+__all__ = [
+    "ProcessingHistory"
+]

endoreg_db/models/media/processing_history/processing_history.py

@@ -0,0 +1,96 @@
+from typing import Optional
+
+from django.contrib.contenttypes.fields import GenericForeignKey
+from django.contrib.contenttypes.models import ContentType
+from django.db import models
+
+
+class ProcessingHistory(models.Model):
+    """
+    Generic processing history for media files (video, pdf, ...).
+
+    Stores:
+      - which object (VideoFile/RawPdfFile/other) this entry belongs to
+      - whether processing/anonymization succeeded
+      - timestamps
+    """
+
+    created_at = models.DateTimeField(auto_now_add=True)
+    success = models.BooleanField(default=False, blank=True)
+
+    content_type = models.ForeignKey(ContentType, on_delete=models.CASCADE)
+    object_id = models.PositiveBigIntegerField()
+    content_object = GenericForeignKey("content_type", "object_id")
+
+    class Meta:
+        ordering = ["-created_at"]
+
+    def __str__(self) -> str:
+        return f"{self.content_type} #{self.object_id}, Success: {self.success}"
+
+    # --- public helpers that work with *objects* ---
+
+    @classmethod
+    def get_or_create_for_object(
+        cls,
+        *,
+        obj: models.Model,
+        success: Optional[bool],
+    ) -> "ProcessingHistory":
+        """
+        Get or create a ProcessingHistory entry for a concrete model instance.
+
+        - Returns existing entry for (object_id, content_type) if present
+        - Otherwise creates one with the given success flag (default False)
+        - If an entry exists and `success` is provided, it updates `success`
+        """
+        ct = ContentType.objects.get_for_model(obj, for_concrete_model=False)
+
+        ph, created = cls.objects.get_or_create(
+            object_id=obj.pk,
+            content_type=ct,
+            defaults={"success": success},
+        )
+
+        if not created and success is not None and ph.success != success:
+            ph.success = success
+            ph.save(update_fields=["success"])
+
+        return ph
+
+    @classmethod
+    def has_history(
+        cls,
+        *,
+        object_id: int,
+        content_type: ContentType,
+        success: Optional[bool] = None,
+    ) -> bool:
+        """
+        Return True if there is at least one ProcessingHistory entry for the
+        given (object_id, content_type) combination.
+
+        If `success` is not None, only entries matching that success flag are
+        considered.
+        """
+        qs = cls.objects.filter(object_id=object_id, content_type=content_type)
+        if success is not None:
+            qs = qs.filter(success=success)
+        return qs.exists()
+
+    @classmethod
+    def has_history_for_object(
+        cls,
+        *,
+        obj: models.Model,
+        success: Optional[bool] = None,
+    ) -> bool:
+        """
+        Convenience wrapper for model instances.
+        """
+        ct = ContentType.objects.get_for_model(obj, for_concrete_model=False)
+        return cls.has_history(
+            object_id=obj.pk,
+            content_type=ct,
+            success=success,
+        )