endoreg-db 0.8.3.3__py3-none-any.whl → 0.8.6.5__py3-none-any.whl

endoreg_db/models/metadata/sensitive_meta_logic.py

@@ -2,26 +2,26 @@ import logging
 import os
 import random
 import re  # Neu hinzugefügt für Regex-Pattern
+from datetime import date, datetime, timedelta
 from hashlib import sha256
-from datetime import datetime, timedelta, date
-from typing import TYPE_CHECKING, Dict, Any, Optional, Type
+from typing import TYPE_CHECKING, Any, Dict, Optional, Type
 
-from django.utils import timezone
 from django.db import transaction
+from django.utils import timezone
 
-# Assuming these utils are correctly located
-from endoreg_db.utils.hashs import get_patient_hash, get_patient_examination_hash
 from endoreg_db.utils import guess_name_gender
 
+# Assuming these utils are correctly located
+from endoreg_db.utils.hashs import get_patient_examination_hash, get_patient_hash
+
 # Import models needed for logic, use local imports inside functions if needed to break cycles
-from ..administration import Center, Examiner, Patient, FirstName, LastName
-from ..other import Gender
+from ..administration import Center, Examiner, FirstName, LastName, Patient
 from ..medical import PatientExamination
+from ..other import Gender
 from ..state import SensitiveMetaState
 
-
 if TYPE_CHECKING:
-    from .sensitive_meta import SensitiveMeta # Import model for type hinting
+    from .sensitive_meta import SensitiveMeta  # Import model for type hinting
 
 logger = logging.getLogger(__name__)
 SECRET_SALT = os.getenv("DJANGO_SALT", "default_salt")
@@ -35,23 +35,23 @@ DE_RX = re.compile(r"^\d{2}\.\d{2}\.\d{4}$")
 def parse_any_date(s: str) -> Optional[date]:
     """
     Parst Datumsstring mit Priorität auf deutsches Format (DD.MM.YYYY).
-    
+
     Unterstützte Formate:
     1. DD.MM.YYYY (Priorität) - deutsches Format
     2. YYYY-MM-DD (Fallback) - ISO-Format
     3. Erweiterte Fallbacks über dateparser
-    
+
     Args:
         s: Datumsstring zum Parsen
-        
+
     Returns:
         date-Objekt oder None bei ungültigem/fehlendem Input
     """
     if not s:
         return None
-    
+
     s = s.strip()
-    
+
     # 1. German dd.mm.yyyy (PRIORITÄT)
     if DE_RX.match(s):
         try:
@@ -60,7 +60,7 @@ def parse_any_date(s: str) -> Optional[date]:
         except ValueError as e:
             logger.warning(f"Invalid German date format '{s}': {e}")
             return None
-    
+
     # 2. ISO yyyy-mm-dd (Fallback für Rückwärtskompatibilität)
     if ISO_RX.match(s):
         try:
@@ -68,23 +68,20 @@ def parse_any_date(s: str) -> Optional[date]:
         except ValueError as e:
             logger.warning(f"Invalid ISO date format '{s}': {e}")
             return None
-    
+
     # 3. Extended fallbacks
     try:
         # Try standard datetime parsing
         return datetime.fromisoformat(s).date()
     except Exception:
         pass
-    
+
     try:
         # Try dateparser with German locale preference
         import dateparser
+
         dt = dateparser.parse(
-            s, 
-            settings={
-                "DATE_ORDER": "DMY", 
-                "PREFER_DAY_OF_MONTH": "first"
-            }
+            s, settings={"DATE_ORDER": "DMY", "PREFER_DAY_OF_MONTH": "first"}
         )
         return dt.date() if dt else None
     except Exception as e:
@@ -95,10 +92,10 @@ def parse_any_date(s: str) -> Optional[date]:
 def format_date_german(d: Optional[date]) -> str:
     """
     Formatiert date-Objekt als deutsches Datumsformat (DD.MM.YYYY).
-    
+
     Args:
         d: date-Objekt oder None
-        
+
     Returns:
         Formatiertes Datum als String oder leerer String bei None
     """
@@ -110,10 +107,10 @@ def format_date_german(d: Optional[date]) -> str:
 def format_date_iso(d: Optional[date]) -> str:
     """
     Formatiert date-Objekt als ISO-Format (YYYY-MM-DD).
-    
+
     Args:
         d: date-Objekt oder None
-        
+
     Returns:
         Formatiertes Datum als String oder leerer String bei None
     """
@@ -137,7 +134,7 @@ def generate_random_dob() -> datetime:
 def generate_random_examination_date() -> date:
     """Generates a random date within the last 20 years."""
     today = date.today()
-    start_date = today - timedelta(days=20 * 365) # Approximate 20 years back
+    start_date = today - timedelta(days=20 * 365)  # Approximate 20 years back
     time_between_dates = today - start_date
     days_between_dates = time_between_dates.days
     random_number_of_days = random.randrange(days_between_dates)
@@ -165,17 +162,22 @@ def calculate_patient_hash(instance: "SensitiveMeta", salt: str = SECRET_SALT) -
     if not center:
         raise ValueError("Center is required to calculate patient hash.")
 
+    assert first_name is not None, "First name is required to calculate patient hash."
+    assert last_name is not None, "Last name is required to calculate patient hash."
+
     hash_str = get_patient_hash(
         first_name=first_name,
         last_name=last_name,
         dob=dob,
-        center=center.name, # Use center name
+        center=center.name,  # Use center name
         salt=salt,
     )
     return sha256(hash_str.encode()).hexdigest()
 
 
