paths:
  # ─── CreateStation ────────────────────────────────────────────────────────
  "/?ctrl=staffManagementCtl&api=createStation&ver=v1":
    post:
      operationId: createStation
      summary: Create a station
      description: |
        Permission: **ADMIN, OWNER**

        Creates a local station for a client, calls the configured provider to
        create the provider-side station, then activates the local station when
        provider creation succeeds.
      tags: [staffManagement]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "../components.yaml#/components/schemas/CreateStationRequest"
            example:
              client_id: "6656c2b3f1a2b3c4d5e6f701"
              provider_code: "GROWATT"
              station_name: "Cancun Solar Plant"
              type: "Residential"
              capacity_kwp: 12.5
              address:
                country_id: "MEX"
                state_province_id: "QR"
                city_id: "CUN"
                district: "Benito Juarez"
                street: "Av. Tulum"
                house_number: "123"
              notes: "Rooftop installation"
              created_by: "usr_staff_001"
      responses:
        "200":
          description: Station created — DTO returned directly
          content:
            application/json:
              schema:
                $ref: "../components.yaml#/components/schemas/CreateStationResponse"
              example:
                station_id: "9e5b8a7a-5a3a-4d6f-9b13-3b8e0db0f2d1"
                client_id: "6656c2b3f1a2b3c4d5e6f701"
                station_name: "Cancun Solar Plant"
                provider_code: "GROWATT"
                provider_station_id: "prov-station-999"
                provisioning_status: "ACTIVE"
        "400":
          $ref: "../components.yaml#/components/responses/ClientError"
        "403":
          $ref: "../components.yaml#/components/responses/ClientError"
        "500":
          $ref: "../components.yaml#/components/responses/ServerError"