Class: CongregaPlenum::VotingsService

Inherits:
Object
  • Object
show all
Defined in:
lib/modules/votings_service.rb,
sig/congrega_plenum.rbs

Overview

Service for voting records produced by the Chamber's Plenary and committees.

A voting is a single, finished decision. It is not the legislative event in which it occurred, and a proposition can be affected by several distinct votings of amendments, reports, requests and other related propositions. rubocop:disable Metrics/ClassLength

Constant Summary collapse

ITEMS_PER_PAGE =

Maximum page size documented for the voting list endpoints.

Returns:

  • (Integer) 
100
DEFAULT_ORDER =

Default ordering used by the official API.

Returns:

  • (String) 
'DESC'
DEFAULT_ORDER_BY =

Default field used by the official API to order voting records.

Returns:

  • (String) 
'dataHoraRegistro'
SERVICE_TAG =

Tag prefix for structured logging.

Returns:

  • (String) 
'CongregaPlenum::VotingsService'

Class Method Summary collapse

Class Method Details

.api_get(endpoint, params = {}) ⇒ payload_hash

Wraps Client#get with voting-specific logging while preserving errors.

Parameters:

  • (String)
  • (params_hash)

Returns:

  • (payload_hash) 


29
30
31
32
33
34
 
# File 'lib/modules/votings_service.rb', line 29

def api_get(endpoint, params = {})
  client.get(endpoint, params)
rescue StandardError => e
  log_error("Erro ao acessar API em #{endpoint}: #{e.message}")
  raise
end

.api_get_paginated(endpoint, params = {}) ⇒ payload_list

Paginated variant of api_get. Incomplete synchronizations are never converted into empty results.

Parameters:

  • (String)
  • (params_hash)

Returns:

  • (payload_list) 


38
39
40
41
42
43
 
# File 'lib/modules/votings_service.rb', line 38

def api_get_paginated(endpoint, params = {})
  client.get_paginated(endpoint, params)
rescue StandardError => e
  log_error("Erro paginando API em #{endpoint}: #{e.message}")
  raise
end

.client ⇒ CongregaPlenum::Client

Shared client configured through CongregaPlenum.configure.

Returns:



24
25
26
 
# File 'lib/modules/votings_service.rb', line 24

def client
  @client ||= CongregaPlenum::Client.instance
end

.fetch_all(**filters) ⇒ Array<Hash>

Retrieves all pages matching the supplied filters.

Without date or identifier filters the Câmara API limits the result to votings from the previous 30 days. When both dates are supplied they must belong to the same calendar year, as required by the upstream API.

Parameters:

  • filters (Hash) —

    a customizable set of options

Options Hash (**filters):

  • :voting_ids (String, Integer, Array<String>, Array<Integer>)
  • :proposition_ids (Integer, Array<Integer>)
  • :event_ids (Integer, Array<Integer>)
  • :body_ids (Integer, Array<Integer>) —

    identifiers from /orgaos

  • :start_date (String, Date) —

    ISO 8601 date

  • :end_date (String, Date) —

    ISO 8601 date

  • :order (String) —

    ASC or DESC

  • :order_by (String) —

    field accepted by the upstream endpoint

Returns:

  • (Array<Hash>) 


60
61
62
63
64
65
66
67
68
 
# File 'lib/modules/votings_service.rb', line 60

def fetch_all(**filters)
  log_info('Iniciando coleta de votações')

  filters[:items_per_page] = ITEMS_PER_PAGE
  votings = api_get_paginated('votacoes', list_params(filters))

  log_info("Coletamos #{votings.size} votações")
  votings
end

.fetch_by_body(body_id, proposition_ids: nil, start_date: nil, end_date: nil, order: DEFAULT_ORDER, order_by: DEFAULT_ORDER_BY) ⇒ Array<Hash>

Retrieves all voting pages for a Chamber body such as the Plenary or a committee.

rubocop:disable Metrics/ParameterLists

Parameters:

  • body_id (Integer) —

    identifier from /orgaos

  • proposition_ids (Integer, Array<Integer>, nil) (defaults to: nil)
  • start_date (String, Date, nil) (defaults to: nil)
  • end_date (String, Date, nil) (defaults to: nil)
  • order (String) (defaults to: DEFAULT_ORDER)
  • order_by (String) (defaults to: DEFAULT_ORDER_BY)

Returns:

  • (Array<Hash>) 


146
147
148
149
150
151
152
153
154
155
156
157
158
 
