High-efficiency REST API for smart queue and appointment management built with Python, FastAPI, PostgreSQL, and Docker, focusing on algorithmic optimization (
🚀 QueueSmart API Uma API RESTful desenvolvida com FastAPI e Python criada para resolver um problema comum em estabelecimentos de atendimento: a gestão ineficiente de filas e agendamentos.
💡 O Problema e a Solução O Problema: Filas presenciais e agendamentos costumam ser difíceis de gerenciar sem uma estrutura centralizada. Clientes perdem tempo sem saber sua posição exata e estabelecimentos enfrentam gargalos no fluxo de atendimento.
A Solução: A QueueSmart API centraliza o cadastro de clientes, controla a entrada e o progresso em filas em tempo real (Mudança de status: Aguardando -> Em Atendimento -> Finalizado) e permite o agendamento de horários específicos.
🛠️ O Que Foi Feito no Código Arquitetura Modular: Organização do projeto no padrão de mercado (app/ contendo models, schemas, database e main).
Modelagem e ORM: Banco de dados relacional configurado com SQLAlchemy, mapeando as entidades de Clientes, Atendimentos da Fila e Agendamentos.
Validação Rígida de Dados: Utilização do Pydantic V2 (ConfigDict) para validar entradas e formatar as respostas JSON com segurança.
Rotas e Documentação Automática: Endpoints RESTful completos (operações de POST, GET e PUT) documentados nativamente via Swagger UI (/docs).
Testes de Integração: Suíte de testes automatizados construída com Pytest e HTTPX, garantindo que as rotas base e comportamentos principais estejam funcionando.
⚙️ Decisões Técnicas e Desafios Superados Durante o desenvolvimento, surgiram desafios de infraestrutura e ambiente que foram contornados com decisões práticas:
Adapter de Banco para Desenvolvimento:
Desafio: O ambiente do Docker Desktop apresentou bloqueio de virtualização no Windows durante a subida do container PostgreSQL.
Solução: Para não travar a evolução das regras de negócio e das rotas, a engine do SQLAlchemy foi adaptada temporariamente para SQLite. A transição para PostgreSQL via docker-compose está pronta no código e exige apenas a virada de chave da variável de conexão.
Garantia de Qualidade com Pytest:
Desafio: Incompatibilidade inicial com dependências do TestClient e rotas base sobrescritas geraram erros 404 nos testes.
Solução: Adição do pacote httpx ao requirements.txt, reestruturação da pasta tests/ na raiz do projeto e restauração dos endpoints de verificação de saúde (/health), atingindo 100% de aprovação nos testes.
🚀 Como Rodar o Projeto
-
Clonar o repositório e instalar dependências PowerShell git clone https://github.com/SEU-USUARIO/queuesmart-api.git cd queuesmart-api python -m pip install -r requirements.txt
-
Iniciar a API PowerShell python -m uvicorn app.main:app --reload Acesse a documentação interativa no navegador: http://127.0.0.1:8000/docs
-
Rodar os testes automatizados PowerShell python -m pytest
📝 Licença Este projeto foi desenvolvido para fins de aprendizado e portfólio. Sinta-se à vontade para contribuir ou utilizar o código!