commit 108fb1901c76172adbe152043325555a621692d2 Author: João Pedro Toledo Goncalves Date: Wed Oct 15 17:18:01 2025 +0000 Adicionar # Guia de Uso e Boas Práticas - Dashboard de Inventário diff --git a/%23 Guia de Uso e Boas Pr%C3%A1ticas - Dashboard de Invent%C3%A1rio.-.md b/%23 Guia de Uso e Boas Pr%C3%A1ticas - Dashboard de Invent%C3%A1rio.-.md new file mode 100644 index 0000000..fb13ad5 --- /dev/null +++ b/%23 Guia de Uso e Boas Pr%C3%A1ticas - Dashboard de Invent%C3%A1rio.-.md @@ -0,0 +1,86 @@ +Este guia documenta o processo de execução dos scripts para a geração do Dashboard de Inventário e Análise de Riscos, além de destacar os cuidados necessários e possíveis melhorias no projeto. + +## 1. Visão Geral do Processo + +O projeto funciona em duas etapas principais, utilizando dois scripts distintos: + +1. **`normalizar_planilha.py`**: Este é o script de **preparação**. Ele lê as duas planilhas de origem, limpa os dados, adiciona novos colaboradores, atualiza informações de contrato e status, e salva um novo arquivo Excel chamado `dados-normalizados.xlsx` na sua Área de Trabalho (Desktop). + +2. **`inventario.py`**: Este é o script **principal**. Ele lê o arquivo Excel já normalizado (`dados.xlsx`), realiza todos os cálculos de KPIs e riscos, e gera o relatório final `dashboard_interativo_final.html`. + +O fluxo de trabalho atual exige um passo manual entre a execução dos dois scripts. + +## 2. Requisitos de Ambiente + +Para executar os scripts, seu ambiente precisa ter: + +* **Python 3.x** instalado. +* As seguintes bibliotecas Python, que podem ser instaladas com o comando: + ```bash + pip install pandas openpyxl plotly + ``` + +## 3. Passo a Passo para Execução + +Siga rigorosamente estes passos para garantir que o dashboard seja gerado corretamente. + +1. **Verifique os Arquivos de Entrada**: + * O script `normalizar_planilha.py` possui **caminhos fixos** no código. Ele espera encontrar os arquivos de dados exatamente nos seguintes locais: + * `C:\Users\SEU_USUARIO\Documents\Relatorio de Inventario GRUPO PRALOG\dados.xlsx` + * `C:\Users\SEU_USUARIO\Documents\Relatorio de Inventario GRUPO PRALOG\Inventario de Equipamentos Grupo Pralog - via RH (1).xlsx` + * **Certifique-se de que esses caminhos e arquivos existem antes de prosseguir.** + +2. **Execute o Script de Normalização**: + * Abra um terminal e execute o primeiro script para limpar e enriquecer os dados. + * `python scripts/normalizar_planilha.py` + * Ao final, ele criará o arquivo `dados-normalizados.xlsx` na sua **Área de Trabalho (Desktop)**. + +3. **⚠️ Passo Manual Crítico**: + * Vá até sua Área de Trabalho e localize o arquivo **`dados-normalizados.xlsx`**. + * **Renomeie** este arquivo para **`dados.xlsx`**. + * **Mova** o arquivo `dados.xlsx` (já renomeado) para dentro da pasta `scripts/` do projeto, substituindo qualquer versão antiga que possa existir lá. + +4. **Execute o Script Principal**: + * Com o arquivo `dados.xlsx` atualizado dentro da pasta `scripts/`, volte ao terminal. + * Execute o segundo script para gerar o dashboard: + * `python scripts/inventario.py` + +5. **Acesse o Relatório**: + * O relatório final, **`dashboard_interativo_final.html`**, será salvo na pasta raiz do seu projeto. Basta abri-lo em um navegador de internet. + +--- + +## 4. ⚠️ Cuidados Essenciais e Boas Práticas + +Estes são os pontos que mais exigem atenção. Erros aqui farão os scripts falharem. + +* **Nomes das Colunas são Rígidos**: + * O script `normalizar_planilha.py` **exige** que a planilha de inventário (`Inventario de Equipamentos...`) contenha exatamente as seguintes colunas: + * `Colaborador Registrado` + * `Tipo de Contrato` + * `Unidade` + * `Status` + * O script `inventario.py` depende dos nomes de colunas definidos no dicionário `COLUNAS` no início do código. **Qualquer alteração no nome de uma coluna na planilha `dados.xlsx` deve ser refletida neste dicionário.** + +* **Caminhos de Arquivo Fixos**: Como mencionado no passo a passo, o script `normalizar_planilha.py` não funcionará se os arquivos de origem não estiverem na pasta `Documents\Relatorio de Inventario GRUPO PRALOG`. + +* **Processo Manual é Fonte de Erro**: Esquecer de **renomear e mover** o arquivo `dados-normalizados.xlsx` é o erro mais comum. Se o seu dashboard não atualizar com os dados novos, verifique se você executou este passo corretamente. + +* **Dados Vazios**: Certifique-se de que a coluna `Colaborador Registrado` na planilha de inventário não tenha linhas em branco, pois elas serão descartadas e o colaborador não será processado. + +--- + +## 5. Sugestões de Melhoria para o Futuro + +Para tornar o projeto mais robusto e fácil de usar, considere as seguintes melhorias: + +1. **Remover Caminhos Fixos (Hardcoded)**: + * Modifique o `normalizar_planilha.py` para usar caminhos relativos, lendo os arquivos da pasta `dados_entrada/` do projeto, conforme a estrutura que definimos para o repositório. Isso torna o projeto portátil e independente do computador de cada usuário. + +2. **Automatizar o Fluxo de Trabalho**: + * O ideal é eliminar o passo manual. Isso pode ser feito de duas formas: + * **Opção A (Recomendada)**: Modificar o `inventario.py` para que ele leia diretamente o arquivo `dados-normalizados.xlsx` de um local predefinido, em vez de `dados.xlsx`. + * **Opção B**: Unir os dois scripts em um só. O processo de normalização seria a primeira parte do script `inventario.py`, passando os dados diretamente em memória (via DataFrame) para a etapa de geração do dashboard, sem precisar salvar um arquivo Excel intermediário. + +3. **Externalizar Configurações**: + * Para um projeto ainda mais avançado, o dicionário `COLUNAS` e os nomes dos arquivos poderiam ser movidos para um arquivo de configuração externo (ex: `config.json`), facilitando a manutenção sem precisar alterar o código Python. \ No newline at end of file