Metodologia Técnica do Sistema (versão atual)
1. Objetivo e escopo
Este sistema foi implementado para resolver três problemas operacionais com rastreabilidade técnica:
- conectar corretamente registros de despacho térmico com registros de custo variável unitário;
- permitir intervenção manual controlada quando a conexão automática não é suficiente;
- produzir análise temporal de geração, custo e usina de maior custo unitário despachada.
Esta metodologia descreve como a lógica foi programada, em nível de algoritmo, estrutura de dados e fluxo reativo do aplicativo.
2. Arquitetura de implementação em camadas
A implementação está organizada em quatro camadas principais.
2.1 Camada de entrada e padronização
Responsável por:
- localizar arquivos por padrão de nome;
- ler dados em lote (Parquet, CSV e XLSX);
- padronizar tipos (
character, numeric, POSIXct, Date);
- ajustar diferenças de esquema entre arquivos.
2.2 Camada de consolidação e vínculo
Responsável por:
- gerar tabelas únicas por código de usina;
- construir chaves de ligação entre despacho e CVU;
- combinar ligação automática e manual;
- produzir conjuntos conectados e não conectados.
2.3 Camada de decisões manuais
Responsável por:
- persistir mapeamentos manuais;
- aplicar exclusões por tipo de base;
- sobrescrever atributos editáveis (modalidade/combustível) sem alterar a base bruta.
2.4 Camada analítica e de desempenho
Responsável por:
- pré-processar séries por usina e por período;
- manter memória intermediária em disco para reduzir latência;
- calcular e reaproveitar resultados do cenário “maior CVU despachado”.
3. Estrutura dos Dados e Funcionamento Interno
3.1 Fontes principais
3.2 Fontes auxiliares
3.3 Arquivos de Tratamento Manual
dicionário.csv: pares manuais entre código de despacho e código de CVU.usinas_inoperantes.csv: exclusões manuais.edicoes_conectados.csv: edições manuais de atributos.
3.4 Estruturas lógicas mantidas em memória
- conjunto mestre consolidado restaurado do cache leve, quando disponível;
- subconjuntos conectados e não conectados derivados do conjunto mestre;
- tabelas de controle manual carregadas (
dicionário, exclusões e edições);
- metadados do cache analítico usados para montar filtros e limites de período;
- bases auxiliares e dados brutos apenas quando alguma ação exigir reprocessamento ou enriquecimento sob demanda.
4. Ingestão e padronização: lógica programada
4.1 Leitura de arquivos
A leitura é feita por varredura de diretório com filtro por expressão de nome. Em termos de algoritmo:
para cada padrão de arquivo esperado:
listar arquivos existentes
se existir ao menos um arquivo:
ler todos em lote
concatenar linhas
senão:
criar tabela vazia com esquema mínimo
4.2 Padronização de colunas variáveis
No despacho, o identificador CEG pode chegar com nomes diferentes. A lógica trata isso em sequência:
- procurar
ceg;
- se ausente, procurar nomes alternativos conhecidos;
- renomear para
ceg quando encontrado;
- se nenhum existir, criar coluna
ceg nula.
O CEG chega de múltiplas fontes e pode variar no formato sem mudar o significado técnico.
Exemplo comum:
...01 em uma base;...1 em outra base.
Para evitar falso “não encontrado” durante junções e integração com outras bases, o sistema aplica duas camadas de padronização.
Camada A: normalização para cruzamento entre bases de cadastro
Na montagem do conjunto conectado e na integração com outras bases de capacidade/modalidade/combustível:
- remove espaços extras;
- mantém o texto como identificador principal;
- no último bloco numérico após ponto, remove zeros à esquerda.
Regra de transformação do bloco final:
... .01 -> ... .1
... .001 -> ... .1
... .10 -> ... .10 (não altera valor sem zero à esquerda)
Isso resolve o caso de mesmo CEG com final 01 vs 1 sem descaracterizar o restante do código.
Camada B: chave padronizada para buscas e comparação ampla
Em etapas de consulta e consolidação analítica:
- converte para maiúsculo;
- quebra o texto em blocos alfanuméricos;
- em cada bloco numérico, remove zeros à esquerda;
- recompõe uma chave padronizada de comparação.
Essa camada reduz divergências de pontuação e separadores (ponto, hífen, espaço), além do problema 01 vs 1.
Exemplo de equivalência prática
Entradas:
UTE.TESTE.0001.01UTE TESTE-0001-1
Após padronização da chave, ambas convergem para a mesma referência de comparação, permitindo o vínculo correto.
Comportamento para valores ausentes
Se CEG vier vazio/nulo, o sistema preserva como ausente e segue com prioridades de fallback na integração com outras bases (CVU -> despacho -> dicionário), evitando inventar CEG.
4.4 Normalização de código de usina
Para evitar perda de chave, todo código de usina passa por regra determinística:
- remover espaços extras;
- se o código estiver vazio, nulo ou inválido, gerar um identificador sintético com prefixo
GEN_ a partir do nome da usina normalizado;
- manter código original quando válido.
Isso impede quebra de agrupamentos por ausência de identificador.
4.5 Padronização temporal
Toda data-hora de armazenamento técnico é convertida para UTC. A data de negócio (filtro e apresentação) é calculada em BRT.
Implementação lógica:
entrada temporal -> converter para UTC (armazenamento)
saída para interface -> projetar para BRT
filtro por dia -> transformar dia BRT em intervalo UTC [início, fim exclusivo)
5. Consolidação de vínculo entre despacho e CVU
5.1 Preparação de tabelas únicas
Antes da ligação, o sistema resume cada base por código de usina:
- no despacho: código, nome, CEG e anos presentes;
- no CVU: código, nome, CEG, subsistema (quando disponível) e anos presentes.
5.2 Estratégia de chave aditiva
A ligação é construída por união de duas rotas:
- rota de identidade: mesmo código nas duas bases;
- rota de dicionário: par manual armazenado.
5.3 Junção e composição do conjunto conectado
Com as chaves prontas, a junção cruza:
- lado despacho (origem operacional);
- lado CVU (origem de custo).
O resultado mantém:
- código de origem do despacho;
- código associado de CVU;
- nomes dos dois lados;
- CEG consolidado;
- faixa de anos de cada origem;
- indicador de ligação manual.
Após a ligação, aplica-se prioridade de fonte:
CEG
- valor já existente no lado CVU;
- valor do lado despacho;
- valor informado manualmente no dicionário.
Modalidade de Operação e Tipo de Combustível usado
Após consolidar o CEG, cada usina passa por uma regra única de decisão para preencher os campos finais da tela.
Campos finais exibidos no app:
- modalidade de operação:
nom_modalidadeoperacao
- tipo de combustível usado:
nom_combustivel
Como a decisão é feita (passo a passo por usina)
- identificar o CEG já padronizado da usina conectada;
- buscar esse CEG na planilha de capacidade;
- buscar o mesmo CEG nas bases auxiliares de modalidade e combustível;
- montar o valor final por prioridade, sempre escolhendo o primeiro valor disponível.
Regra de prioridade da modalidade de operação
- usar modalidade da
CAPACIDADE_GERACAO.xlsx;
- se estiver vazio, usar modalidade da
MODALIDADE_USINA.parquet;
- se ambos estiverem vazios, manter sem valor.
Regra de prioridade do tipo de combustível usado
- usar combustível da
CAPACIDADE_GERACAO.xlsx;
- se estiver vazio, usar combustível vindo das bases UG/SIGA;
- se ambos estiverem vazios, manter sem valor.
Tabela de decisão resumida
- capacidade preenchida, base auxiliar preenchida: fica o valor da capacidade.
- capacidade vazia, base auxiliar preenchida: fica o valor da base auxiliar.
- capacidade preenchida, base auxiliar vazia: fica o valor da capacidade.
- capacidade vazia, base auxiliar vazia: fica ausente (ajuste manual opcional).
Exemplo prático
Usina com CEG já padronizado:
- modalidade final permanece
Termelétrica
- capacidade informa combustível =
Gás Natural
- base auxiliar informa combustível =
Gás
Resultado final no app:
- modalidade =
Termelétrica
- combustível =
Gás Natural (capacidade tem prioridade sobre a base auxiliar)
Se o valor final ainda estiver incorreto ou ausente, ele pode ser corrigido manualmente em edições. Essas edições têm precedência na visualização final e ficam persistidas em arquivo próprio.
5.5 Geração de não conectados
Os não conectados são obtidos por diferença de conjuntos:
- despacho único menos códigos já conectados e já mapeados manualmente;
- CVU único menos códigos já conectados e já mapeados manualmente.
6. Aplicação de decisões manuais
As decisões manuais são aplicadas após a consolidação do conjunto mestre.
6.1 Edições de atributos
As edições sobrescrevem apenas campos editáveis do conjunto conectado (modalidade e combustível), mantendo rastreabilidade em arquivo separado.
6.2 Exclusões
Exclusões removem registros da camada visual e analítica por código e tipo, sem apagar a origem bruta.
6.3 Vínculo manual
No fluxo manual da interface:
- operador escolhe um item não conectado de despacho;
- operador escolhe um item não conectado de CVU;
- sistema valida presença de CEG;
- sistema grava novo par no dicionário com motivo e horário;
- visão é recalculada imediatamente.
7. Modelo reativo do aplicativo
A camada de servidor usa estado reativo para propagar mudanças de forma incremental.
7.1 Estado principal
Mantém em memória:
- dados brutos;
- auxiliares;
- conjunto mestre;
- visões resultantes para tabelas e gráficos;
- sinalizadores de inicialização e estruturas reativas de apoio.
7.2 Inicialização
Na abertura da sessão:
- tenta restaurar memória intermediária leve;
- verifica se o dicionário foi atualizado depois da memória intermediária;
- valida se a camada leve de dados pré-calculados possui as estruturas mínimas esperadas do esquema atual;
- se essa camada estiver íntegra, restaura o conjunto mestre e os controles manuais;
- se essa camada estiver ausente, legada ou desatualizada, carrega apenas auxiliares e sinaliza que a atualização deve ocorrer externamente.
7.3 Disparadores de recálculo
Eventos de usuário e eventos internos atualizam o estado central, e os componentes dependentes são recalculados automaticamente.
Principais disparadores:
- atualização externa das bases consumidas pela aplicação;
- salvamento de edições em conectados;
- criação de vínculo manual;
- exclusão e restauração de itens;
- consultas sob demanda;
- reconstrução analítica quando acionada por evento específico de servidor.
Esse desenho evita recálculo de tudo a cada clique.
7.4 Organização funcional da interface Shiny
A interface está organizada em três áreas principais.
Área 1: CVU e Despacho de Usinas Termoelétricas
Possui uma barra lateral de filtros e duas sub-abas:
- Análise por Usina:
- granularidade horária, diária, semanal ou mensal;
- período em BRT, com atalhos de janela;
- seleção de usina de despacho;
- seleção de um ou mais códigos CVU associados;
- tipos de despacho a exibir;
- escolha de série
verif, prog ou ambas;
- opção de exibir custo operacional.
- Maior CVU despachado:
- série base
prog ou verif;
- escolha das séries exibidas no gráfico (CVU, PLD, CMO);
- filtro de combustíveis;
- exportação em planilha.
Área 2: Tratamento de Dados
Está dividida em cinco painéis funcionais:
- dados conectados, com edição manual de modalidade e combustível;
- consulta operacional sob demanda por CEG ou código CVU;
- tratamento manual para vincular despacho e CVU;
- gestão de exclusões;
- manutenção do dicionário de vínculo.
Área 3: Metodologia
Exibe:
- o documento canônico em markdown;
- o fluxograma técnico renderizado em
DiagrammeR;
- controles de zoom para inspeção visual do fluxo.
7.5 Encadeamento reativo por domínio
O comportamento reativo da aplicação segue quatro padrões principais:
- bootstrap de sessão:
- tenta restaurar a camada leve de dados pré-calculados;
- carrega bases auxiliares necessárias para a sessão;
- verifica consistência do estado restaurado;
- evita reprocessamento pesado automático na abertura.
- estado mestre + visão final:
- conjunto mestre, exclusões e edições alimentam um ponto central de atualização;
- a cada mudança relevante, o sistema recompõe a visão consolidada e atualiza conectados e não conectados.
- consultas acionadas por botão:
- consultas analíticas só são executadas por disparo explícito do usuário;
- a consulta só roda quando o usuário clica em
Consultar;
- filtros alterados isoladamente não recalculam o resultado até novo disparo.
- interface dinâmica derivada do estado disponível:
- limites de data, lista de usinas, CVUs disponíveis e tipos de despacho são montados reativamente;
- essas listas dependem dos metadados disponíveis, do dicionário e da camada de dados pré-calculados.
8. Reconstrução analítica e memória intermediária em disco
8.1 Particionamento por usina e período
Na reconstrução analítica, o sistema grava:
- série horária por usina;
- agregados diário, semanal e mensal por usina;
- séries de CVU por código associado à análise;
- séries de preços por granularidade;
- séries do cenário “maior CVU despachado” para reaproveitamento;
- metadados gerais da construção.
A semana operacional é ancorada no sábado (padrão ONS).
8.2 Agregação de valores
Para cada usina e período:
- colunas de despacho são agregadas por média;
- total de registros do período é armazenado para auditoria.
8.3 Memória intermediária de preços
PLD, CMO DESSEM e CMO DECOMP são consolidados e salvos por partição anual para acelerar consultas por intervalo.
8.4 Memória intermediária do “maior CVU despachado”
Além do particionamento por usina, o sistema mantém uma memória intermediária específica para a consulta mais pesada do aplicativo.
Essa memória é organizada em camadas:
- resultados em memória da sessão;
- perfis pré-calculados compatíveis;
- consultas persistidas com a mesma assinatura de fontes;
- recálculo completo ou parcial quando não há reaproveitamento seguro.
No recálculo parcial, a atualização usa janela de sobreposição de dias para evitar recomputar todo o histórico.
8.5 Assinatura de atualização
A validade de reaproveitamento é controlada por assinatura baseada no horário de modificação das fontes.
Quando a assinatura muda, resultados antigos são invalidados e recalculados.
Além disso, os metadados guardam a semântica temporal vigente e a versão dos artefatos de preço e análise. Se houver divergência com a configuração atual, o sistema reconstrói caches legados sob demanda.
9. Análise por usina: cálculo técnico
A série da usina é carregada conforme granularidade e filtrada por período com fronteira de dia em BRT.
9.2 Seleção da base de geração
Modos disponíveis:
- programada;
- verificada;
- ambas.
No modo “ambas”, a regra numérica é:
- usar valor verificado;
- se ausente, usar programado como contingência.
9.3 Cálculo de custo operacional
O custo é calculado por multiplicação da geração de base pelo CVU diário consolidado do código de CVU selecionado.
Regra aplicada:
- manter as faixas semanais originais (
dat_iniciosemana a dat_fimsemana);
- expandir cada faixa para os dias cobertos pela vigência;
- consolidar o resultado por código de CVU e por dia de negócio;
- para cada dia com mais de um CVU vigente no mesmo código, manter o maior valor disponível;
- cruzar a geração horária com o CVU diário do dia correspondente em BRT.
Quando o sistema apresenta uma visão diária de CVU, ela já corresponde a essa consolidação diária por código, e não apenas à repetição textual da faixa semanal.
10. Cálculo do “Maior CVU despachado”
Cada registro elegível precisa ter:
- despacho maior que zero no tipo analisado;
- CVU válido para o dia correspondente.
A ligação entre despacho e CVU usa a base horária de despacho, o CVU diário consolidado por código e o dicionário manual, com possibilidade de múltiplas correspondências.
10.2 Seleção de vencedor em Ordem de Mérito e Garantia Energética
A seleção é feita por ordenação hierárquica:
- maior CVU;
- maior despacho;
- menor código de usina.
Essa ordenação garante determinismo.
10.3 Regra de contingência de Garantia Energética
A substituição por Ordem de Mérito ocorre somente quando:
- não existe candidato elegível de Garantia Energética no instante/subsistema;
- existe candidato elegível de Ordem de Mérito.
Se houver despacho de Garantia Energética sem CVU válido, a substituição não é forçada.
10.5 Agregação não horária
Para diário/semanal/mensal:
- parte-se da série horária;
- escolhe-se o vencedor do período pelo mesmo critério de ordenação;
- preservam-se metadados do vencedor;
- agrega-se preço por média no período.
Após a definição do vencedor, o sistema anexa as séries de preço do mesmo instante ou período.
Regra de uso:
PLD é anexado como série própria;- em granularidade horária e diária, a referência principal de CMO prioriza
DESSEM;
- em granularidade semanal e mensal, a referência principal de CMO prioriza
DECOMP;
- as colunas de preço permanecem separadas para rastreabilidade.
10.7 Saída diagnóstica
Além da série vencedora, o sistema produz uma visão diagnóstica das usinas com despacho positivo e sem CVU válido no instante ou período analisado.
Essa saída serve para auditoria do cálculo e para identificar lacunas de vínculo ou de vigência de CVU.
11. Estratégia de reaproveitamento para consulta pesada
A consulta do “maior CVU despachado” usa camadas de reaproveitamento na seguinte ordem:
- instantâneo em memória da sessão;
- perfil pré-calculado compatível;
- resultado persistido da mesma consulta;
- recálculo completo ou parcial.
No recálculo parcial, a atualização pode usar janela de sobreposição de dias para reduzir custo computacional.
12. Persistência e rastreabilidade
12.1 Persistência de governança manual
- dicionário de vínculo manual;
- exclusões;
- edições de atributos.
12.2 Persistência analítica
- séries por usina em múltiplas granularidades;
- séries de preços;
- séries do maior CVU e perfis de reaproveitamento;
- metadados de versão e semântica temporal.
Todos os artefatos são organizados para leitura incremental e reconstrução controlada.
13. Controles de consistência e migração
O sistema possui verificações para detectar e corrigir cenários de memória intermediária legada:
- estrutura incompleta de colunas esperadas;
- semana fora do padrão operacional;
- dados pré-calculados montados com regra temporal diferente da adotada atualmente, como uso incorreto do fuso de exibição, conversão inconsistente entre UTC e BRT ou agrupamento semanal fora do padrão operacional;
- assinatura de fontes divergente.
Ao detectar inconsistência, ativa recálculo orientado para restaurar coerência.
Quando necessário, a correção pode reconstruir sob demanda caches agregados, caches de preço e artefatos legados do cenário “maior CVU despachado”.
14. Resumo técnico
A lógica implementada combina:
- padronização defensiva de entrada;
- vínculo híbrido (automático + manual);
- integração com outras bases por prioridade de fonte;
- decisões manuais persistentes e auditáveis;
- processamento reativo incremental na interface;
- memória intermediária em camadas para desempenho;
- regras determinísticas para seleção do maior CVU;
- consistência temporal formal entre UTC e BRT.
Com esse desenho, o aplicativo mantém robustez operacional, previsibilidade de resultado e capacidade de evolução sem perda de rastreabilidade.