{"id":50476253,"url":"https://github.com/userdanixdev/project_logistica_refactor","last_synced_at":"2026-06-01T13:31:05.638Z","repository":{"id":361640820,"uuid":"1255131635","full_name":"userdanixdev/project_logistica_refactor","owner":"userdanixdev","description":"Projeto de refatoração para modelagem relacional de dados logísticos com Python, SQLAlchemy, SQLite, Poetry e validações automatizadas.","archived":false,"fork":false,"pushed_at":"2026-05-31T15:59:25.000Z","size":472,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-31T17:12:41.739Z","etag":null,"topics":["data-engineering","data-modeling","orm","poetry","pytest","python","sqlalchemy","sqlite"],"latest_commit_sha":null,"homepage":"https://danixdev.blogspot.com/2026/01/normalizacao-de-dados-na-area-de.html","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/userdanixdev.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-31T12:54:27.000Z","updated_at":"2026-05-31T15:59:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/userdanixdev/project_logistica_refactor","commit_stats":null,"previous_names":["userdanixdev/project_logistica_refactor"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/userdanixdev/project_logistica_refactor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/userdanixdev%2Fproject_logistica_refactor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/userdanixdev%2Fproject_logistica_refactor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/userdanixdev%2Fproject_logistica_refactor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/userdanixdev%2Fproject_logistica_refactor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/userdanixdev","download_url":"https://codeload.github.com/userdanixdev/project_logistica_refactor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/userdanixdev%2Fproject_logistica_refactor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33777967,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-engineering","data-modeling","orm","poetry","pytest","python","sqlalchemy","sqlite"],"created_at":"2026-06-01T13:31:04.899Z","updated_at":"2026-06-01T13:31:05.633Z","avatar_url":"https://github.com/userdanixdev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Project Logística Refactor:\n\n![Python](https://img.shields.io/badge/Python-3.11%2B-blue)\n![Poetry](https://img.shields.io/badge/Poetry-Dependency%20Management-60A5FA)\n![SQLAlchemy](https://img.shields.io/badge/SQLAlchemy-ORM-red)\n![SQLite](https://img.shields.io/badge/SQLite-Database-003B57)\n![Pytest](https://img.shields.io/badge/Pytest-Validated-0A9EDC)\n![Status](https://img.shields.io/badge/Status-v0.1.0%20em%20desenvolvimento-yellow)\n![License](https://img.shields.io/badge/License-MIT-green)\n\n## 🛠️ Motivo da Refatoração:\n\nEste projeto nasceu a partir de um projeto legado desenvolvido com foco exploratório e acadêmico. Embora o primeiro projeto tenha sido importante para validar a ideia, estudar a modelagem e construir os primeiros artefatos, ela apresentava limitações de organização e reprodutibilidade.\n\nEntre os principais pontos identificados estavam o uso excessivo de notebooks como parte do fluxo principal, a criação de bancos de dados diferentes ao longo do desenvolvimento, inconsistências entre nomes de arquivos e comandos documentados, além da ausência de uma estrutura clara para instalação, execução e validação do projeto.\n\nA refatoração foi iniciada para transformar o estudo em um projeto mais organizado, reproduzível e adequado para portfólio técnico. Neste projeto de refatoração, o objetivo é separar melhor as responsabilidades, padronizar o ambiente com Poetry, centralizar a criação do banco, registrar logs de execução, adicionar validações manuais e automatizadas, e documentar com mais clareza as decisões técnicas.\n\n\n## 📌 Descrição Geral:\n\nEste projeto tem como objetivo desenvolver uma aplicação para consulta e análise de dados logísticos normalizados.\n\nO estudo parte de um cenário fictício em que uma empresa possui uma planilha de entregas originada de um ambiente transacional. A proposta é transformar esses dados em um modelo relacional normalizado, organizando as informações em entidades como clientes, endereços, categorias, produtos, pedidos, itens de pedido, entregas, motoristas e veículos.\n\nA modelagem foi elaborada para garantir integridade referencial, normalização dos dados e preservação de informações históricas.\n\n## 🎯 Objetivos\n\n- Modelar um banco de dados relacional para um cenário logístico.\n- Separar dados cadastrais e transacionais.\n- Implementar modelos ORM com SQLAlchemy.\n- Utilizar SQLite como banco local.\n- Gerenciar dependências e ambiente com Poetry.\n- Criar scripts utilitários para validação do banco.\n- Demonstrar práticas de ETL (Extract, Transform and Load)\n- Evoluir o projeto para um painel web com Streamlit.\n\n\n## 📂 Estrutura do Projeto\n\n```text\nproject_logistica_refactor/\n├── data/\n│   ├── raw/\n│   ├── bronze/\n│   └── silver/\n├── scripts_utils/\n├── src/\n│   ├── database/\n│   ├── etl/\n│   └── models/\n├── tests/\n├── create_db.py\n├── pyproject.toml\n└── readme.md\n```\n\n---\n\n### 🗂️ Amostra da Tabela Central\n\nA tabela central original representa a visão transacional antes do processo de normalização.\n\n![Tabela Central](src/docs/tabela_central_sample.png)\n\n---\n\n## 🧠 Modelagem de Dados\n\nO projeto foi estruturado a partir de um processo de modelagem em camadas, partindo da compreensão conceitual do domínio até a implementação física do banco relacional.\n\n### 🧭 Modelo Conceitual\n\nO Modelo Entidade-Relacionamento foi elaborado com base na notação de **Peter Chen** identificando entidades, atributos e relacionamentos de acordo com os requisitos do domínio logístico.\nO modelo conceitual representa as principais entidades do cenário logístico e seus relacionamentos em alto nível.\n\n![Modelo Conceitual](src/docs/model_concept_peter_chen_der.png)\n\n### 🔗 Modelo Lógico\n\nO modelo lógico foi construído segundo a abordagem relacional proposta por **James Martin**, realizando a transformação das entidades em tabelas, definição de chaves primárias e estrangeiras e normalização dos dados.\nO modelo lógico transforma as entidades do domínio em tabelas relacionais, definindo chaves primárias, chaves estrangeiras e relacionamentos entre as estruturas.\n\n![Modelo Lógico](src/docs/model_logic_james_martin.png)\n\n---\n### 🛢️ Modelo Físico:\n\nO modelo físico foi implementado utilizando **SQLAlchemy**, respeitando as decisões tomadas nas etapas anteriores e aplicando regras de integridade diretamente no banco de dados.\n\nForam utilizadas:\n\n- Chaves primárias simples\n- Chaves estrangeiras\n- Restrições de unicidade (`UniqueConstraint`)\n- Regras de exclusão (`ON DELETE CASCADE` e `ON DELETE RESTRICT`)\n- Relacionamentos ORM com `cascade=\"all, delete-orphan\"` quando aplicável\n\n---\n\n## 🔐 Integridade Referencial e Regras de Exclusão:\n\nAs regras de exclusão foram definidas com base na dependência entre as entidades:\n\n- **CASCADE** foi aplicado quando a entidade dependente não possui significado sem sua entidade principal:\n\n  - Pedido → ItemPedido  \n  - Pedido → Entrega  \n  - Cliente → Endereço  \n\n- **RESTRICT** foi utilizado para proteger dados históricos e de cadastro base:\n\n  - Produto → ItemPedido  \n  - Cliente → Pedido  \n  - Motorista → Entrega  \n  - Veículo → Entrega  \n\nAlém disso, o ORM SQLAlchemy foi configurado com `cascade=\"all, delete-orphan\"` nos relacionamentos apropriados, garantindo a remoção automática de registros órfãos no nível da aplicação.\n\n## 🧩 Tecnologias:\n\n- Python\n- Poetry\n- SQLAlchemy\n- SQLite\n- Dbdesigner\n- BRmodeler\n- DB Browser\n- Pandas\n- OpenPyXL\n- Streamlit\n- Pytest\n- Git e GitHub\n\n## 📚 Considerações Finais\n\nEste projeto demonstra, de forma integrada, a aplicação prática dos conceitos de modelagem de dados, desde o levantamento conceitual até a implementação física em um banco relacional.\n\nA versão refatorada foi estruturada com foco em organização, reprodutibilidade e validação técnica. Para isso, foram utilizadas ferramentas como **Poetry**, para gerenciamento do ambiente virtual e das dependências; **SQLAlchemy**, para implementação do modelo físico por meio de ORM; **SQLite**, como banco relacional local; **logging**, para registro das instruções SQL executadas; e **Pytest**, para apoiar a validação automatizada da estrutura do banco.\n\nA abordagem adotada prioriza a consistência dos dados, a preservação do histórico, a clareza estrutural e a rastreabilidade das decisões técnicas. Dessa forma, o projeto se torna adequado tanto para fins acadêmicos quanto para apresentação em portfólio técnico, servindo como base para as próximas etapas de ETL, análises e construção de uma aplicação web.\n\n### 🐍 Ambiente Virtual: \n\nInstale as dependências com Poetry:\n\n```poetry install```\n\n### ⚙️⚙️ Ative o ambiente virtual no terminal:\n\n```source .venv/Scripts/activate```\n\n#### Ou execute comandos diretamente com Poetry:\n\n```poetry run python nome_do_script.py```\n\n#### 🛢️ Criação do Banco\n\nExecute:\n```\npython create_db.py\n```\n\n### Ou:\n```\npoetry run python create_db.py\n```\n\n\u003e *O arquivo database_logistic.db será criado localmente.*\n\n### 🔎 Validações manuais:\n\n```\nListar tabelas criadas:\n\n- python scripts_utils/verificar_banco.py\n\nVerificar colunas, tipos, nulidade e chaves primárias:\n\n- python scripts_utils/verificar_schema.py\n\nVerificar chaves estrangeiras:\n\n- python scripts_utils/verificar_foreign_keys.py\n\nVerificar se as foreign keys estão ativas no SQLite:\n\n- python scripts_utils/verificar_sqlite_fk.py\n```\n### 🧾 Logs de Execução:\n\nPara fins didáticos e de documentação do projeto, esta versão mantém uma amostra dos logs gerados durante a criação e validação do banco.\n\nOs logs permitem visualizar com mais clareza o que acontece durante a execução dos scripts, incluindo instruções SQL geradas pelo SQLAlchemy e detalhes da execução dos testes automatizados com Pytest.\n\n#### 🛢️ Log do SQLAlchemy\n\nO log do SQLAlchemy registra as operações executadas pelo ORM durante a criação e inspeção do banco de dados.\n\nArquivo:\n\n```text\nlogs/sqlalchemy.log\n```\nO print abaixo mostra uma amostra do log gerado pelo SQLAlchemy durante a criação e inspeção do banco de dados.\n\n![Print do Log do SQLAlchemy](src/docs/logs_sqlalchemy.png)\n\n*Esse log ajuda a visualizar os comandos SQL executados, a criação das tabelas, inspeções feitas no banco, operações realizadas pelo engine e comportamento interno do ORM durante as validações.*\n\n#### 🧪 Print do Log do Pytest\n\nO print abaixo mostra uma amostra do log gerado durante a execução dos testes automatizados com Pytest.\n\n![Print do Log do Pytest](src/docs/logs_pytest.png)\n\n### 🚦 Status da Versão:\n```\nA versão inicial contempla:\n\n- configuração do projeto com Poetry\n- reestruturação inicial de diretórios\n- conexão com SQLite\n- ativação de chaves estrangeiras no SQLite\n- modelos ORM com SQLAlchemy\n- script de criação do banco\n- scripts utilitários de validação *(Logs do SQLAlchemy com inspect)*\n- testes automatizados com Pytest\n```\n\n### 🧭 Próximos Passos:\n\n- Implementar a camada Bronze.\n- Implementar a camada Silver.\n- Criar carga dos dados normalizados no banco.\n- Desenvolver o painel web com Streamlit.\n\n\n## 👤 Autor:\n\n``` Daniel Martins França ```\n\n## 📬 Contato:\n\n- 📧 Email: [f.daniel.m@gmail.com](mailto:f.daniel.m@gmail.com)  \n- 💼 LinkedIn: [www.linkedin.com/in/danixdev](https://www.linkedin.com/in/danixdev)  \n- 📁 Trabalhos: [hwww.danixdev.blogspot.com/2026/01/normalizacao-de-dados-na-area-de.html](https://danixdev.blogspot.com/2026/01/normalizacao-de-dados-na-area-de.html)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuserdanixdev%2Fproject_logistica_refactor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuserdanixdev%2Fproject_logistica_refactor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuserdanixdev%2Fproject_logistica_refactor/lists"}