# File 'lib/modules/votings_service.rb', line 146

def fetch_by_body(body_id, proposition_ids: nil, start_date: nil, end_date: nil,
                  order: DEFAULT_ORDER, order_by: DEFAULT_ORDER_BY)
  params = {
    idProposicao: normalize_filter(proposition_ids),
    dataInicio: normalize_date(start_date),
    dataFim: normalize_date(end_date),
    itens: ITEMS_PER_PAGE,
    ordem: order,
    ordenarPor: order_by
  }.compact

  api_get_paginated("orgaos/#{body_id}/votacoes", params)
end

.fetch_by_event(event_id) ⇒ Array<Hash>

Lists votings completed during a deliberative event.

Parameters:

  • event_id (Integer)
  • (Integer)

Returns:

  • (Array<Hash>) 


130
131
132
133
 
# File 'lib/modules/votings_service.rb', line 130

def fetch_by_event(event_id)
  response = api_get("eventos/#{event_id}/votacoes")
  extract_collection(response, "votações do evento #{event_id}")
end

.fetch_by_id(voting_id) ⇒ Hash?

Retrieves the detailed representation of a voting.

The detail may contain possible voting objects and propositions affected by the result. These relationships have different legislative meanings.

Parameters:

  • voting_id (String, Integer) —

    alphanumeric voting identifier

  • (String, Integer)

Returns:

  • (Hash, nil) 


89
90
91
 
# File 'lib/modules/votings_service.rb', line 89

def fetch_by_id(voting_id)
  extract_detail(api_get("votacoes/#{voting_id}"), "votação #{voting_id}")
end

.fetch_by_proposition(proposition_id, order: DEFAULT_ORDER, order_by: DEFAULT_ORDER_BY) ⇒ Array<Hash>

Lists votings that had a proposition as their object or affected it.

Parameters:

  • proposition_id (Integer)
  • order (String) (defaults to: DEFAULT_ORDER)
  • order_by (String) (defaults to: DEFAULT_ORDER_BY)
  • (Integer)
  • order: (String) (defaults to: DEFAULT_ORDER)
  • order_by: (String) (defaults to: DEFAULT_ORDER_BY)

Returns:

  • (Array<Hash>) 


120
121
122
123
124
 
# File 'lib/modules/votings_service.rb', line 120

def fetch_by_proposition(proposition_id, order: DEFAULT_ORDER, order_by: DEFAULT_ORDER_BY)
  params = { ordem: order, ordenarPor: order_by }
  response = api_get("proposicoes/#{proposition_id}/votacoes", params)
  extract_collection(response, "votações da proposição #{proposition_id}")
end

.fetch_list(page: 1, items_per_page: ITEMS_PER_PAGE, **filters) ⇒ Array<Hash>

Retrieves one page of basic voting records.

Parameters:

  • page (Integer) (defaults to: 1)
  • items_per_page (Integer) (defaults to: ITEMS_PER_PAGE)

Returns:

  • (Array<Hash>)

See Also:



76
77
78
79
80
 
# File 'lib/modules/votings_service.rb', line 76

def fetch_list(page: 1, items_per_page: ITEMS_PER_PAGE, **filters)
  filters.merge!(page: page, items_per_page: items_per_page)
  params = list_params(filters)
  extract_collection(api_get('votacoes', params), 'lista de votações')
end

.fetch_orientations(voting_id) ⇒ Array<Hash>

Lists recommendations issued by parties, blocs and other leaderships. The upstream API currently provides orientations only for Plenary votes.

Parameters:

  • voting_id (String, Integer)
  • (String, Integer)

Returns:

  • (Array<Hash>) 


109
110
111
112
 
# File 'lib/modules/votings_service.rb', line 109

def fetch_orientations(voting_id)
  response = api_get("votacoes/#{voting_id}/orientacoes")
  extract_collection(response, "orientações da votação #{voting_id}")
end

.fetch_votes(voting_id) ⇒ Array<Hash>

Lists the individual positions registered in an open nominal voting. An empty response does not identify absent deputies and is normal for symbolic votings.

Parameters:

  • voting_id (String, Integer)
  • (String, Integer)

Returns:

  • (Array<Hash>) 


99
100
101
102
 
# File 'lib/modules/votings_service.rb', line 99

def fetch_votes(voting_id)
  response = api_get("votacoes/#{voting_id}/votos")
  extract_collection(response, "votos da votação #{voting_id}")
end