Skip to content

GustavoHASH/dashboard-hex

BranchesTags

Repository files navigation

📊 Dashboard de Vendas - AdventureWorks

Dashboard interativo desenvolvido em Python com Streamlit para análise de vendas da base de dados AdventureWorks.

Teste de Habilidade BI - Hexagon

Python Streamlit SQL Server License

📸 Preview

O dashboard oferece:

  • 📊 4 KPIs principais (Vendas Totais, Pedidos, Ticket Médio, Produtos)
  • 📈 Gráfico de evolução de vendas ao longo do tempo
  • 🏆 Top 15 produtos mais vendidos
  • 🥧 Distribuição de vendas por categoria
  • 🗺️ Análise de vendas por região
  • 🔍 Filtros interativos (data, região, país, categoria, produtos)

🎯 Índice

📋 Pré-requisitos

Antes de começar, você precisa ter instalado:

1. SQL Server Express (Gratuito)

2. SQL Server Management Studio - SSMS

3. Python 3.8 ou superior

4. ODBC Driver 18 for SQL Server

5. Base de Dados AdventureWorks

🚀 Instalação Completa Passo a Passo

ETAPA 1: Instalar SQL Server e SSMS

1.1 Instalar SQL Server Express

  1. Execute o instalador do SQL Server Express
  2. Escolha "Basic" (instalação básica)
  3. Aceite os termos e aguarde a instalação
  4. ANOTE o Instance Name (exemplo: SQLEXPRESS ou MSSQLSERVER)
  5. Reinicie o computador (recomendado)

1.2 Instalar SSMS

  1. Execute o instalador do SSMS
  2. Siga o wizard de instalação
  3. Aguarde (~10-15 minutos)
  4. Reinicie o computador

ETAPA 2: Restaurar o Banco AdventureWorks

2.1 Conectar ao SQL Server

  1. Abra o SQL Server Management Studio (SSMS)
  2. Na janela "Connect to Server":
    • Server name: localhost\SQLEXPRESS (ou localhost\MSSQLSERVER)
    • Authentication: Windows Authentication
    • Clique em "Opções >>" → Propriedades da Conexão
    • Criptografar conexão: Marque como "Opcional"
  3. Clique em "Connect"

2.2 Restaurar o Database

  1. No Object Explorer (painel esquerdo):

    • Clique com botão direito em "Databases"
    • Selecione "Restore Database..."

  2. Na janela de Restore:

    • Selecione "Device"
    • Clique no botão "..."
    • Clique em "Add"
    • Navegue até C:\temp\AdventureWorks2019.bak
    • Selecione o arquivo e clique OK
    • Clique OK novamente
    • Clique OK para iniciar a restauração

  3. Aguarde a mensagem:

    Database 'AdventureWorks2019' restored successfully.

2.3 Verificar Instalação

Execute esta query no SSMS (New Query → Execute):

USE AdventureWorks2019;
GO

SELECT COUNT(*) AS TotalVendas FROM Sales.SalesOrderHeader;
SELECT COUNT(*) AS TotalItens FROM Sales.SalesOrderDetail;
GO

Resultado esperado:

  • TotalVendas: 31,465
  • TotalItens: 121,317

✅ Se viu esses números, o banco está OK!

ETAPA 3: Configurar o Projeto Python

3.1 Criar Estrutura de Pastas

Abra o Prompt de Comando (cmd) e execute:

# Criar pasta do projeto
mkdir C:\DashboardVendas
cd C:\DashboardVendas

# Criar pasta para ambiente virtual
mkdir venv

3.2 Copiar Arquivos do Projeto

Copie todos os arquivos fornecidos para C:\DashboardVendas\:

C:\DashboardVendas\
├── dashboard.py
├── requirements.txt
├── test_connection_sqlexpress.py
├── .env
├── README.md
└── .gitignore

3.3 Criar Ambiente Virtual (Recomendado)

No Prompt de Comando (dentro de C:\DashboardVendas):

# Criar ambiente virtual
python -m venv venv

# Ativar ambiente virtual
venv\Scripts\activate

# Você verá (venv) antes do prompt

3.4 Instalar Dependências

Com o ambiente virtual ativado:

pip install --upgrade pip
pip install -r requirements.txt

Aguarde a instalação (~2-3 minutos). Pacotes instalados:

  • streamlit
  • pandas
  • plotly
  • pyodbc
  • python-dateutil

⚙️ Configuração

Configuração da Conexão com SQL Server

Você tem duas opções para configurar a conexão:

