Docs/improve documentation | docs(documentation): Conclui Fase 3 de documentação e aprimora README

README.md

@@ -1,16 +1,41 @@
-# 🚀 AutoSINAPI: Transformando Dados em Decisões Estratégicas na Construção Civil
+# 🚀 AutoSINAPI: Acelere Suas Decisões na Construção Civil com Dados Inteligentes
 
 [![Licença](https://img.shields.io/badge/licen%C3%A7a-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
 [![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
 [![Status](https://img.shields.io/badge/status-alpha-orange.svg)](https://github.com/LAMP-LUCAS/AutoSINAPI/releases)
 
-O **AutoSINAPI** é uma solução open-source completa para profissionais de Arquitetura, Engenharia e Construção (AEC) que buscam eficiência e precisão na gestão de custos. Ele automatiza todo o ciclo de vida dos dados do SINAPI, desde a coleta até a análise, transformando um processo manual e demorado em um pipeline de dados robusto e confiável.
+## 🚧 Cansado de Planilhas e Dados Desatualizados? Conheça o AutoSINAPI!
 
-Com o AutoSINAPI, você para de gastar horas com planilhas e foca no que realmente importa: **análises estratégicas, orçamentos precisos e decisões baseadas em dados.**
+Para arquitetos, engenheiros e construtores, a gestão de custos e orçamentos é a espinha dorsal de qualquer projeto bem-sucedido. No entanto, a realidade muitas vezes envolve:
+
+*   **Horas Perdidas:** Coletando, organizando e atualizando manualmente dados do SINAPI.
+*   **Decisões Baseadas em Achismos:** A falta de dados precisos e atualizados compromete a assertividade.
+*   **Complexidade:** Lidar com a vasta e mutável base de dados do SINAPI é um desafio constante.
+
+O **AutoSINAPI** surge como a solução definitiva para transformar essa realidade. Somos uma ferramenta open-source completa, projetada para automatizar o ciclo de vida dos dados do SINAPI, desde a coleta até a análise, entregando a você **informação precisa e atualizada na palma da mão.**
+
+### ✨ O Que o AutoSINAPI Oferece?
+
+*   **Automação Inteligente:** Diga adeus à tediosa coleta manual. O AutoSINAPI baixa, processa e organiza os dados do SINAPI para você.
+*   **Precisão Inquestionável:** Tenha acesso a dados limpos, padronizados e prontos para uso, garantindo orçamentos mais acurados e análises confiáveis.
+*   **Visão Estratégica:** Libere seu tempo para focar no que realmente importa: análises estratégicas, otimização de custos e tomadas de decisão embasadas.
+*   **Histórico Completo:** Mantenha um registro detalhado das alterações do SINAPI ao longo do tempo, essencial para auditorias e comparações.
+*   **Flexibilidade:** Seja você um usuário final buscando uma solução pronta ou um desenvolvedor que precisa integrar dados SINAPI em seus sistemas, o AutoSINAPI se adapta.
 
 ---
 
-## Como Usar o AutoSINAPI
+## 🛠️ Para Desenvolvedores: Robustez, Confiabilidade e Código Aberto
+
+Construído com as melhores práticas de engenharia de software, o AutoSINAPI é mais do que uma ferramenta; é um `toolkit` Python modular, testável e desacoplado.
+
+*   **Arquitetura Modular:** Componentes bem definidos (`downloader`, `processor`, `database`) facilitam a compreensão, manutenção e extensão.
+*   **Testes Abrangentes:** Uma suíte de testes robusta garante a estabilidade e a confiabilidade do pipeline, mesmo com as constantes atualizações do SINAPI.
+*   **Integração Simplificada:** Projetado para ser facilmente consumido por outras aplicações, como APIs REST (ex: [autoSINAPI_API](https://github.com/LAMP-LUCAS/autoSINAPI_API)) ou CLIs customizadas.
+*   **Open Source:** Transparência total e a possibilidade de contribuir para a evolução da ferramenta.
+
+---
+
+## 🚀 Como Começar com o AutoSINAPI
 
 Existem duas maneiras de rodar o pipeline, escolha a que melhor se adapta ao seu fluxo de trabalho.
 
@@ -62,6 +87,17 @@ Para quem prefere ter controle total sobre o ambiente e não usar Docker.
 
 ---
 
+## 🏗️ Arquitetura do Projeto
+
+O **AutoSINAPI** é projetado como um `toolkit` modular e desacoplado, focado em processar dados do SINAPI de forma eficiente e robusta. Sua arquitetura é dividida em componentes principais que interagem para formar um pipeline ETL completo.
+
+Para uma compreensão aprofundada do modelo de dados e do fluxo de execução do ETL, consulte os seguintes documentos:
+
+*   **[Modelo de Dados Detalhado](docs/DataModel.md)**: Descreve as tabelas do banco de dados, seus relacionamentos e a estrutura dos dados.
+*   **[Fluxo de Execução do ETL](docs/DataModel.md#3-processo-de-etl-fluxo-de-execucao-detalhado)**: Detalha as fases do processo de Extração, Transformação e Carga, desde a obtenção dos dados até a persistência no banco de dados.
+
+---
+
 ## Versionamento e Estratégia de Lançamento
 
 O versionamento deste projeto é **totalmente automatizado com base nas tags do Git**. Para mais detalhes, consulte a documentação sobre o fluxo de trabalho do Git.
@@ -76,4 +112,4 @@ Contribuições são bem-vindas! Consulte o nosso [repositório no GitHub](https
 
 ## 📝 Licença
 
-Distribuído sob a licença **GNU General Public License v3.0**.
+Distribuído sob a licença **GNU General Public License v3.0**.

autosinapi/__init__.py

@@ -1,5 +1,12 @@
 """
 AutoSINAPI: Um toolkit para automação de dados do SINAPI.
+
+Este arquivo é o ponto de entrada do pacote `autosinapi`. Ele define a interface
+pública da biblioteca, expondo as principais classes e exceções para serem
+utilizadas por outras aplicações.
+
+O `__all__` define explicitamente quais nomes são exportados quando um cliente
+usa `from autosinapi import *`.
 """
 
 __version__ = "0.1.0"  # A ser gerenciado pelo setuptools-scm

autosinapi/config.py

@@ -1,6 +1,12 @@
 """
 Módulo de configuração do AutoSINAPI.
-Responsável por validar e gerenciar as configurações do sistema.
+
+Este módulo define a classe `Config`, responsável por centralizar, validar e gerenciar
+todas as configurações necessárias para a execução do pipeline de ETL.
+
+A classe garante que todas as chaves obrigatórias para a conexão com o banco de dados
+e para os parâmetros do SINAPI sejam fornecidas, levantando um erro claro em caso de
+configurações ausentes.
 """
 from typing import Dict, Any
 from .exceptions import ConfigurationError

autosinapi/core/__init__.py

@@ -0,0 +1,13 @@
+"""
+Pacote Core do AutoSINAPI.
+
+Este pacote contém os módulos centrais e especializados que executam as principais
+tarefas do pipeline de ETL:
+
+- `downloader`: Responsável pelo download dos arquivos do SINAPI.
+- `processor`: Responsável pelo processamento e transformação dos dados.
+- `database`: Responsável pela interação com o banco de dados.
+
+O `__init__.py` vazio marca este diretório como um pacote Python, permitindo
+que seus módulos sejam importados de forma organizada.
+"""

autosinapi/core/database.py

@@ -1,5 +1,16 @@
 """
-Módulo responsável pelas operações de banco de dados.
+Módulo de Banco de Dados do AutoSINAPI.
+
+Este módulo encapsula toda a interação com o banco de dados PostgreSQL.
+Ele é responsável por:
+- Criar a conexão com o banco de dados usando SQLAlchemy.
+- Definir e criar o esquema de tabelas e views (DDL).
+- Salvar os dados processados (DataFrames) nas tabelas, com diferentes
+  políticas de inserção (append, upsert, replace).
+- Executar queries de consulta e de modificação de forma segura.
+
+A classe `Database` abstrai a complexidade do SQL e do SQLAlchemy, fornecendo
+uma interface clara e de alto nível para o restante da aplicação.
 """
 import logging
 from typing import Dict, Any

autosinapi/core/downloader.py

@@ -1,5 +1,13 @@
 """
-Módulo responsável pelo download e gerenciamento dos arquivos SINAPI.
+Módulo de Download do AutoSINAPI.
+
+Este módulo é responsável por obter os arquivos de dados do SINAPI. Ele abstrai
+a origem dos dados, que pode ser tanto um download direto do site da Caixa
+Econômica Federal quanto um arquivo local fornecido pelo usuário.
+
+A classe `Downloader` gerencia a sessão HTTP, constrói as URLs de download
+com base nas configurações e trata os erros de rede, garantindo que o pipeline
+receba um stream de bytes do arquivo a ser processado.
 """
 from typing import Dict, Optional, BinaryIO, Union
 import requests

autosinapi/core/processor.py

@@ -1,3 +1,16 @@
+"""
+Módulo de Processamento do AutoSINAPI.
+
+Este módulo é responsável por todas as etapas de transformação e limpeza dos dados
+brutos do SINAPI, obtidos pelo módulo `downloader`. Ele lida com a leitura de
+arquivos Excel, padronização de nomes de colunas, tratamento de valores ausentes,
+e a estruturação dos dados em DataFrames do Pandas para que estejam prontos
+para inserção no banco de dados pelo módulo `database`.
+
+A classe `Processor` encapsula a lógica de negócio para interpretar as planilhas
+do SINAPI, extrair informações relevantes e aplicar as regras de negócio
+necessárias para a consistência dos dados.
+"""
 import pandas as pd
 from typing import Dict, Any, List
 import logging

autosinapi/exceptions.py

@@ -1,5 +1,13 @@
 """
 Módulo de exceções customizadas para o AutoSINAPI.
+
+Este arquivo define uma hierarquia de exceções customizadas para o projeto.
+O uso de exceções específicas para cada tipo de erro (Configuração, Download,
+Processamento, Banco de Dados) permite um tratamento de erros mais granular
+e robusto por parte das aplicações que consomem este toolkit.
+
+A exceção base `AutoSinapiError` garante que todos os erros gerados pela
+biblioteca possam ser capturados de forma unificada, se necessário.
 """
 
 class AutoSinapiError(Exception):