Adicionar # Guia de Uso e Boas Práticas - Dashboard de Inventário
commit
108fb1901c
|
|
@ -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.
|
||||
Loading…
Reference in New Issue