Opção 1: Usando Variáveis de Ambiente (RECOMENDADO) ✅

  1. Crie um arquivo .env na pasta do projeto (C:\DashboardVendas\.env)

  2. Adicione as seguintes variáveis:

# Configurações do SQL Server
SQL_SERVER=localhost\SQLEXPRESS
SQL_DATABASE=AdventureWorks2019
SQL_DRIVER=ODBC Driver 18 for SQL Server

# Use Windows Authentication (recomendado)
SQL_USE_WINDOWS_AUTH=True

# OU use SQL Authentication (descomente se necessário)
# SQL_USE_WINDOWS_AUTH=False
# SQL_USER=seu_usuario
# SQL_PASSWORD=sua_senha
  1. Instale python-dotenv (se ainda não instalou):
pip install python-dotenv
  1. O dashboard.py já está configurado para usar .env automaticamente!

Opção 2: Editar Diretamente no Código

Abra dashboard.py e localize a função get_database_connection() (linha ~60).

Configuração Padrão (Windows Authentication):

conn_str = (
    "DRIVER={ODBC Driver 18 for SQL Server};"
    "SERVER=localhost\\SQLEXPRESS;"  # ← AJUSTE AQUI seu servidor
    "DATABASE=AdventureWorks2019;"
    "Trusted_Connection=yes;"
    "TrustServerCertificate=yes;"
)

Para SQL Authentication (usuário e senha):

conn_str = (
    "DRIVER={ODBC Driver 18 for SQL Server};"
    "SERVER=localhost\\SQLEXPRESS;"
    "DATABASE=AdventureWorks2019;"
    "UID=seu_usuario;"
    "PWD=sua_senha;"
    "TrustServerCertificate=yes;"
)

⚠️ Ajustes Importantes

Se seu SQL Server for diferente, ajuste:

Instalação SERVER
SQL Express localhost\SQLEXPRESS
SQL Server padrão localhost ou localhost\MSSQLSERVER
Servidor remoto 192.168.1.100\SQLEXPRESS
Named instance localhost\SuaInstancia

Se tiver ODBC Driver 17:

Mude ODBC Driver 18 para ODBC Driver 17

▶️ Como Executar

1. Testar Conexão (IMPORTANTE!)

Antes de rodar o dashboard, sempre teste a conexão:

cd C:\DashboardVendas
python test_connection_sqlexpress.py

Resultado esperado:

✅ CONEXÃO ESTABELECIDA COM SUCESSO!
✅ Sales.SalesOrderHeader: 31,465 registros
✅ Sales.SalesOrderDetail: 121,317 registros
...
✅ TESTE CONCLUÍDO COM SUCESSO!

Se der erro, verifique a seção Troubleshooting.

2. Executar o Dashboard

Com o ambiente virtual ativado:

streamlit run dashboard.py

O navegador abrirá automaticamente em: http://localhost:8501

Para especificar uma porta:

streamlit run dashboard.py --server.port 8502

Para executar sem abrir o navegador:

streamlit run dashboard.py --server.headless true

3. Usar o Dashboard

  1. Filtros (Sidebar à esquerda):

    • Selecione período de datas
    • Escolha região, país, categoria
    • Selecione produtos específicos (opcional)

  2. KPIs (Topo):

    • Vendas Totais
    • Total de Pedidos
    • Ticket Médio
    • Produtos Vendidos

  3. Visualizações:

    • Evolução temporal das vendas
    • Top 15 produtos
    • Distribuição por categoria
    • Análise por região

  4. Dados Detalhados:

    • Expanda "Ver Dados Detalhados" no final da página

📁 Estrutura do Projeto

DashboardVendas/
│
├── dashboard.py                      # Aplicação principal do Streamlit
├── requirements.txt                  # Dependências Python
├── test_connection_sqlexpress.py    # Script de teste de conexão
├── .env                             # Configurações (NÃO commitar!)
├── README.md                        # Este arquivo
├── DESENVOLVIMENTO.md               # Documentação técnica
├── GUIA_INSTALACAO_COMPLETA.md     # Guia detalhado de instalação
├── .gitignore                       # Arquivos a ignorar no Git
│
├── venv/                            # Ambiente virtual (não commitar)
│
└── .streamlit/                      # Configurações do Streamlit (opcional)
    └── config.toml

🐛 Troubleshooting

Erro: "ModuleNotFoundError: No module named 'streamlit'"

Causa: Dependências não instaladas

Solução:

pip install -r requirements.txt

Erro: "Cannot connect to localhost\SQLEXPRESS"

Causa: SQL Server não está rodando ou nome incorreto

