Documento de Levantamento de Requisitos - Sistema ETL de Limites Operacionais

1. Visão Geral do Projeto

O projeto consiste no desenvolvimento de uma aplicação Desktop (ETL - Extract, Transform, Load) para automatizar a extração de dados de limites operacionais de Linhas de Transmissão (LTs) e Transformadores (TRs) a partir de documentos em PDF (Manuais de Procedimento/Diretrizes do ONS). Os dados extraídos serão padronizados, validados, armazenados em um banco de dados relacional e exportados para planilhas Excel para fins de conferência de capacidade.

1. Arquitetura e Tecnologias

Interface Gráfica (GUI): PySide6

Extração de PDF: Camelot (foco em tabelas com bordas/linhas bem definidas) e Tabula-py (foco em tabelas formatadas por espaçamento ou stream).

Transformação e Processamento: Pandas (Python)

Armazenamento Local/Staging: SQLite3

Exportação: Pandas (motor openpyxl ou xlsxwriter) para Excel (.xlsx)

Paradigma de Programação: Programação Orientada a Objetos (POO) para garantir a padronização de diferentes layouts de tabelas.

1. Requisitos Funcionais (RF)

Módulo de Interface (PySide6)

RF01: O sistema deve permitir que o usuário selecione, através de uma interface gráfica, o diretório (pasta) contendo os arquivos PDF a serem processados.

RF02: A interface deve exibir uma barra de progresso ou log de execução em tempo real para informar o usuário sobre o status da extração e processamento.

RF03: O sistema deve permitir a parametrização de pastas de saída para os arquivos Excel gerados.

Módulo de Extração (Extract - Camelot/Tabula)

RF04: O sistema deve ler todos os arquivos .pdf na pasta selecionada.

RF05: O sistema deve utilizar heurísticas para identificar o tipo de equipamento da tabela (ex: buscar palavras-chave como “LINHAS DE TRANSMISSÃO”, “TRANSFORMADOR”, “Condição Normal”, “Condição de Emergência”).

RF06: O sistema deve aplicar o extrator mais adequado (Camelot para Lattice e Tabula para Stream) de forma dinâmica caso um falhe ou traga dados inconsistentes.

Módulo de Transformação (Transform - Pandas + POO)

RF07: O sistema deve limpar cabeçalhos repetidos gerados por quebras de página no PDF.

RF08: O sistema deve unificar as informações de “Condição Normal” (Corrente/Icn) e “Condição de Emergência” (Corrente/Ice e Duração) na mesma estrutura de dados.

RF09: O sistema deve mapear os nomes das colunas extraídas do PDF para o padrão interno (Ex: “Valor operacional (A)” -> Icn ou Ice dependendo do contexto da tabela).

Módulo de Carga (Load - SQLite3 e Excel)

RF10: O sistema deve persistir os dados extraídos e padronizados em um banco de dados SQLite3 (Tabelas: raw_pdf_data, linhas_transmissao, transformadores).

RF11: O sistema deve exportar os dados do banco SQLite3 para um arquivo Excel formatado, compatível com o layout de conferência desejado (similar aos CSVs de entrada de “Capacidades Equipamentos”).

1. Requisitos Não Funcionais (RNF)

RNF01 (Desempenho): O processamento da interface gráfica (UI) não deve “congelar” durante a extração dos PDFs. O ETL deve rodar em uma QThread ou Worker separado no PySide6.

RNF02 (Manutenibilidade): O uso de POO é obrigatório. Novas regras de extração para novos formatos de tabelas de diretrizes devem ser adicionadas criando novas subclasses, sem alterar o código principal (Open-Closed Principle).

RNF03 (Tolerância a Falhas): Se uma tabela específica em uma página do PDF não puder ser lida, o sistema deve registrar o erro no log (SQLite/TXT) e continuar a execução para as páginas e arquivos seguintes.

RNF04 (Rastreabilidade): O banco de dados SQLite3 deve atuar como área de staging, guardando a data de extração, arquivo de origem e número da página, facilitando auditorias caso um valor do Excel final esteja estranho.

1. Modelagem Orientada a Objetos (POO) - Proposta

Para lidar com os diferentes formatos de tabela (ex: página 93 do manual de limites), a arquitetura POO sugere:

Classe Base: ExtratorEquipamento (Abstract Class)

Atributos: dataframe_bruto, nome_equipamento, tensao_kv.

Métodos Abstratos: extrair_tabelas(), limpar_dados(), padronizar_colunas().

Subclasses de Extração:

ExtratorLinhaTransmissao (Herda de ExtratorEquipamento)

Implementa regras específicas para ler tabelas de LTs (que podem ter formatação de origem/destino diferente).

ExtratorTransformador (Herda de ExtratorEquipamento)

Implementa regras para tabelas de Transformadores (focando em enrolamentos de alta/baixa, ex: 345/88 kV, conforme PDF de exemplo).

Classe de Orquestração: ETLPipeline

Métodos: iniciar(), salvar_sqlite(), gerar_excel().

Design Pattern sugerido: Factory Method. Uma classe ExtratorFactory avalia o cabeçalho do PDF e instancia automaticamente um ExtratorLinhaTransmissao ou ExtratorTransformador.

1. Fluxo de Execução do Sistema (ETL)

Input: Usuário abre o PySide6, clica em “Selecionar Pasta” e depois em “Iniciar Extração”.

Extract:

O Python itera sobre os PDFs.

Para cada página, Camelot/Tabula converte a imagem/texto em DataFrames do Pandas brutos.

Identify & Instanciate (POO):

A Factory lê o contexto do DataFrame e cria o objeto correto (LT ou TR).

Transform:

O objeto executa limpar_dados(): Remove NaNs, funde células mescladas quebradas, remove textos descritivos fora da tabela.

O objeto executa padronizar_colunas(): Transforma os dados em colunas fixas: Equipamento, Tensao, Corrente_Normal_A, Corrente_Emergencia_A, Duracao_Emergencia.

Load (Staging):

Os dados padronizados são inseridos nas tabelas do SQLite3.

Export:

Uma query no SQLite3 consolida os dados e o Pandas exporta para .xlsx.

Output: A interface PySide6 emite alerta de “Concluído” com link para a pasta de saída.

1. Regras de Negócio Iniciais (Baseado nos arquivos)

RN01: Os valores extraídos do PDF representam a capacidade em Corrente (Amperes - A). Nas tabelas do Excel final, esses valores correspondem as colunas Icn (Normal) e Ice (Emergência).

RN02: Os dados de transformadores costumam ter limites divididos por enrolamento (ex: lado 88kV e lado 345kV). A extração deve vincular o limite de corrente à tensão correta do enrolamento.

RN03: O limite de emergência deve vir acompanhado de sua duração (ex: 04:00 horas), conforme apontado no manual.