post:
  operationId: getListStations
  summary: View station list
  description: |
    Permission: **ADMIN, OWNER**

    Returns the station management list with BA-required columns, cursor-based
    infinite loading via `last_object_id`, station-name search,
    station-name/created-date sort, and status/provider/type filters.
  tags: [station]
  security:
    - bearerAuth: []
  requestBody:
    required: false
    content:
      application/json:
        schema:
          $ref: "../../components.yaml#/components/schemas/ListStationsRequest"
        example:
          client_id: "6656c2b3f1a2b3c4d5e6f701"
          search: "Cancun"
          status: ["Active"]
          provider_code: ["growatt"]
          type: ["Residential"]
          sort_by: "created_at"
          sort_dir: "desc"
          limit: 20
          last_object_id: "665f0c2df1a2b3c4d5e6f789"
  responses:
    "200":
      description: Stations returned directly.
      content:
        application/json:
          schema:
            $ref: "../../components.yaml#/components/schemas/ListStationsResponse"
          example:
            items:
              - station_id: "9e5b8a7a-5a3a-4d6f-9b13-3b8e0db0f2d1"
                station_name: "Cancun Solar Plant"
                client_id: "6656c2b3f1a2b3c4d5e6f701"
                client_name: "Acme Solar Corp"
                provider_name: "Growatt"
                provider_code: "growatt"
                type: "Residential"
                status: "Active"
                created_at: "2026-06-02T14:30:00Z"
            total: 1
            limit: 20
            next_last_object_id: "665f0c2df1a2b3c4d5e6f789"
            has_more: false
    "400":
      $ref: "../../components.yaml#/components/responses/Failure"
    "403":
      $ref: "../../components.yaml#/components/responses/Failure"