Solução:

  1. Verificar se SQL Server está rodando:

    • Windows + R → services.msc
    • Procure "SQL Server (SQLEXPRESS)"
    • Se estiver "Parado", clique com botão direito → "Iniciar"

  2. Verificar o nome correto do servidor:

    • Abra SSMS
    • Use o nome que funciona no SSMS
    • Atualize no .env ou dashboard.py

Erro: "Login failed for user"

Causa: Credenciais incorretas ou permissões

Solução:

Para Windows Authentication:

"Trusted_Connection=yes;"

Para SQL Authentication:

"UID=seu_usuario;"
"PWD=sua_senha;"

Certifique-se que o usuário tem permissão no banco AdventureWorks2019.

Erro: "Driver not found"

Causa: ODBC Driver não instalado

Solução:

  1. Verifique drivers instalados:
python test_connection_sqlexpress.py

  1. Se não tiver ODBC Driver 18, instale:

  2. Ou use ODBC Driver 17 (se tiver):

    • Mude no .env ou código: ODBC Driver 17 for SQL Server

Erro: "A connection was successfully established with the server, but then an error occurred during the login"

Causa: Problema de certificado SSL (SQL Server 2025)

Solução:

Adicione à string de conexão:

"TrustServerCertificate=yes;"

Ou no .env:

SQL_TRUST_CERTIFICATE=yes

Erro: "Database 'AdventureWorks2019' does not exist"

Causa: Banco não foi restaurado

Solução:

  1. Verifique no SSMS se o banco existe
  2. Se não existir, restaure conforme ETAPA 2
  3. Verifique o nome exato do banco (pode ser AdventureWorks, AdventureWorks2019, etc.)

Erro: "Porta 8501 já em uso"

Causa: Outro processo usando a porta

Solução:

streamlit run dashboard.py --server.port 8502

Dashboard carrega mas não mostra dados

Causa: Conexão OK mas query com problema

Solução:

  1. Verifique logs do Streamlit no terminal
  2. Execute o teste de conexão:
python test_connection_sqlexpress.py
  1. Teste a query SQL diretamente no SSMS

Python não reconhecido no cmd

Causa: Python não adicionado ao PATH

Solução:

  1. Reinstale Python marcando "Add Python to PATH"
  2. Ou adicione manualmente:
    • Procure onde Python está instalado (ex: C:\Python311)
    • Windows + Pause → Configurações Avançadas → Variáveis de Ambiente
    • Adicione C:\Python311 e C:\Python311\Scripts ao PATH

🎨 Funcionalidades

KPIs Principais

KPI Descrição Cálculo
💰 Vendas Totais Receita total do período SUM(TotalDue)
📦 Total de Pedidos Quantidade de pedidos COUNT(DISTINCT SalesOrderID)
📊 Ticket Médio Valor médio por pedido AVG(TotalDue)
🏷️ Produtos Vendidos Produtos únicos vendidos COUNT(DISTINCT ProductID)

Filtros Disponíveis

  • 📅 Período: Range de datas (início e fim)
  • 🌍 Região: Estados/Províncias
  • 🏳️ País: Países
  • 🏷️ Categoria: Categorias de produtos
  • 📦 Produtos: Multi-seleção de produtos específicos

Visualizações

  1. 📈 Evolução das Vendas

    • Tipo: Gráfico de linha com área preenchida
    • Eixo X: Ano-Mês
    • Eixo Y: Valor total de vendas
    • Interatividade: Hover com detalhes

  2. 📊 Top 15 Produtos

    • Tipo: Gráfico de barras horizontal
    • Ordenação: Descendente por valor
    • Cores: Gradient azul

  3. 🥧 Vendas por Categoria

    • Tipo: Gráfico de pizza
    • Valores: Percentual e absoluto
    • Interatividade: Click para destacar

  4. 🗺️ Top 10 Regiões

    • Tipo: Gráfico de barras horizontal
    • Cores: Gradient verde
    • Ordenação: Por valor de vendas

Tecnologias Utilizadas

Tecnologia Versão Uso
Python 3.8+ Linguagem principal
Streamlit 1.32.0 Framework de dashboard
Pandas 2.2.0 Manipulação de dados
Plotly 5.18.0 Visualizações interativas
PyODBC 5.0.1 Conexão com SQL Server
SQL Server 2019+ Banco de dados

🔒 Segurança

Boas Práticas Implementadas

✅ Variáveis de Ambiente: Credenciais em .env, não no código
✅ GitIgnore: .env nunca é commitado
✅ Prepared Statements: PyODBC previne SQL Injection
✅ Cache: Dados sensíveis não são expostos desnecessariamente

