Metodologia do Sistema (versão atual)

1. Objetivo

Este sistema organiza dados de usinas térmicas para responder três pontos, de forma prática:

1. Quais usinas já estão corretamente ligadas entre as bases.
2. Quais usinas ainda precisam de ajuste manual.
3. Como geração e custo evoluem no tempo.

2. Quais dados o sistema usa

Dados principais

• GERACAO_TERMICA_DESPACHO*.parquet: mostra geração por hora e por tipo de despacho.
• CVU_USINA_TERMICA_*.parquet: mostra custo da usina por faixa de tempo.

Dados de apoio

• MODALIDADE_USINA.parquet
• Unidades Geradoras Liberadas Operacao Comercial.csv
• siga-empreendimentos-geracao.csv
• CAPACIDADE_GERACAO.xlsx

Arquivos de decisão manual

• dicionário.csv: liga código de despacho com código de CVU quando o vínculo automático não basta.
• usinas_inoperantes.csv: guarda exclusões feitas manualmente.
• edicoes_conectados.csv: guarda correções manuais de modalidade e combustível.

3. Fluxo completo (de ponta a ponta)

1. O sistema lê os arquivos de despacho e CVU.
2. Padroniza códigos e datas para tudo conversar entre si.
3. Interpreta datas de uso do app sempre em BRT (America/Sao_Paulo), convertendo para UTC apenas na consulta técnica.
4. Tenta ligar usinas automaticamente por código.
5. Usa o dicionário para completar ligações manuais.
6. Mostra o que ficou conectado e o que ainda precisa de decisão.
7. Permite vincular, excluir e editar informações na interface.
8. Salva essas decisões em arquivos de controle.
9. Gera a parte de análise (gráficos e indicadores), inclusive a sub-aba “Maior CVU despachado”.

4. Aba “Tratamento de Dados”

O que acontece nessa aba

• O sistema separa usinas em conectadas e não conectadas.
• Você pode criar vínculo manual entre usina de despacho e usina de CVU.
• Você pode excluir casos da fila de tratamento com motivo.
• Você pode restaurar exclusões.
• Você pode corrigir modalidade e combustível.

Como essas decisões são guardadas

• Vínculos manuais vão para dicionário.csv.
• Exclusões vão para usinas_inoperantes.csv.
• Edições vão para edicoes_conectados.csv.

Essas decisões ficam registradas com data de atualização.

5. Aba “Análise de Dados” (Análise por Usina)

O que a pessoa escolhe

• Usina.
• Período.
• Granularidade (horário, diário, semanal, mensal).
• Série programada, verificada ou ambas.
• Tipos de despacho para o gráfico de comparação.
• Exibição de custo da operação.

O que o sistema mostra

• Indicadores de energia e custo.
• Série temporal principal.
• Série por tipos de despacho selecionados.
• Horário da interface sempre em BRT (gráfico, tabela, tooltip e exportação).

Como o custo é calculado

1. Pega a geração da usina.
2. Busca o CVU correspondente.
3. Se precisar, usa o dicionário para achar o CVU certo.
4. Calcula custo como geração x CVU.

Quando existem duas faixas de CVU no mesmo dia, o sistema faz média proporcional ao tempo de validade de cada faixa.
Se essa conta não puder ser feita, usa a faixa mais recente.

6. Sub-aba “Maior CVU despachado”

Essa sub-aba mostra duas linhas no tempo:

1. CVU da usina mais cara despachada por Ordem de Mérito.
2. CVU da usina mais cara despachada por Garantia Energética.

Se não houver despacho por Garantia Energética naquele momento, o sistema usa o valor da Ordem de Mérito.

Importante sobre essa visão

• É uma visão global do sistema (não depende de escolher uma usina específica).
• A granularidade segue o filtro da tela: horário, diário, semanal ou mensal.
• Na granularidade semanal, o período segue o padrão ONS: sábado a sexta-feira.
• A série pode ser Programada ou Verificada.
• As janelas de período (dia/semana/mês) são calculadas com base em datas BRT.

7. Lógica da sub-aba “Maior CVU despachado” em linguagem direta

Passo 1: ligar despacho com custo (CVU)

Para cada registro de despacho, o sistema tenta achar o CVU da usina:

1. Primeiro pelo próprio código da usina.
2. Depois também pelos vínculos do dicionário.csv.

Ou seja, o dicionário entra diretamente nesse cálculo.

Passo 2: escolher a usina “mais cara” em cada momento

Em cada hora:

1. Ordem de Mérito:
   • pega só usinas com valor de despacho maior que zero;
   • entre elas, escolhe a de maior CVU.
2. Garantia Energética:
   • mesma regra;
   • se não tiver nenhuma com valor maior que zero, usa a escolhida da Ordem de Mérito.

Passo 3: regra de desempate

Se houver empate:

1. Fica a de maior CVU.
2. Se ainda empatar, fica a de maior despacho naquele tipo.
3. Se ainda empatar, fica a de menor código.

Passo 4: quando a visualização é diária, semanal ou mensal

• O sistema parte da série horária já calculada.
• Em cada dia, semana ou mês, mantém o maior CVU do período.
• Também mantém os dados da usina vencedora daquele ponto.
• Na visão semanal, cada ponto representa o início da semana ONS (sábado).

8. Quando os dados mudam na prática

• Sempre que entrar arquivo novo ou mudar o dicionário, rode Reconstruir Cache.
• A sub-aba “Maior CVU despachado” só reflete essas mudanças depois dessa reconstrução.
• Se houver mudança de semântica temporal, o cache legado deve ser refeito para alinhar com BRT.

9. O que fica salvo para desempenho

Na pasta data/cache_analise/, o sistema salva:

• Dados por usina (horário, diário, semanal e mensal).
• Dados de CVU por usina.
• Série global da sub-aba “Maior CVU despachado”:
  • despacho_mais_caro/horario.parquet
  • despacho_mais_caro/diario.parquet
  • despacho_mais_caro/semanal.parquet
  • despacho_mais_caro/mensal.parquet
• Metadados gerais da análise.
  • Inclui timezone_semantics = "BRT_UI_V1" para identificar cache compatível com BRT no app.

10. Resumo final

O sistema combina:

• ligação automática,
• correção manual com histórico,
• e análise temporal pronta para uso.

Na sub-aba “Maior CVU despachado”, a lógica segue exatamente o que você definiu:

• comparar Ordem de Mérito e Garantia Energética;
• usar fallback para Ordem de Mérito quando Garantia for zero;
• considerar os vínculos do dicionário no encontro com CVU;
• e manter a leitura simples no gráfico ao longo do tempo.