Neues Dashboard: Kostenobjekte

app/tools/helpers.py

@@ -0,0 +1,79 @@
+
+def calc_variance_pct(actual, plan):
+    """
+    Calculates the percentage variance between actual and plan values
+    for reporting purposes.
+
+    The percentage variance is only returned if it is economically
+    meaningful and interpretable:
+    - The plan value must not be zero
+    - Actual and plan must have the same sign (no sign change)
+
+    In cases where a percentage variance would be misleading
+    (e.g. sign change from loss to profit), the function returns None
+    and absolute variance should be used instead.
+
+    Parameters
+    ----------
+    actual : float | int
+        Actual (realized) value.
+    plan : float | int
+        Planned or budgeted value.
+
+    Returns
+    -------
+    float | None
+        Percentage variance relative to the absolute plan value,
+        or None if the percentage variance is not meaningful.
+    """
+
+    variance = actual - plan
+    if plan == 0:
+        return None
+    if actual * plan < 0:
+        return None
+    return variance / abs(plan)
+
+
+
+
+def display_value(value, unit):
+    """
+    Formats a numeric KPI value for reporting output based on the configured
+    display unit (e.g. €, T€, Mio. €).
+
+    - Scales the input value according to DISPLAY_UNIT
+    - Applies European number formatting (thousands separator, decimal comma)
+    - Returns 'n/a' if the input value is None
+
+    Parameters
+    ----------
+    value : float | int | None
+        Raw KPI value in base currency (e.g. EUR).
+
+    Returns
+    -------
+    str
+        Formatted value including display unit, ready for dashboard display.
+    """    
+    
+    if value is None:
+        return "n/a"
+    
+    unit_factors = {
+        "Mio. €": 1_000_000,
+        "T€": 1_000,
+        "€": 1,
+    }
+
+    factor = unit_factors.get(unit, 1)
+    scaled = value / factor
+    formatted = f"{scaled:,.2f}"
+    formatted = (
+        formatted
+        .replace(",", "X")
+        .replace(".", ",")
+        .replace("X", ".")
+    )
+    
+    return f"{formatted} {unit}"