⚠️ IMPORTANTE

NUNCA commite:

  • Arquivo .env com credenciais
  • Senhas hardcoded no código
  • Strings de conexão com dados sensíveis

Sempre:

  • Use .gitignore para excluir .env
  • Use variáveis de ambiente
  • Mantenha credenciais seguras

📊 Dados do AdventureWorks

Estatísticas do Banco

  • Pedidos: 31,465
  • Itens Vendidos: 121,317
  • Receita Total: $123,216,786.12
  • Período: 2011-05-31 a 2014-06-30
  • Produtos: 504
  • Categorias: 4
  • Regiões: 181

Principais Tabelas Utilizadas

Tabela Registros Uso
Sales.SalesOrderHeader 31,465 Cabeçalho dos pedidos
Sales.SalesOrderDetail 121,317 Detalhes dos itens
Production.Product 504 Informações de produtos
Person.StateProvince 181 Regiões/Estados
Person.CountryRegion 238 Países

🚀 Deploy (Opcional)

Streamlit Cloud (Gratuito)

  1. Faça push do código para GitHub
  2. Acesse https://streamlit.io/cloud
  3. Conecte seu repositório
  4. Configure as variáveis de ambiente no painel
  5. Deploy automático!

Limitação: Não funciona com SQL Server local, apenas com bancos na nuvem.

Docker (Avançado)

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 8501
CMD ["streamlit", "run", "dashboard.py"]

📝 Checklist de Instalação

Use este checklist para garantir que tudo está funcionando:

  • SQL Server Express instalado
  • SSMS instalado
  • AdventureWorks2019.bak baixado
  • AdventureWorks restaurado no SSMS
  • Verificação SQL executada com sucesso (31,465 pedidos)
  • Python 3.8+ instalado e no PATH
  • ODBC Driver 18 instalado
  • Pasta do projeto criada (C:\DashboardVendas)
  • Arquivos copiados para a pasta
  • Ambiente virtual criado
  • Dependências instaladas (pip install -r requirements.txt)
  • Arquivo .env configurado
  • Teste de conexão passou ✅ (test_connection_sqlexpress.py)
  • Dashboard rodando ✅ (streamlit run dashboard.py)

💡 Dicas e Truques

Performance

  1. Cache: O dashboard usa cache do Streamlit - primeira carga é lenta, depois é rápida
  2. Filtros: Use filtros para reduzir o volume de dados processados
  3. Refresh: Para recarregar dados, use Ctrl+R no navegador

Desenvolvimento

  1. Auto-reload: Streamlit recarrega automaticamente ao salvar arquivos
  2. Debug: Use st.write() para debug no próprio dashboard
  3. Logs: Veja logs detalhados no terminal onde executou o Streamlit

Customização

  1. Cores: Edite o CSS inline no dashboard.py
  2. Tema: Crie arquivo .streamlit/config.toml
  3. Novos gráficos: Use Plotly Express - documentação em https://plotly.com/python/

📞 Suporte

Recursos Úteis

Para Dúvidas

  1. Verifique este README primeiro
  2. Execute test_connection_sqlexpress.py e veja os erros
  3. Consulte a seção Troubleshooting
  4. Revise os logs no terminal do Streamlit

📄 Licença

Este projeto foi desenvolvido para fins de avaliação técnica.

🙏 Agradecimentos

  • Microsoft - Base de dados AdventureWorks
  • Streamlit - Framework incrível para dashboards
  • Plotly - Visualizações interativas
  • Hexagon - Oportunidade de desenvolver este projeto

📅 Informações do Projeto

  • Versão: 1.0.0
  • Desenvolvido para: Teste de Habilidade BI - Hexagon
  • Data: Fevereiro 2026
  • Python: 3.8+
  • Banco de Dados: AdventureWorks 2019

Desenvolvido com ❤️ usando Python, Streamlit e muito ☕

Última atualização: Fevereiro 2026

🎯 Quick Start (TL;DR)

Para quem já tem tudo instalado:

# 1. Clone/copie os arquivos
cd C:\DashboardVendas

# 2. Crie e ative ambiente virtual
python -m venv venv
venv\Scripts\activate

# 3. Instale dependências
pip install -r requirements.txt

# 4. Configure .env
# Crie arquivo .env com suas credenciais

# 5. Teste conexão
python test_connection_sqlexpress.py

# 6. Execute!
streamlit run dashboard.py

Pronto! Acesse http://localhost:8501 🚀

About

Um teste

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages