?&j;ZUdZddlmZddlZddlmZmZmZmZm Z m Z  ddlm Z ddlmZmZmZmZe r ddlmZddlmZGd d e ZGd d e ZGd de ZeeefZdZded<idddddddddddddddddd d!dd"dd#dd$d%d&dd'd(d)dd*d(d+dd,d-d.dd/d-d0dd1dd2dd3dd4dd5d6d7dd8d d9dd:d;ddZd?ed@<dAdBdZdOdCZ dPdDZ!dQdEZ"dRdFZ#dSdGZ$dTdHZ%dUdIZ&dVdJZ' dWdKZ(dXdLZ)dYdMZ*dZdNZ+y#e $r ddl m Z YwxYw)[u alloggiati/transformer.py ========================= Single source of truth transformation layer between the internal Django Guest model and the Alloggiati Web API payload format. This module is a PURE transformation layer: - No database writes - No API calls - No logging of sensitive data (document numbers, names) - No modifications to models or serializers Design notes ------------ - get_field_value() is used for EVERY guest-originating field that may exist in extra_data. This ensures the extra_data override rule is applied consistently across all fields, not just some. - Normalization (country codes, document type codes, gender) happens BEFORE the post-normalization validation step. This is intentional: we must know the normalized value to determine whether it is valid. Validating the raw value first would allow invalid raw strings to pass the presence check and then silently corrupt the payload. - normalize_country_code() and normalize_document_type() return "" on failure (not the raw input). This is a deliberate strict policy: leaking a human- readable string like "United States" or "random document" into the payload would cause silent rejection by the Alloggiati portal with no actionable error. Returning "" causes the post-normalization validation to fire with a specific reason code instead. - Identity validation (first_name + last_name) is handled separately from _REQUIRED_OUTPUT_FIELDS because the system intentionally allows a single- word name where first_name is "" and last_name is the full name. Including first_name/last_name in _REQUIRED_OUTPUT_FIELDS would incorrectly reject valid single-name guests. Field mapping notes (actual model vs. original spec assumptions): - booking.reference_code → does not exist; mapped to booking.uid (UUID) - booking.structure.external_id → does not exist; mapped to booking.structure.istat_code (the Alloggiati/ISTAT structure identifier) Usage: from alloggiati.transformer import to_alloggiati_guest, transform_booking_guests ) annotationsN)AnyDictListOptionalTuple TYPE_CHECKING) TypedDict) _safe_strnormalize_gendernormalize_country_codenormalize_document_type)Guest)BookingceZdZUded<ded<ded<ded<ded<ded<ded<ded <ded <ded <ded <d ed<d ed<ded<y)AlloggiatiPayloadstr first_name last_namegender date_of_birthplace_of_birth_cityplace_of_birth_country nationality document_typedocument_numberdocument_issuing_countrybooking_reference Optional[str] arrival_datedeparture_date structure_idN__name__ __module__ __qualname____annotations__"/backend/alloggiati/transformer.pyrrIsSON K!!!!r)rc"eZdZUded<ded<y) ValidResultboolvalidrdataNr#r(r)r*r,r,Zs K r)r,c"eZdZUded<ded<y) InvalidResultr-r.rreasonNr#r(r)r*r1r1_s K Kr)r1)rrrrrr"rzTuple[str, ...]_REQUIRED_OUTPUT_FIELDSmissing_id_number id_numberzDocument number is required.)fieldmessagemissing_date_of_birthrzDate of birth is required.missing_nationalityrzNationality is required.missing_document_typerzDocument type is required. missing_document_issuing_countryrz%Document issuing country is required.invalid_date_formatz8Date of birth is not a valid date (expected YYYY-MM-DD).missing_identity full_namezBGuest name is required (first name or last name must be provided).missing_booking_relationbookingz!Guest is not linked to a booking.missing_booking_uidzBooking reference is missing.missing_structure structurez%Booking is not linked to a structure.missing_structure_istat_codez'Structure ISTAT code is not configured.invalid_nationality_codezENationality could not be resolved to a valid Alloggiati country code.invalid_document_typezWDocument type is not recognised. Use a standard type such as Passport or Identity Card.invalid_birth_countrycountry_of_birthzJCountry of birth could not be resolved to a valid Alloggiati country code. invalid_document_issuing_countryzRDocument issuing country could not be resolved to a valid Alloggiati country code.incomplete_payloadpayloadz>One or more required fields are missing from the guest record.final_validation_failedzHGuest record failed final validation. Please review all required fields.zDict[str, Dict[str, str]]_REASON_MESSAGESunknownz(An unexpected validation error occurred.cHttj|tS)u Convert an internal reason code to a staff-readable {field, message} dict. Never raises — unknown codes produce a safe fallback message. Never exposes raw field values, credentials, or stack traces. )dictrMget_FALLBACK_ERROR)r2s r*reason_to_errorrSs  $$V_= >>r)c|r|jsy|jj}t|dk(rd|dfS|ddj|ddfS)u Parse a full name string into (first_name, last_name). Rules: - Strips surrounding whitespace. - Two or more tokens: first token → first_name, remainder → last_name. - Exactly one token: first_name = "", last_name = that token. - Empty / whitespace-only: returns ("", ""). Args: full_name: Raw full name string from Guest.full_name. Returns: Tuple of (first_name, last_name), both stripped strings. )rUrUr N)stripsplitlenjoin)r>partss r*split_full_namer]s_ IOO- OO  # # %E 5zQE!H~ !HchhuQRy) **r)crt|ddxsi}|j|}||dk7r|St||dS)u Retrieve a guest field value applying the extra_data override rule. Priority: 1. extra_data[field_name] — if present and non-empty (not None, not ""). 2. getattr(guest, field_name) — model field fallback. 3. None — if neither source has the field. This function MUST be used for every guest-originating field that may exist in extra_data. Using getattr() directly would bypass the override rule and produce inconsistent behaviour when guests submit data via the check-in form (which stores values in extra_data). Args: guest: Guest model instance. field_name: Name of the field to retrieve. Returns: The resolved value, or None if not found in either source. extra_dataNrU)getattrrQ)guest field_namer_ extra_values r*get_field_valuerdsG*") d!C!IrJ..,K;"#4 5*d ++r)ct|ddxsi}|jdxsdj}|jdxsdj}|r|r||fStt|ddxsd\}}|r|n|}|r|n|}||fS)ab Resolve first_name and last_name using the priority chain: 1. extra_data.first_name / extra_data.last_name (if non-empty) 2. Parsed Guest.full_name 3. Empty strings as final fallback (caller must validate) Args: guest: Guest model instance. Returns: Tuple of (first_name, last_name), both stripped. r_NrrUrr>)r`rQrXr])rar_ extra_first extra_last parsed_first parsed_lastrrs r*_resolve_identityrj"s") d!C!IrJ"|4:AACK!~~k28b??AJzZ(( /{B0O0USU VL+ +J( kI  ""r)c|yt|tjtjfr|jddfSt|tr`|j }|syt |dkry|dd} tjj|}|jd|k7ry|dfSy#t$rYywxYw)uk Strictly parse and validate a date value into "YYYY-MM-DD" format. Accepts: - datetime.date / datetime.datetime objects → always valid - Strings in "YYYY-MM-DD" format with a valid calendar date Rejects: - Strings that are not valid ISO dates ("2026-99-99", "abc", "") - None → treated as missing, not invalid (returns None, True) Args: value: Raw date value. Returns: (formatted_str, True) — valid date (None, True) — value was None/missing (caller decides) (None, False) — value present but malformed N)NTz%Y-%m-%dT )NF) isinstancedatetimedatestrftimerrXrZ fromisoformat ValueError)valuestripped date_partparseds r*_parse_date_strictrwDs( }%(--):):;<z*D11%;;= x=2  SbM  !]]00;F ??: &) 3 4   !  !s9B22 B>=B>cgd}|D]8\}}t||}|"t|ts%|jr6|cSt|d}t |\}}|syy)uJ Validate presence of required guest-level fields BEFORE normalization. Uses get_field_value() for all fields so that extra_data overrides are respected during validation — the same source used during payload assembly. This prevents the mismatch where validation passes on the model field but payload assembly uses a different (extra_data) value. Required fields: document_number → "missing_id_number" date_of_birth → "missing_date_of_birth" nationality → "missing_nationality" document_type → "missing_document_type" Date format is also validated here: date_of_birth must be a valid ISO date → "invalid_date_format" Args: guest: Guest model instance. Returns: None if all fields pass, or a reason string on the first failure. )rr4)rr8)rr9)rr:)rr;Nrr<)rdrmrrXrw)rascalar_requiredr6r2rawdob_raw_ date_valids r*_validate_guest_fieldsryse0.O) veU+ ;:c3/ M) e_5G&w/MAz $ r)cg}t|\}}|js*|js|jtdgd}d}|D]W\}}t ||}|"t |t s%|jr6|jt||dk(sVd}Y|s6t |d} t| \} } | s|jtdt|dd} t| } | r|jt| |Stt |d xsd}|r't|}|s|jtd tt |d xsd}|r't|}|s|jtd tt |d xsd}|r't|}|s|jtd|S)a Collect ALL validation errors for a guest in a single pass. Unlike _validate_guest_fields() which stops at the first failure, this function checks every required field and returns the complete list of problems. This is used by the service layer to build structured, staff-readable error reports. Validation order mirrors the transformer pipeline: 1. Identity (name) 2. Required scalar fields (document_number, date_of_birth, nationality, document_type, document_issuing_country) 3. Date format for date_of_birth 4. Booking + structure references 5. Post-normalization checks (nationality code, document type code, document_issuing_country code) Args: guest: Guest model instance. Returns: List of {"field": str, "message": str} dicts. Empty list means the guest is fully valid. Never raises. r=ryFNrTr<r@rrErrFrrI) rjrXappendrSrdrmrrwr`_validate_booking_fieldsr r r)raerrorsrr scalar_checks missing_dobrb reason_coder{r|r}r~r@booking_reasonraw_nationalitynorm_nat raw_doc_typenorm_doc raw_issuing norm_issuings r*collect_guest_validation_errorsrs4$&F.e4J    ioo&7 o&89:,MK#0 KeZ0 ;:c3/ MM/+6 7_," $1 !%9*73 : MM/*?@ AeY-G-g6N on56  } EFN$O)/: MM/*DE F_UODEML*<8 MM/*AB COE3MNOWSWK-k:  MM/*LM N Mr)c|yt|dd}|t|jdk(ryt|dd}|yt|dd}|t|jdk(ry y) u" Validate required booking- and structure-level fields. Checks (fails on first error): booking exists → "missing_booking_relation" booking.uid non-empty → "missing_booking_uid" booking.structure exists → "missing_structure" booking.structure.istat_code non-empty → "missing_structure_istat_code" Args: booking: Booking model instance (or None). Returns: None if all fields pass, or a reason string on the first failure. Nr?uidrUrArCrB istat_coderD)r`rrX)r@rrCrs r*rrsy ) '5$ 'C {c#hnn&",$d3I"L$7JS_224:- r)c|sy|syy)u Validate that normalization produced non-empty coded values for required fields. This step runs AFTER normalization. It is necessary because a field can pass the presence check in _validate_guest_fields() (e.g. "Mars" is a non-empty string) but then fail normalization (normalize_country_code returns "" for an unrecognised value). Without this step, an invalid raw value would silently produce an empty field in the payload. Required to be non-empty after normalization: nationality → "invalid_nationality_code" document_type → "invalid_document_type" Optional fields (empty is allowed — not all guests have these): place_of_birth_country → "invalid_birth_country" (only if non-empty raw) document_issuing_country → "invalid_document_issuing_country" (only if non-empty raw) Note: place_of_birth_country and document_issuing_country are validated only when the caller passes a non-empty string, indicating the raw value was present but failed normalization. Args: nationality: Normalized nationality code (or ""). document_type: Normalized document type code (or ""). place_of_birth_country: Normalized birth country code (or ""). document_issuing_country: Normalized issuing country code (or ""). Returns: None if all checks pass, or a reason string on the first failure. rErFNr(rrrrs r*_validate_normalized_fieldsr-sJ ) & r)ct|jd}t|jd}|s|sytD] }|j|}t|r yd}|D]}t|j|ryy)u  Final safety gate: ensure every required output field is non-empty. Checks _REQUIRED_OUTPUT_FIELDS (which intentionally excludes first_name and last_name — identity is validated separately). Also enforces that at least one of first_name / last_name is non-empty. Args: payload: The assembled AlloggiatiPayload dict. Returns: None if the payload passes all checks. "missing_identity" — both first_name and last_name are empty. "incomplete_payload" — a required field is empty/missing. "final_validation_failed" — a critical field subset is empty (document_number, document_type, structure_id, booking_reference). rrr=rJ)rrr"rrLN)r rQr3)rKfirstlastr6rscriticals r*_final_payload_guardrgs* gkk,/ 0E W[[- .D !) E"') YHU+,, r)ct|}|rd|dSt|\}}|js|jsdddSt|dd}t |}|rd|dS|j }t |d}t|\}} | r|dddStt|dd\} } | sdddStt|d d\} } | sdddSttt |d xsd}ttt |d xsd}ttt |d xsd}ttt |d xsd}tt |d}t||||}|rd|dS||||tt |d|||tt |d|t|j| | t|jd}t|}|rd|dSd|dS)u) Transform a single Guest instance into an Alloggiati Web payload dict. Validation + transformation pipeline (fails fast on first error): STEP 1 — Pre-normalization field presence check Ensures required raw fields exist before we attempt normalization. Uses get_field_value() so extra_data overrides are respected. STEP 2 — Identity resolution Resolves first_name / last_name from extra_data or full_name. STEP 3 — Booking + structure validation Checks uid, structure, istat_code. STEP 4 — Strict date parsing Validates date_of_birth, check_in_date, check_out_date. Uses get_field_value() for date_of_birth to match STEP 1. STEP 5 — Normalization Converts raw values to ISTAT coded values. All guest fields use get_field_value() for consistent extra_data override behaviour. STEP 6 — Post-normalization validation Ensures normalization produced non-empty coded values for required fields. Catches cases where a field was present but unrecognised (e.g. nationality="Mars"). STEP 7 — Final payload guard Last-resort check that no required output field is empty. Args: guest: Guest model instance with a related Booking and Structure. Returns: {"valid": True, "data": AlloggiatiPayload} on success. {"valid": False, "reason": str} on any validation failure. F)r.r2r=r@Nrr< check_in_datecheck_out_daterrHrrrrplace_of_birthr)rrrrrrrrrrrr r!r"T)r.r/)rrjrXr`rrCrdrwr r rr rrrr)ra field_errorrrr@ booking_errorrCr|dob_str dob_valid arrival_str arrival_valid departure_strdeparture_validnorm_nationalitynorm_country_of_birthnorm_doc_issuing_countrynorm_document_type norm_gender norm_errorrK guard_errors r*to_alloggiati_guestrsRZ)/K+66 .e4J    ioo&7*<== eY-G,W5M-88!!I e_5G+G4GY *?@@!3$/"K *?@@%7)40&"M? *?@@./%78@D3/%);<=E 6/%)CDEM 1/%9:Bd#?5(#CDK-$(4!9 J *55 $.#,#.#*#,_UDT-U#V#8#3#5#,_UDU-V#W$<#,W[[#9#.#0#,Y-A-A#BG('w/K+667 ++r)c |g}g}t|dd}|jjD]}t|}|j dr|j |d4t |}tt|ddxsd}|j t|dd|||j dd |d ||d S) um Transform all guests associated with a booking. Iterates booking.guests.all(), applies to_alloggiati_guest() to each, and separates results into valid and invalid buckets. For invalid guests, collect_guest_validation_errors() is called to produce the full structured error list (all fields, not just the first). Country normalization is O(1) per call — the snapshot is an immutable in-memory dict loaded once at startup. Document type lookups are cached via lru_cache for the process lifetime. No N+1 DB queries occur. Args: booking: Booking model instance with a prefetchable guests relation. Returns: { "valid": [AlloggiatiPayload, ...], "invalid": [ { "guest_id": int, "booking_id": int, "guest_name": str, # display name only, no doc numbers "reason": str, # legacy single-reason code "errors": [{"field": str, "message": str}, ...], }, ... ], } idNr.r/r>rUz Unknown Guestr2 unknown_error)guest_id booking_id guest_namer2r)r.invalid)r`guestsallrrQrrr )r@valid_payloadsinvalid_recordsrraresultstructured_errorsrs r*transform_booking_guestsr0s@/1N,.O$-J##%$U+ ::g   ! !&. 1!@ F #75+r#BCVJ  " "")%t"<",","(**X"G"3  &."" r))r2rreturnzDict[str, str])r>rrTuple[str, str])ra'Guest'rbrrr)rarrr)rsrrzTuple[Optional[str], bool])rarrr)rarrzList[Dict[str, str]])r@rrr) rrrrrrrrrr)rKzDict[str, Any]rr)rarrTransformResult)r@z 'Booking'rzDict[str, List[Any]]),__doc__ __future__rrntypingrrrrrr r ImportErrortyping_extensionsalloggiati.normalizersr r r r guests.modelsrbookings.modelsrrr,r1rrr3r'rMrRrSr]rdrjrwrrrrrrrr(r)r*rs,\#BB, #' ") I sCx.,&K/1K/ "/ K/ -K/"/K/$'+:)%K/."M/K/8W9K/B6!CK/J2KK/R:SK/Z#<%[K/d Z!eK/l"lmK/t%_uK/|'-g)}K/FSGK/N] OK/+KZ&2\]?+>,D#D.j+dUxL333 3" 3  3t&ZU,x>u,++,sD D*)D*