-def calculate_examination_hash(instance: "SensitiveMeta", salt: str = SECRET_SALT) -> str:
+def calculate_examination_hash(
+    instance: "SensitiveMeta", salt: str = SECRET_SALT
+) -> str:
     """Calculates the examination hash for the instance."""
     dob = instance.patient_dob
     first_name = instance.patient_first_name
@@ -190,13 +192,12 @@ def calculate_examination_hash(instance: "SensitiveMeta", salt: str = SECRET_SAL
     if not center:
         raise ValueError("Center is required to calculate examination hash.")
 
-
     hash_str = get_patient_examination_hash(
         first_name=first_name,
         last_name=last_name,
         dob=dob,
         examination_date=examination_date,
-        center=center.name, # Use center name
+        center=center.name,  # Use center name
         salt=salt,
     )
     return sha256(hash_str.encode()).hexdigest()
@@ -206,15 +207,19 @@ def create_pseudo_examiner_logic(instance: "SensitiveMeta") -> "Examiner":
     """Creates or retrieves the pseudo examiner based on instance data."""
     first_name = instance.examiner_first_name
     last_name = instance.examiner_last_name
-    center = instance.center # Should be set before calling save
+    center = instance.center  # Should be set before calling save
 
     if not first_name or not last_name or not center:
-        logger.warning(f"Incomplete examiner info for SensitiveMeta (pk={instance.pk}). Using default examiner.")
+        logger.warning(
+            f"Incomplete examiner info for SensitiveMeta (pk={instance.pk or 'new'}). Using default examiner."
+        )
         # Ensure default center exists or handle appropriately
         try:
-            default_center = Center.objects.get_by_natural_key("endoreg_db_demo")
+            default_center = Center.objects.get(name="endoreg_db_demo")
         except Center.DoesNotExist:
-            logger.error("Default center 'endoreg_db_demo' not found. Cannot create default examiner.")
+            logger.error(
+                "Default center 'endoreg_db_demo' not found. Cannot create default examiner."
+            )
             raise ValueError("Default center 'endoreg_db_demo' not found.")
 
         examiner, _created = Examiner.custom_get_or_create(
@@ -232,7 +237,7 @@ def get_or_create_pseudo_patient_logic(instance: "SensitiveMeta") -> "Patient":
     """Gets or creates the pseudo patient based on instance data."""
     # Ensure necessary fields are set
     if not instance.patient_hash:
-         instance.patient_hash = calculate_patient_hash(instance)
+        instance.patient_hash = calculate_patient_hash(instance)
     if not instance.center:
         raise ValueError("Center must be set before creating pseudo patient.")
     if not instance.patient_gender:
@@ -254,61 +259,168 @@ def get_or_create_pseudo_patient_logic(instance: "SensitiveMeta") -> "Patient":
     return patient
 
 
-def get_or_create_pseudo_patient_examination_logic(instance: "SensitiveMeta") -> "PatientExamination":
+def get_or_create_pseudo_patient_examination_logic(
+    instance: "SensitiveMeta",
+) -> "PatientExamination":
     """Gets or creates the pseudo patient examination based on instance data."""
     # Ensure necessary fields are set
     if not instance.patient_hash:
-         instance.patient_hash = calculate_patient_hash(instance)
+        instance.patient_hash = calculate_patient_hash(instance)
     if not instance.examination_hash:
-         instance.examination_hash = calculate_examination_hash(instance)
+        instance.examination_hash = calculate_examination_hash(instance)
 
     # Ensure the pseudo patient exists first, as PatientExamination might depend on it
     if not instance.pseudo_patient_id:
         pseudo_patient = get_or_create_pseudo_patient_logic(instance)
-        instance.pseudo_patient_id = pseudo_patient.pk # Assign FK directly
-
-    patient_examination, _created = PatientExamination.get_or_create_pseudo_patient_examination_by_hash(
-        patient_hash=instance.patient_hash,
-        examination_hash=instance.examination_hash,
-        # Optionally pass pseudo_patient if the method requires it
-        # pseudo_patient=instance.pseudo_patient
+        instance.pseudo_patient_id = pseudo_patient.pk  # Assign FK directly
+
+    patient_examination, _created = (
+        PatientExamination.get_or_create_pseudo_patient_examination_by_hash(
+            patient_hash=instance.patient_hash,
+            examination_hash=instance.examination_hash,
+            # Optionally pass pseudo_patient if the method requires it
+            # pseudo_patient=instance.pseudo_patient
+        )
     )
     return patient_examination
 
 
-@transaction.atomic # Ensure all operations within save succeed or fail together
+@transaction.atomic  # Ensure all operations within save succeed or fail together
 def perform_save_logic(instance: "SensitiveMeta") -> "Examiner":
     """
     Contains the core logic for preparing a SensitiveMeta instance for saving.
     Handles data generation (dates), hash calculation, and linking pseudo-entities.
-    Returns the Examiner instance to be linked via M2M after the main save.
+
+    This function is called on every save() operation and implements a two-phase approach:
+
+    **Phase 1: Initial Creation (with defaults)**
+    - When a SensitiveMeta is first created (e.g., via get_or_create_sensitive_meta()),
+      it may have missing patient data (names, DOB, etc.)
+    - Default values are set to prevent hash calculation errors:
+      * patient_first_name: "unknown"
+      * patient_last_name: "unknown"
+      * patient_dob: random date (1920-2000)
+    - A temporary hash is calculated using these defaults
+    - Temporary pseudo-entities (Patient, Examination) are created
+
+    **Phase 2: Update (with extracted data)**
+    - When real patient data is extracted (e.g., from video OCR via lx_anonymizer),
+      update_from_dict() is called with actual values
+    - The instance fields are updated with real data (names, DOB, etc.)
+    - save() is called again, triggering this function
+    - Default-setting logic is skipped (fields are no longer empty)
+    - Hash is RECALCULATED with real data
+    - New pseudo-entities are created/retrieved based on new hash
+
+    **Example Flow:**
+    ```
+    # Initial creation
+    sm = SensitiveMeta.create_from_dict({"center": center})
+    # → patient_first_name = "unknown", patient_last_name = "unknown"
+    # → hash = sha256("unknown unknown 1990-01-01 ...")
+    # → pseudo_patient_temp created
+
+    # Later update with extracted data
+    sm.update_from_dict({"patient_first_name": "Max", "patient_last_name": "Mustermann"})
+    # → patient_first_name = "Max", patient_last_name = "Mustermann" (overwrites)
+    # → save() triggered → perform_save_logic() called again
+    # → Default-setting skipped (names already exist)
+    # → hash = sha256("Max Mustermann 1985-03-15 ...") (RECALCULATED)
+    # → pseudo_patient_real created/retrieved with new hash
+    ```
+
+    Args:
+        instance: The SensitiveMeta instance being saved
+
+    Returns:
+        Examiner: The pseudo examiner instance to be linked via M2M after save
+
+    Raises:
+        ValueError: If required fields (center, gender) cannot be determined
     """
 
     # --- Pre-Save Checks and Data Generation ---
 
     # 1. Ensure DOB and Examination Date exist
     if not instance.patient_dob:
-        logger.debug(f"SensitiveMeta (pk={instance.pk}): Patient DOB missing, generating random.")
+        logger.debug(
+            f"SensitiveMeta (pk={instance.pk or 'new'}): Patient DOB missing, generating random."
+        )
         instance.patient_dob = generate_random_dob()
     if not instance.examination_date:
-        logger.debug(f"SensitiveMeta (pk={instance.pk}): Examination date missing, generating random.")
+        logger.debug(
+            f"SensitiveMeta (pk={instance.pk or 'new'}): Examination date missing, generating random."
+        )
         instance.examination_date = generate_random_examination_date()
 
     # 2. Ensure Center exists (should be set before calling save)
     if not instance.center:
         raise ValueError("Center must be set before saving SensitiveMeta.")
 
+    # 2.5 CRITICAL: Set default patient names BEFORE hash calculation
+    #
+    # **Why this is necessary:**
+    # Hash calculation (step 4) requires first_name and last_name to be non-None.
+    # However, on initial creation (e.g., via get_or_create_sensitive_meta()), these
+    # fields may be empty because real patient data hasn't been extracted yet.
+    #
+    # **Two-phase approach:**
+    # - Phase 1 (Initial): Set defaults if names are missing
+    #   → Allows hash calculation to succeed without errors
+    #   → Creates temporary pseudo-entities with default hash
+    #
+    # - Phase 2 (Update): Real data extraction (OCR, manual input)
+    #   → update_from_dict() sets real names ("Max", "Mustermann")
+    #   → save() is called again
+    #   → This block is SKIPPED (names already exist)
+    #   → Hash is recalculated with real data (step 4)
+    #   → New pseudo-entities created with correct hash
+    #
+    # **Example:**
+    # Initial:  patient_first_name = "unknown" → hash = sha256("unknown unknown...")
+    # Updated:  patient_first_name = "Max"     → hash = sha256("Max Mustermann...")
+    #
+    if not instance.patient_first_name:
+        instance.patient_first_name = DEFAULT_UNKNOWN_NAME
+        logger.debug(
+            "SensitiveMeta (pk=%s): Patient first name missing, set to default '%s'.",
+            instance.pk or "new",
+            DEFAULT_UNKNOWN_NAME,
+        )
+
+    if not instance.patient_last_name:
+        instance.patient_last_name = DEFAULT_UNKNOWN_NAME
+        logger.debug(
+            "SensitiveMeta (pk=%s): Patient last name missing, set to default '%s'.",
+            instance.pk or "new",
+            DEFAULT_UNKNOWN_NAME,
+        )
+
     # 3. Ensure Gender exists (should be set before calling save, e.g., during creation/update)
     if not instance.patient_gender:
-         # Attempt to guess if names are available
-         first_name = instance.patient_first_name or DEFAULT_UNKNOWN_NAME
-         gender = guess_name_gender(first_name)
-         if not gender:
-             raise ValueError("Patient gender could not be determined and must be set before saving.")
-         instance.patient_gender = gender
-
+        # Use the now-guaranteed first_name for gender guessing
+        first_name = instance.patient_first_name
+        gender_str = guess_name_gender(first_name)
+        if not gender_str:
+            raise ValueError(
+                "Patient gender could not be determined and must be set before saving."
+            )
+        # Convert string to Gender object
+        try:
+            gender_obj = Gender.objects.get(name=gender_str)
+            instance.patient_gender = gender_obj
+        except Gender.DoesNotExist:
+            raise ValueError(f"Gender '{gender_str}' not found in database.")
 
     # 4. Calculate Hashes (depends on DOB, Exam Date, Center, Names)
+    #
+    # **IMPORTANT: Hashes are RECALCULATED on every save!**
+    # This enables the two-phase update pattern:
+    # - Initial save: Hash based on default "unknown unknown" names
+    # - Updated save: Hash based on real extracted names ("Max Mustermann")
+    #
+    # The new hash will link to different pseudo-entities, ensuring proper
+    # anonymization while maintaining referential integrity.
     instance.patient_hash = calculate_patient_hash(instance)
     instance.examination_hash = calculate_examination_hash(instance)
 
@@ -333,10 +445,59 @@ def perform_save_logic(instance: "SensitiveMeta") -> "Examiner":
     return examiner_instance
 
 
-def create_sensitive_meta_from_dict(cls: Type["SensitiveMeta"], data: Dict[str, Any]) -> "SensitiveMeta":
-    """Logic to create a SensitiveMeta instance from a dictionary."""
+def create_sensitive_meta_from_dict(
+    cls: Type["SensitiveMeta"], data: Dict[str, Any]
+) -> "SensitiveMeta":
+    """
+    Create a SensitiveMeta instance from a dictionary.
+
+    **Center handling:**
+    This function accepts TWO ways to specify the center:
+    1. `center` (Center object) - Directly pass a Center instance
+    2. `center_name` (string) - Pass the center name as a string (will be resolved to Center object)
+
+    At least ONE of these must be provided.
+
+    **Example usage:**
+    ```python
+    # Option 1: With Center object
+    data = {
+        "patient_first_name": "Patient",
+        "patient_last_name": "Unknown",
+        "patient_dob": date(1990, 1, 1),
+        "examination_date": date.today(),
+        "center": center_obj,  # ← Center object
+    }
+    sm = SensitiveMeta.create_from_dict(data)
+
+    # Option 2: With center name string
+    data = {
+        "patient_first_name": "Patient",
+        "patient_last_name": "Unknown",
+        "patient_dob": date(1990, 1, 1),
+        "examination_date": date.today(),
+        "center_name": "university_hospital_wuerzburg",  # ← String
+    }
+    sm = SensitiveMeta.create_from_dict(data)
+    ```
+
+    Args:
+        cls: The SensitiveMeta class
+        data: Dictionary containing field values
+
+    Returns:
+        SensitiveMeta: The created instance
 
-    field_names = {f.name for f in cls._meta.get_fields() if not f.is_relation or f.one_to_one or (f.many_to_one and f.related_model)}
+    Raises:
+        ValueError: If neither center nor center_name is provided
+        ValueError: If center_name does not match any Center in database
+    """
+
+    field_names = {
+        f.name
+        for f in cls._meta.get_fields()
+        if not f.is_relation or f.one_to_one or (f.many_to_one and f.related_model)
+    }
     selected_data = {k: v for k, v in data.items() if k in field_names}
 
     # --- Convert patient_dob if it's a date object ---
@@ -348,80 +509,153 @@ def create_sensitive_meta_from_dict(cls: Type["SensitiveMeta"], data: Dict[str,
         logger.debug("Converted patient_dob from date to aware datetime: %s", aware_dob)
     elif isinstance(dob, str):
         # Handle string DOB - check if it's a field name or actual date
-        if dob == "patient_dob" or dob in ["patient_first_name", "patient_last_name", "examination_date"]:
-            logger.warning("Skipping invalid patient_dob value '%s' - appears to be field name", dob)
+        if dob == "patient_dob" or dob in [
+            "patient_first_name",
+            "patient_last_name",
+            "examination_date",
+        ]:
+            logger.warning(
+                "Skipping invalid patient_dob value '%s' - appears to be field name",
+                dob,
+            )
             selected_data.pop("patient_dob", None)  # Remove invalid value
         else:
             # Try to parse as date string
             try:
                 import dateparser
-                parsed_dob = dateparser.parse(dob, languages=['de'], settings={'DATE_ORDER': 'DMY'})
+
+                parsed_dob = dateparser.parse(
+                    dob, languages=["de"], settings={"DATE_ORDER": "DMY"}
+                )
                 if parsed_dob:
-                    aware_dob = timezone.make_aware(parsed_dob.replace(hour=0, minute=0, second=0, microsecond=0))
+                    aware_dob = timezone.make_aware(
+                        parsed_dob.replace(hour=0, minute=0, second=0, microsecond=0)
+                    )
                     selected_data["patient_dob"] = aware_dob
-                    logger.debug("Parsed string patient_dob '%s' to aware datetime: %s", dob, aware_dob)
+                    logger.debug(
+                        "Parsed string patient_dob '%s' to aware datetime: %s",
+                        dob,
+                        aware_dob,
+                    )
                 else:
-                    logger.warning("Could not parse patient_dob string '%s', removing from data", dob)
+                    logger.warning(
+                        "Could not parse patient_dob string '%s', removing from data",
+                        dob,
+                    )
                     selected_data.pop("patient_dob", None)
             except Exception as e:
-                logger.warning("Error parsing patient_dob string '%s': %s, removing from data", dob, e)
+                logger.warning(
+                    "Error parsing patient_dob string '%s': %s, removing from data",
+                    dob,
+                    e,
+                )
                 selected_data.pop("patient_dob", None)
     # --- End Conversion ---
-    
+
     # Similar validation for examination_date
     exam_date = selected_data.get("examination_date")
     if isinstance(exam_date, str):
-        if exam_date == "examination_date" or exam_date in ["patient_first_name", "patient_last_name", "patient_dob"]:
-            logger.warning("Skipping invalid examination_date value '%s' - appears to be field name", exam_date)
+        if exam_date == "examination_date" or exam_date in [
+            "patient_first_name",
+            "patient_last_name",
+            "patient_dob",
+        ]:
+            logger.warning(
+                "Skipping invalid examination_date value '%s' - appears to be field name",
+                exam_date,
+            )
             selected_data.pop("examination_date", None)
         else:
             # Try to parse as date string
             try:
                 # First try simple ISO format for YYYY-MM-DD
-                if len(exam_date) == 10 and exam_date.count('-') == 2:
+                if len(exam_date) == 10 and exam_date.count("-") == 2:
                     try:
                         from datetime import datetime as dt
-                        parsed_date = dt.strptime(exam_date, '%Y-%m-%d').date()
+
+                        parsed_date = dt.strptime(exam_date, "%Y-%m-%d").date()
                         selected_data["examination_date"] = parsed_date
-                        logger.debug("Parsed ISO examination_date '%s' to date: %s", exam_date, parsed_date)
+                        logger.debug(
+                            "Parsed ISO examination_date '%s' to date: %s",
+                            exam_date,
+                            parsed_date,
+                        )
                     except ValueError:
                         # Fall back to dateparser for complex formats
                         import dateparser
-                        parsed_date = dateparser.parse(exam_date, languages=['de'], settings={'DATE_ORDER': 'DMY'})
+
+                        parsed_date = dateparser.parse(
+                            exam_date, languages=["de"], settings={"DATE_ORDER": "DMY"}
+                        )
                         if parsed_date:
                             selected_data["examination_date"] = parsed_date.date()
-                            logger.debug("Parsed string examination_date '%s' to date: %s", exam_date, parsed_date.date())
+                            logger.debug(
+                                "Parsed string examination_date '%s' to date: %s",
+                                exam_date,
+                                parsed_date.date(),
+                            )
                         else:
-                            logger.warning("Could not parse examination_date string '%s', removing from data", exam_date)
+                            logger.warning(
+                                "Could not parse examination_date string '%s', removing from data",
+                                exam_date,
+                            )
                             selected_data.pop("examination_date", None)
                 else:
                     # Use dateparser for non-ISO formats
                     import dateparser
-                    parsed_date = dateparser.parse(exam_date, languages=['de'], settings={'DATE_ORDER': 'DMY'})
+
+                    parsed_date = dateparser.parse(
+                        exam_date, languages=["de"], settings={"DATE_ORDER": "DMY"}
+                    )
                     if parsed_date:
                         selected_data["examination_date"] = parsed_date.date()
-                        logger.debug("Parsed string examination_date '%s' to date: %s", exam_date, parsed_date.date())
+                        logger.debug(
+                            "Parsed string examination_date '%s' to date: %s",
+                            exam_date,
+                            parsed_date.date(),
+                        )
                     else:
-                        logger.warning("Could not parse examination_date string '%s', removing from data", exam_date)
+                        logger.warning(
+                            "Could not parse examination_date string '%s', removing from data",
+                            exam_date,
+                        )
                         selected_data.pop("examination_date", None)
             except Exception as e:
-                logger.warning("Error parsing examination_date string '%s': %s, removing from data", exam_date, e)
+                logger.warning(
+                    "Error parsing examination_date string '%s': %s, removing from data",
+                    exam_date,
+                    e,
+                )
                 selected_data.pop("examination_date", None)
 
-    # Handle Center
+    # Handle Center - accept both center_name (string) and center (object)
+    from ..administration import Center
+
+    center = data.get("center")  # First try direct Center object
     center_name = data.get("center_name")
-    if not center_name:
-        raise ValueError("center_name is required in data dictionary.")
-    try:
-        center = Center.objects.get_by_natural_key(center_name)
+
+    if center is not None:
+        # Center object provided directly - validate it's a Center instance
+        if not isinstance(center, Center):
+            raise ValueError(f"'center' must be a Center instance, got {type(center)}")
         selected_data["center"] = center
-    except Center.DoesNotExist as exc:
-        raise ValueError(f"Center with name '{center_name}' does not exist.") from exc
+    elif center_name:
+        # center_name string provided - resolve to Center object
+        try:
+            center = Center.objects.get(name=center_name)
+            selected_data["center"] = center
+        except Center.DoesNotExist:
+            raise ValueError(f"Center with name '{center_name}' does not exist.")
+    else:
+        # Neither center nor center_name provided
+        raise ValueError(
+            "Either 'center' (Center object) or 'center_name' (string) is required in data dictionary."
+        )
 
     # Handle Names and Gender
     first_name = selected_data.get("patient_first_name") or DEFAULT_UNKNOWN_NAME
     last_name = selected_data.get("patient_last_name") or DEFAULT_UNKNOWN_NAME
-    selected_data["patient_first_name"] = first_name # Ensure defaults are set
+    selected_data["patient_first_name"] = first_name  # Ensure defaults are set
     selected_data["patient_last_name"] = last_name
 
     patient_gender_input = selected_data.get("patient_gender")
@@ -432,22 +666,34 @@ def create_sensitive_meta_from_dict(cls: Type["SensitiveMeta"], data: Dict[str,
     elif isinstance(patient_gender_input, str):
         # Input is a string (gender name)
         try:
-            selected_data["patient_gender"] = Gender.objects.get(name=patient_gender_input)
+            selected_data["patient_gender"] = Gender.objects.get(
+                name=patient_gender_input
+            )
         except Gender.DoesNotExist:
-            logger.warning(f"Gender with name '{patient_gender_input}' provided but not found. Attempting to guess or use default.")
+            logger.warning(
+                f"Gender with name '{patient_gender_input}' provided but not found. Attempting to guess or use default."
+            )
             # Fall through to guessing logic if provided string name is invalid
-            patient_gender_input = None # Reset to trigger guessing
-    
-    if not isinstance(selected_data.get("patient_gender"), Gender): # If not already a Gender object (e.g. was None, or string lookup failed)
+            patient_gender_input = None  # Reset to trigger guessing
+
+    if not isinstance(
+        selected_data.get("patient_gender"), Gender
+    ):  # If not already a Gender object (e.g. was None, or string lookup failed)
         gender_name_to_use = guess_name_gender(first_name)
         if not gender_name_to_use:
-            logger.warning(f"Could not guess gender for name '{first_name}'. Setting Gender to unknown.")
+            logger.warning(
+                f"Could not guess gender for name '{first_name}'. Setting Gender to unknown."
+            )
             gender_name_to_use = "unknown"
         try:
-            selected_data["patient_gender"] = Gender.objects.get(name=gender_name_to_use)
+            selected_data["patient_gender"] = Gender.objects.get(
+                name=gender_name_to_use
+            )
         except Gender.DoesNotExist:
             # This should ideally not happen if "unknown" gender is guaranteed to exist
-            raise ValueError(f"Default or guessed gender '{gender_name_to_use}' does not exist in Gender table.")
+            raise ValueError(
+                f"Default or guessed gender '{gender_name_to_use}' does not exist in Gender table."
+            )
 
     # Update name DB
     update_name_db(first_name, last_name)
@@ -456,32 +702,105 @@ def create_sensitive_meta_from_dict(cls: Type["SensitiveMeta"], data: Dict[str,
     sensitive_meta = cls(**selected_data)
 
     # Call save once at the end. This triggers the custom save logic.
-    sensitive_meta.save() # This will call perform_save_logic internally
+    sensitive_meta.save()  # This will call perform_save_logic internally
 
     return sensitive_meta
 
 
-def update_sensitive_meta_from_dict(instance: "SensitiveMeta", data: Dict[str, Any]) -> "SensitiveMeta":
-    """Logic to update a SensitiveMeta instance from a dictionary."""
-    field_names = {f.name for f in instance._meta.get_fields() if not f.is_relation or f.one_to_one or (f.many_to_one and f.related_model)}
+def update_sensitive_meta_from_dict(
+    instance: "SensitiveMeta", data: Dict[str, Any]
+) -> "SensitiveMeta":
+    """
+    Updates a SensitiveMeta instance from a dictionary of new values.
+
+    **Integration with two-phase save pattern:**
+    This function is typically called after initial SensitiveMeta creation when real
+    patient data becomes available (e.g., extracted from video OCR, PDF parsing, or
+    manual annotation).
+
+    **Example workflow:**
+    ```python
+    # Phase 1: Initial creation with defaults
+    sm = SensitiveMeta.create_from_dict({"center": center})
+    # → patient_first_name = "unknown", hash = sha256("unknown...")
+
+    # Phase 2: Update with extracted data
+    extracted = {
+        "patient_first_name": "Max",
+        "patient_last_name": "Mustermann",
+        "patient_dob": date(1985, 3, 15)
+    }
+    update_sensitive_meta_from_dict(sm, extracted)
+    # → Sets: sm.patient_first_name = "Max", sm.patient_last_name = "Mustermann"
+    # → Calls: sm.save()
+    # → Triggers: perform_save_logic() again
+    # → Result: Hash recalculated with real data, new pseudo-entities created
+    ```
+
+    **Key behaviors:**
+    - Updates instance attributes from provided dictionary
+    - Handles type conversions (date strings → date objects, gender strings → Gender objects)
+    - Tracks patient name changes to update name database
+    - Calls save() at the end, triggering full save logic including hash recalculation
+    - Default-setting in perform_save_logic() is skipped (fields already populated)
+
+    Args:
+        instance: The existing SensitiveMeta instance to update
+        data: Dictionary of field names and new values
+
+    Returns:
+        The updated SensitiveMeta instance
+
+    Raises:
+        Exception: If save fails or required conversions fail
+    """
+    field_names = {
+        f.name
+        for f in instance._meta.get_fields()
+        if not f.is_relation or f.one_to_one or (f.many_to_one and f.related_model)
+    }
     # Exclude FKs that should not be updated directly from dict keys (handled separately or via save logic)
-    excluded_fields = {'pseudo_patient', 'pseudo_examination'}
-    selected_data = {k: v for k, v in data.items() if k in field_names and k not in excluded_fields}
+    excluded_fields = {"pseudo_patient", "pseudo_examination"}
+    selected_data = {
+        k: v for k, v in data.items() if k in field_names and k not in excluded_fields
+    }
 
-    # Handle potential Center update
+    # Handle potential Center update - accept both center_name (string) and center (object)
+    from ..administration import Center
+
+    center = data.get("center")  # First try direct Center object
     center_name = data.get("center_name")
-    if center_name:
+
+    if center is not None:
+        # Center object provided directly - validate and update
+        if isinstance(center, Center):
+            instance.center = center
+            logger.debug(f"Updated center from Center object: {center.name}")
+        else:
+            logger.warning(
+                f"Invalid center type {type(center)}, expected Center instance. Ignoring."
+            )
+        # Remove from selected_data to prevent override
+        selected_data.pop("center", None)
+    elif center_name:
+        # center_name string provided - resolve to Center object
         try:
-            center = Center.objects.get_by_natural_key(center_name)
-            instance.center = center # Update center directly
-        except Center.DoesNotExist as exc:
-            logger.warning(f"Center '{center_name}' not found during update. Keeping existing center.")
-            selected_data.pop('center', None) # Remove from dict if not found
+            center_obj = Center.objects.get(name=center_name)
+            instance.center = center_obj
+            logger.debug(f"Updated center from center_name string: {center_name}")
+        except Center.DoesNotExist:
+            logger.warning(
+                f"Center '{center_name}' not found during update. Keeping existing center."
+            )
+    else:
+        # Both are None/missing - remove 'center' from selected_data to preserve existing value
+        selected_data.pop("center", None)
+    # If both are None/missing, keep existing center (no update needed)
 
     # Set examiner names if provided, before calling save
     examiner_first_name = data.get("examiner_first_name")
     examiner_last_name = data.get("examiner_last_name")
-    if examiner_first_name is not None: # Allow setting empty strings
+    if examiner_first_name is not None:  # Allow setting empty strings
         instance.examiner_first_name = examiner_first_name
     if examiner_last_name is not None:
         instance.examiner_last_name = examiner_last_name
@@ -495,10 +814,14 @@ def update_sensitive_meta_from_dict(instance: "SensitiveMeta", data: Dict[str, A
             elif isinstance(patient_gender_input, str):
                 gender_input_clean = patient_gender_input.strip()
                 # Try direct case-insensitive DB lookup first
-                gender_obj = Gender.objects.filter(name__iexact=gender_input_clean).first()
+                gender_obj = Gender.objects.filter(
+                    name__iexact=gender_input_clean
+                ).first()
                 if gender_obj:
                     selected_data["patient_gender"] = gender_obj
-                    logger.debug(f"Successfully matched gender string '{patient_gender_input}' to Gender object via iexact lookup")
+                    logger.debug(
+                        f"Successfully matched gender string '{patient_gender_input}' to Gender object via iexact lookup"
+                    )
                 else:
                     # Use mapping helper for fallback
                     mapped = _map_gender_string_to_standard(gender_input_clean)
@@ -506,95 +829,177 @@ def update_sensitive_meta_from_dict(instance: "SensitiveMeta", data: Dict[str, A
                         gender_obj = Gender.objects.filter(name__iexact=mapped).first()
                         if gender_obj:
                             selected_data["patient_gender"] = gender_obj
-                            logger.info(f"Mapped gender '{patient_gender_input}' to '{mapped}' via fallback mapping")
+                            logger.info(
+                                f"Mapped gender '{patient_gender_input}' to '{mapped}' via fallback mapping"
+                            )
                         else:
-                            logger.warning(f"Mapped gender '{patient_gender_input}' to '{mapped}', but no such Gender in DB. Trying 'unknown'.")
-                            unknown_gender = Gender.objects.filter(name__iexact='unknown').first()
+                            logger.warning(
+                                f"Mapped gender '{patient_gender_input}' to '{mapped}', but no such Gender in DB. Trying 'unknown'."
+                            )
+                            unknown_gender = Gender.objects.filter(
+                                name__iexact="unknown"
+                            ).first()
                             if unknown_gender:
                                 selected_data["patient_gender"] = unknown_gender
-                                logger.warning(f"Using 'unknown' gender as fallback for '{patient_gender_input}'")
+                                logger.warning(
+                                    f"Using 'unknown' gender as fallback for '{patient_gender_input}'"
+                                )
                             else:
-                                logger.error(f"No 'unknown' gender found in database. Cannot handle gender '{patient_gender_input}'. Skipping gender update.")
+                                logger.error(
+                                    f"No 'unknown' gender found in database. Cannot handle gender '{patient_gender_input}'. Skipping gender update."
+                                )
                                 selected_data.pop("patient_gender", None)
                     else:
                         # Last resort: try to get 'unknown' gender
-                        unknown_gender = Gender.objects.filter(name__iexact='unknown').first()
+                        unknown_gender = Gender.objects.filter(
+                            name__iexact="unknown"
+                        ).first()
                         if unknown_gender:
                             selected_data["patient_gender"] = unknown_gender
-                            logger.warning(f"Using 'unknown' gender as fallback for '{patient_gender_input}' (no mapping)")
+                            logger.warning(
+                                f"Using 'unknown' gender as fallback for '{patient_gender_input}' (no mapping)"
+                            )
                         else:
-                            logger.error(f"No 'unknown' gender found in database. Cannot handle gender '{patient_gender_input}'. Skipping gender update.")
+                            logger.error(
+                                f"No 'unknown' gender found in database. Cannot handle gender '{patient_gender_input}'. Skipping gender update."
+                            )
                             selected_data.pop("patient_gender", None)
             else:
-                logger.warning(f"Unexpected patient_gender type {type(patient_gender_input)}: {patient_gender_input}. Skipping gender update.")
+                logger.warning(
+                    f"Unexpected patient_gender type {type(patient_gender_input)}: {patient_gender_input}. Skipping gender update."
+                )
                 selected_data.pop("patient_gender", None)
         except Exception as e:
-            logger.exception(f"Error handling patient_gender '{patient_gender_input}': {e}. Skipping gender update.")
+            logger.exception(
+                f"Error handling patient_gender '{patient_gender_input}': {e}. Skipping gender update."
+            )
             selected_data.pop("patient_gender", None)
 
     # Update other attributes from selected_data
     patient_name_changed = False
     for k, v in selected_data.items():
-        # Avoid overwriting examiner names if they were just explicitly set
-        if k not in ["examiner_first_name", "examiner_last_name"] or \
-           (k == "examiner_first_name" and examiner_first_name is None) or \
-           (k == "examiner_last_name" and examiner_last_name is None):
+        # Skip None values to avoid overwriting existing data
+        if v is None:
+            logger.debug(f"Skipping field '{k}' during update because value is None")
+            continue
 
+        # Avoid overwriting examiner names if they were just explicitly set
+        if (
+            k not in ["examiner_first_name", "examiner_last_name"]
+            or (k == "examiner_first_name" and examiner_first_name is None)
+            or (k == "examiner_last_name" and examiner_last_name is None)
+        ):
             try:
                 # --- Convert patient_dob if it's a date object ---
                 value_to_set = v
                 if k == "patient_dob":
                     if isinstance(v, date) and not isinstance(v, datetime):
-                        aware_dob = timezone.make_aware(datetime.combine(v, datetime.min.time()))
+                        aware_dob = timezone.make_aware(
+                            datetime.combine(v, datetime.min.time())
+                        )
                         value_to_set = aware_dob
-                        logger.debug("Converted patient_dob from date to aware datetime during update: %s", aware_dob)
+                        logger.debug(
+                            "Converted patient_dob from date to aware datetime during update: %s",
+                            aware_dob,
+                        )
                     elif isinstance(v, str):
                         # Handle string DOB - check if it's a field name or actual date
-                        if v == "patient_dob" or v in ["patient_first_name", "patient_last_name", "examination_date"]:
-                            logger.warning("Skipping invalid patient_dob value '%s' during update - appears to be field name", v)
+                        if v == "patient_dob" or v in [
+                            "patient_first_name",
+                            "patient_last_name",
+                            "examination_date",
+                        ]:
+                            logger.warning(
+                                "Skipping invalid patient_dob value '%s' during update - appears to be field name",
+                                v,
+                            )
                             continue  # Skip this field
                         else:
                             # Try to parse as date string
                             try:
                                 import dateparser
-                                parsed_dob = dateparser.parse(v, languages=['de'], settings={'DATE_ORDER': 'DMY'})
+
+                                parsed_dob = dateparser.parse(
+                                    v, languages=["de"], settings={"DATE_ORDER": "DMY"}
+                                )
                                 if parsed_dob:
-                                    value_to_set = timezone.make_aware(parsed_dob.replace(hour=0, minute=0, second=0, microsecond=0))
-                                    logger.debug("Parsed string patient_dob '%s' during update to aware datetime: %s", v, value_to_set)
+                                    value_to_set = timezone.make_aware(
+                                        parsed_dob.replace(
+                                            hour=0, minute=0, second=0, microsecond=0
+                                        )
+                                    )
+                                    logger.debug(
+                                        "Parsed string patient_dob '%s' during update to aware datetime: %s",
+                                        v,
+                                        value_to_set,
+                                    )
                                 else:
-                                    logger.warning("Could not parse patient_dob string '%s' during update, skipping", v)
+                                    logger.warning(
+                                        "Could not parse patient_dob string '%s' during update, skipping",
+                                        v,
+                                    )
                                     continue
                             except Exception as e:
-                                logger.warning("Error parsing patient_dob string '%s' during update: %s, skipping", v, e)
+                                logger.warning(
+                                    "Error parsing patient_dob string '%s' during update: %s, skipping",
+                                    v,
+                                    e,
+                                )
                                 continue
                 elif k == "examination_date" and isinstance(v, str):
-                    if v == "examination_date" or v in ["patient_first_name", "patient_last_name", "patient_dob"]:
-                        logger.warning("Skipping invalid examination_date value '%s' during update - appears to be field name", v)
+                    if v == "examination_date" or v in [
+                        "patient_first_name",
+                        "patient_last_name",
+                        "patient_dob",
+                    ]:
+                        logger.warning(
+                            "Skipping invalid examination_date value '%s' during update - appears to be field name",
+                            v,
+                        )
                         continue
                     else:
                         # Try to parse as date string
                         try:
                             import dateparser
-                            parsed_date = dateparser.parse(v, languages=['de'], settings={'DATE_ORDER': 'DMY'})
+
+                            parsed_date = dateparser.parse(
+                                v, languages=["de"], settings={"DATE_ORDER": "DMY"}
+                            )
                             if parsed_date:
                                 value_to_set = parsed_date.date()
-                                logger.debug("Parsed string examination_date '%s' during update to date: %s", v, value_to_set)
+                                logger.debug(
+                                    "Parsed string examination_date '%s' during update to date: %s",
+                                    v,
+                                    value_to_set,
+                                )
                             else:
-                                logger.warning("Could not parse examination_date string '%s' during update, skipping", v)
+                                logger.warning(
+                                    "Could not parse examination_date string '%s' during update, skipping",
+                                    v,
+                                )
                                 continue
                         except Exception as e:
-                            logger.warning("Error parsing examination_date string '%s' during update: %s, skipping", v, e)
+                            logger.warning(
+                                "Error parsing examination_date string '%s' during update: %s, skipping",
+                                v,
+                                e,
+                            )
                             continue
                 # --- End Conversion ---
 
                 # Check if patient name is changing
-                if k in ["patient_first_name", "patient_last_name"] and getattr(instance, k) != value_to_set:
+                if (
+                    k in ["patient_first_name", "patient_last_name"]
+                    and getattr(instance, k) != value_to_set
+                ):
                     patient_name_changed = True
-                
-                setattr(instance, k, value_to_set) # Use value_to_set
-                
+
+                setattr(instance, k, value_to_set)  # Use value_to_set
+
             except Exception as e:
-                logger.error(f"Error setting attribute '{k}' to '{v}': {e}. Skipping this field.")
+                logger.error(
+                    f"Error setting attribute '{k}' to '{v}': {e}. Skipping this field."
+                )
                 continue
 
     # Update name DB if patient names changed
@@ -617,7 +1022,7 @@ def update_sensitive_meta_from_dict(instance: "SensitiveMeta", data: Dict[str, A
 def update_or_create_sensitive_meta_from_dict(
     cls: Type["SensitiveMeta"],
     data: Dict[str, Any],
-    instance: Optional["SensitiveMeta"] = None
+    instance: Optional["SensitiveMeta"] = None,
 ) -> "SensitiveMeta":
     """Logic to update or create a SensitiveMeta instance from a dictionary."""
     # Check if the instance already exists based on unique fields
@@ -632,9 +1037,9 @@ def update_or_create_sensitive_meta_from_dict(
 def _map_gender_string_to_standard(gender_str: str) -> Optional[str]:
     """Maps various gender string inputs to standard gender names used in the DB."""
     mapping = {
-        'male': ['male', 'm', 'männlich', 'man'],
-        'female': ['female', 'f', 'weiblich', 'woman'],
-        'unknown': ['unknown', 'unbekannt', 'other', 'diverse', '']
+        "male": ["male", "m", "männlich", "man"],
+        "female": ["female", "f", "weiblich", "woman"],
+        "unknown": ["unknown", "unbekannt", "other", "diverse", ""],
     }
     gender_lower = gender_str.strip().lower()
     for standard, variants in mapping.items():