post:
  operationId: getStationOverview
  summary: Get station overview (dashboard)
  description: |
    Permission: **ADMIN, OWNER**

    Returns all data for the Overview tab of the Station Detail page (AC-61).
    Includes live power flows, energy statistics (today + overall), device
    summary, energy distribution chart (default: Day view, T-14 to T-1),
    and emission metrics.

    > `null` values → UI displays `"-"`. Zero `0` → display `"0 kWh"` or `"0"`.
    > Empty `data_points` array → UI displays `"No data available for the selected period."`

    **Error codes:**
    | Code     | Condition |
    |----------|-----------|
    | `110501` | Unauthorized (role is not Owner or Admin) |
    | `110502` | Station not found |
    | `110503` | Invalid request (`station_id` missing or invalid) |
    | `100501` | Internal server error |
  tags: [station]
  security:
    - bearerAuth: []
  requestBody:
    required: true
    content:
      application/json:
        schema:
          $ref: "../../components.yaml#/components/schemas/GetStationOverviewRequest"
        example:
          station_id: "665f0c2df1a2b3c4d5e6f789"
  responses:
    "200":
      description: Station overview returned directly.
      content:
        application/json:
          schema:
            $ref: "../../components.yaml#/components/schemas/GetStationOverviewResponse"
          example:
            live_flow:
              solar_generated_w: 4200.5
              home_consumption_w: 1800.0
              grid_export_w: 1500.0
              grid_import_w: null
              battery_soc_pct: 78.5
              battery_power_w: 900.0
              battery_status: "charging"
            statistics:
              today:
                energy_generated_kwh: 32.5
                energy_consumed_kwh: 18.2
                energy_charged_kwh: 9.1
                energy_sold_kwh: 5.2
              overall:
                energy_generated_kwh: 12500.0
                energy_consumed_kwh: 8900.0
                energy_charged_kwh: 2100.0
                energy_sold_kwh: 1500.0
            device_summary:
              total: 12
              device_groups:
                - device_type: "solar_panel"
                  connected: 4
                  disconnected: 1
                - device_type: "battery"
                  connected: 2
                  disconnected: 0
                - device_type: "inverter_converter"
                  connected: 3
                  disconnected: 1
                - device_type: "dtu"
                  connected: 1
                  disconnected: 0
                - device_type: "other"
                  connected: 0
                  disconnected: 0
            energy_chart:
              view: "day"
              date_from: "2026-06-04"
              date_to: "2026-06-17"
              data_points:
                - timestamp: "2026-06-04"
                  solar_pv_kw: 5.2
                  consumption_kw: 3.1
                  battery_kw: 1.5
                  grid_kw: -0.4
                  soc_pct: 65.0
            emission:
              coal_saved_tons: 1.23
              co2_avoided_tons: 2.48
              trees_planted: 113.9
              data_source: "supplier"
    "400":
      $ref: "../../components.yaml#/components/responses/Failure"
    "401":
      $ref: "../../components.yaml#/components/responses/Failure"
    "404":
      $ref: "../../components.yaml#/components/responses/Failure"
    "500":
      $ref: "../../components.yaml#/components/responses/Failure"