{
  "metadata": {
    "name": "Raumrechner Calculation Contracts",
    "version": "1.0.0",
    "generated_at": "2026-06-13",
    "status": "static_formula_contracts",
    "canonical_url": "https://raumrechner.de/api/calculation-contracts",
    "json_url": "https://raumrechner.de/api/calculation-contracts.json",
    "openapi_url": "https://raumrechner.de/openapi.yaml",
    "caveat": "Diese Datei dokumentiert die statischen Rechenlogiken. Sie ist kein serverseitiger Runtime-Rechner und ersetzt keine Normplanung, Produkttests, Live-Preise, Verfuegbarkeit oder sicherheitskritische Pruefung."
  },
  "contracts": [
    {
      "id": "light_requirement_v1",
      "human_page": "https://raumrechner.de/lichtplaner/",
      "runtime_endpoint": "https://raumrechner.de/api/lichtbedarf",
      "data_sources": [
        "https://raumrechner.de/data/products.json",
        "https://raumrechner.de/data/led-charts.json"
      ],
      "inputs": {
        "room_type": "wohnzimmer | kueche | homeoffice | flur | schlafzimmer | bad_spiegel | frei",
        "area_m2": "number",
        "usage_intensity": "gemuetlich | normal | detail",
        "wall_brightness": "hell | normal | dunkel",
        "ceiling_height_m": "number",
        "socket": "E27 | E14 | GU10 | GU5.3 | G9 | G4 | R7s | GX53 | unbekannt",
        "lamp_count": "number"
      },
      "formula": {
        "total_lumens": "area_m2 * target_lux * wall_factor * height_factor",
        "lumens_per_lamp": "total_lumens / lamp_count",
        "estimated_led_watts_range": "total_lumens / 120 bis total_lumens / 80"
      },
      "constants": {
        "wall_factor": {
          "hell": 1.0,
          "normal": 1.2,
          "dunkel": 1.5
        },
        "height_factor": "1.0 bis 2.7 m Deckenhoehe, darueber moderater Zuschlag bis ca. 1.3",
        "target_lux": {
          "wohnzimmer": {
            "gemuetlich": 100,
            "normal": 150,
            "detail": 300
          },
          "kueche": {
            "gemuetlich": 200,
            "normal": 300,
            "detail": 500
          },
          "homeoffice": {
            "gemuetlich": 300,
            "normal": 500,
            "detail": 750
          },
          "flur": {
            "gemuetlich": 75,
            "normal": 100,
            "detail": 150
          },
          "schlafzimmer": {
            "gemuetlich": 100,
            "normal": 150,
            "detail": 250
          },
          "bad_spiegel": {
            "gemuetlich": 200,
            "normal": 300,
            "detail": 500
          }
        }
      },
      "outputs": [
        "target_lux",
        "total_lumens",
        "lumens_per_lamp",
        "estimated_led_watts_range",
        "kelvin_guidance",
        "product_filter_guidance",
        "caveats"
      ]
    },
    {
      "id": "powerstation_runtime_v1",
      "human_page": "https://raumrechner.de/powerstation-rechner/",
      "runtime_endpoint": "https://raumrechner.de/api/powerstation-estimate",
      "data_sources": [
        "https://raumrechner.de/data/powerstation-products.json"
      ],
      "inputs": {
        "device_watts": "number",
        "hours_per_day": "number",
        "days_until_recharge": "number",
        "station_capacity_wh": "number",
        "reserve_percent": "number",
        "inverter_loss_factor": "number, typical 0.85 when 230V inverter is used",
        "solar_panel_wp": "number optional",
        "effective_sun_hours": "number optional"
      },
      "formula": {
        "daily_wh": "device_watts * hours_per_day",
        "required_wh_before_losses": "daily_wh * days_until_recharge",
        "required_wh_with_reserve": "required_wh_before_losses * (1 + reserve_percent / 100)",
        "usable_station_wh": "station_capacity_wh * inverter_loss_factor",
        "runtime_days": "usable_station_wh / daily_wh",
        "solar_daily_wh_estimate": "solar_panel_wp * effective_sun_hours * 0.65"
      },
      "outputs": [
        "daily_wh",
        "required_wh_with_reserve",
        "usable_station_wh",
        "runtime_days",
        "capacity_class",
        "solar_status",
        "candidate_filter_guidance",
        "caveats"
      ]
    },
    {
      "id": "cooler_powerstation_v1",
      "human_page": "https://raumrechner.de/kuehlbox-rechner/",
      "data_sources": [
        "https://raumrechner.de/data/kuehlbox-systems.json",
        "https://raumrechner.de/data/kuehlbox-products.json",
        "https://raumrechner.de/data/powerstation-products.json"
      ],
      "inputs": {
        "load_profile": "poweronly | cooler | camp | work | medical",
        "days_until_recharge": "number",
        "cooler_size": "compact | camp | family | unknown",
        "ambient_temperature": "mild | warm | hot",
        "solar_panel_wp": "number optional",
        "existing_station_wh": "number optional"
      },
      "outputs": [
        "target_capacity_class_wh",
        "daily_wh_estimate",
        "reserve_status",
        "solar_status",
        "matching_powerstation_candidates",
        "matching_cooler_candidates",
        "risk_notes"
      ],
      "caveats": [
        "Kuehlbox-Verbrauch schwankt stark nach Umgebung, Vorkuehlung, Zieltemperatur, Oeffnung und Boxtechnik.",
        "Medizinische Lasten sind nur vorsichtige Rechenbeispiele und keine Sicherheitszusage."
      ]
    },
    {
      "id": "cleaner_rule_v1",
      "human_page": "https://raumrechner.de/putzmittel-finder/",
      "runtime_endpoint": "https://raumrechner.de/api/putzmittel-rule",
      "data_sources": [
        "https://raumrechner.de/data/putzmittel-cases.json",
        "https://raumrechner.de/data/putzmittel-product-candidates.json",
        "https://raumrechner.de/data/putzmittel-official-details.json",
        "https://raumrechner.de/data/putzmittel-review-patterns.json"
      ],
      "inputs": {
        "soil": "kalk | fett | streifen | schimmel | eingebrannt | textilgeruch | renovierung | alltag",
        "surface": "fliesen | naturstein | glas | holz | laminat | edelstahl | kunststoff | textil | ceran",
        "context": "normal | kinder_haustiere | oeko_duftarm",
        "purchase_goal": "ausgewogen | mild | guenstig"
      },
      "outputs": [
        "risk_level",
        "first_cleaner_class",
        "avoid_cleaner_classes",
        "safety_warnings",
        "start_steps",
        "product_candidate_filter_guidance",
        "caveats"
      ],
      "hard_rules": [
        "Naturstein nicht mit sauren Kalkreinigern empfehlen.",
        "Chlorreiniger und Saeure nicht mischen.",
        "Schimmel groesserer oder wiederkehrender Befall als Warnfall behandeln.",
        "Etikett, Materialfreigabe und Teststelle vor Produktempfehlung nennen."
      ]
    }
  ]
}