j9 ZdZddlmZmZddlmZmZddlmZm Z m Z m Z ddl m Z ddlmZGddZd ed efd Zd ed ed ed e efdZ dde ed ed eded e ef dZ dde ed ed eded ef dZde eded eeeffdZdededed efdZdeded efdZde ed ed ed efdZy) a Dashboard metrics service for Aimantis PMS. Provides centralized, reusable calculation logic for: - Average Daily Rate (ADR) - Revenue per Available Room (RevPAR) - Other derived hospitality metrics Uses proper PMS stay-night expansion logic consistent with ISTAT, city tax, and guest night services. ORM Optimization Strategy: - NO select_related() is used because we only access property_id (FK integer), not the full property object. Traversing FK objects would be wasteful. - .only() explicitly selects the minimal fields required for calculations. - This prevents N+1 queries while avoiding Django FieldError from deferred fields. - For multi-tenant scale, structure_id filtering is applied at the DB level. )date timedelta)Decimal ROUND_HALF_UP)DictListOptionalTuple)Q)Bookingc0eZdZdZgdZdedededefdZy) StayNightRevenuez Represents revenue allocated to a single occupied room night. Immutable dataclass-like structure for tracking per-night revenue.  booking_id property_id night_daterevenuerrrrc<||_||_||_||_yNr)selfrrrrs 8/backend/dashboard/services/dashboard_metrics_service.py__init__zStayNightRevenue.__init__$s$&$ N) __name__ __module__ __qualname____doc__ __slots__intrrrrrrrs1 GI3SdU\rrbookingreturnc|jr|jdkr tdS|jxs td}tt|j}|dk(r tdS||z S)a Calculate per-night revenue for a booking using BASE PRICE only. ADR Formula: base_price / length_of_stay IMPORTANT: - Uses base_price (room revenue ONLY) - Excludes: cleaning_fee, city_tax, other_extra_fees, subtotal, total_price - This is the hospitality industry standard for ADR calculation Args: booking: Booking instance with base_price and length_of_stay Returns: Decimal per-night revenue, or Decimal('0') if invalid r0)length_of_stayr base_pricestr)r!r&r%s rcalculate_per_night_revenuer(+sl"  ! !W%;%;q%@s|##3ws|JS!7!789Ns|  &&r window_start window_endc|jr |jsgS|jsgSt|j|}t |j|}||k\rgSt |}|dkrgSg}|}||krG|j t|j|j|||tdz }||krG|S)a% Expand a single booking into individual revenue nights within a window. This is the core PMS logic that properly handles: - check_in_date is INCLUDED - check_out_date is EXCLUDED - Overlap calculation with the analysis window - Per-night revenue allocation Args: booking: Booking object window_start: Start of analysis window (inclusive) window_end: End of analysis window (exclusive) Returns: List of StayNightRevenue objects for each occupied night in window rrdays) check_in_datecheck_out_datermaxminr(appendridr)r!r)r*effective_start effective_endper_night_revenuerevenue_nights current_dates r expand_booking_to_revenue_nightsr:Is.  (>(>    '//>O.. ;M-' 4G<A N"L  & "::#//')     q))   & r structure_idonly_checked_inc t||}|r|t|z}|r|tdz}ttjj |j ddddd d d d S) af Fetch bookings overlapping a date window with proper filtering. Uses PMS overlap logic: - booking.check_in_date < window_end - booking.check_out_date > window_start Args: structure_id: Structure ID for multi-tenant filtering (None = all) window_start: Window start date (inclusive) window_end: Window end date (exclusive) only_checked_in: If True, only include is_checked_in=True bookings (legacy parameter, default=False for active-stay logic) Returns: List of Booking objects overlapping the window )check_in_date__ltcheck_out_date__gt)r;T) is_checked_inr4rr;r/r0r%r&platform)r listr objectsfilteronly)r;r)r*r<filterss rget_bookings_for_windowrGs0$'G 1,//14(($ w'            rc"t||||}|syg}|D]!}t|||}|j|#|sytd|D}t |} | dk(ry|| z } | j t dt} t| S)a Calculate Average Daily Rate (ADR) for a date window. ADR Formula (Hospitality Industry Standard): ADR = Total Room Revenue / Occupied Room Nights Where: - Total Room Revenue = SUM(base_price for all active bookings) - Occupied Room Nights = COUNT(stay nights within window) - Uses base_price ONLY (excludes cleaning fees, city tax, extra services) Business Rules: - Active stay: check_in_date <= target_date < check_out_date - Check-out day is NOT counted as occupied - Zero-division protection: returns 0.0 if no occupied nights - Result rounded to 2 decimals using ROUND_HALF_UP Args: structure_id: Structure ID for filtering (None = all structures) window_start: Window start date (inclusive) window_end: Window end date (exclusive) only_checked_in: If True, only count checked-in bookings (legacy, default=False) Returns: ADR as float rounded to 2 decimals, or 0.0 if no occupied nights r;r)r*r<r!r)r*c34K|]}|jywrr.0nights r z+calculate_adr_for_window..F3E% 3Er0.01rounding) rGr:extendsumlenquantizerrfloat) r;r)r*r<bookingsall_revenue_nightsr!r8 total_revenueoccupied_nightsadr adr_roundeds rcalculate_adr_for_windowrbsB'!!' H 249%!  !!.1  F3EFFM,-O! / )C,,wv,GK  rtodayc||tdzf||tdzf||tdzfd}i}|jD]\}\}}t|||d||<|S)ak Calculate all ADR metrics (today, 7-day, 30-day) in one optimized call. This minimizes database queries by batching booking fetches. Args: structure_id: Structure ID for filtering (None = all structures) today: Current date for calculations Returns: Dict with keys: today, next_7_days, next_30_days r,r-)rc next_7_days next_30_daysFrI)ritemsrb)r;rcwindowsresults metric_namer)r*s rcalculate_all_adr_metricsrms$!223uya'889 r(: :;GG3:==?/ /lJ7%%!!   4C Nrr/r0 target_datec"||cxkxr|kScS)a Determine if a booking is active on a specific date. Active Stay Logic (PMS Standard): - check_in_date <= target_date < check_out_date - Check-out day is EXCLUSIVE (guest leaves, room becomes available) This is a pure function with no side effects, ideal for unit testing. Args: check_in_date: Booking check-in date check_out_date: Booking check-out date target_date: Date to check activity Returns: True if booking is active on target_date, False otherwise Examples: >>> is_active_stay_on_date(date(2026, 5, 14), date(2026, 5, 19), date(2026, 5, 14)) True >>> is_active_stay_on_date(date(2026, 5, 14), date(2026, 5, 19), date(2026, 5, 19)) False # Check-out day is NOT active >>> is_active_stay_on_date(date(2026, 5, 14), date(2026, 5, 19), date(2026, 5, 13)) False # Before check-in r )r/r0rns ris_active_stay_on_daterpAs< K 8. 88 88rr_total_possible_nightsc6|dk(ry||z dz}t|dS)a Calculate occupancy percentage with defensive zero-division protection. Formula: (occupied_nights / total_possible_nights) * 100 Args: occupied_nights: Number of occupied room nights total_possible_nights: Total available room nights Returns: Occupancy percentage (0-100), rounded to 2 decimals Returns 0.0 if total_possible_nights is 0 Examples: >>> calculate_occupancy_percentage(20, 100) 20.0 >>> calculate_occupancy_percentage(0, 100) 0.0 >>> calculate_occupancy_percentage(50, 0) 0.0 # Defensive zero-division rrJd)round)r_rq occupancys rcalculate_occupancy_percentagerwbs,2! #88C?I A rr\c|syg}|D]!}t|||}|j|#|sytd|D}t|}|dk(ry||z }|j t dt } t| S)a Calculate ADR from a list of bookings within a date window. This is a pure calculation function that accepts pre-fetched bookings, making it ideal for unit testing without database dependencies. ADR Formula: ADR = SUM(base_price for occupied nights) / COUNT(occupied room nights) Args: bookings: List of Booking objects (must have base_price, length_of_stay, check_in_date, check_out_date, property_id) window_start: Window start date (inclusive) window_end: Window end date (exclusive) Returns: ADR as float rounded to 2 decimals, or 0.0 if no occupied nights Examples: >>> bookings = [MockBooking(base_price=270, length_of_stay=5, ...)] >>> calculate_adr_from_bookings(bookings, date(2026, 5, 14), date(2026, 5, 15)) 54.0 # 270 / 5 = 54 per night rJrKc34K|]}|jywrrMrNs rrQz.calculate_adr_from_bookings..rRrSrrTrU)r:rWrXrYrZrrr[) r\r)r*r]r!r8r^r_r`ras rcalculate_adr_from_bookingsrzs8 249%!  !!.1  F3EFFM,-O! / )C,,wv,GK  rN)F)rdatetimerrdecimalrrtypingrrr r django.db.modelsr bookings.modelsr rr(r:rboolrGr[rbr'rmrprwrzr rrrs&%*..#  ''W'<: :::  :B" B3-BBB B  '] BR" F3-FFF F  FR%3-% % #u*%Z9999 9B @87m888 8r