Skip to content

didifive/queue-service-api

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Ā 

History

82 Commits
Ā 
Ā 
Ā 
Ā 
Ā 
Ā 
Ā 
Ā 
Ā 
Ā 
Ā 
Ā 
Ā 
Ā 
Ā 
Ā 
Ā 
Ā 
Ā 
Ā 
Ā 
Ā 
Ā 
Ā 

Repository files navigation

Repository language count Made by Didi GitHub last commit License

Java

šŸš¶šŸš¶šŸš¶ Queue Service API - Filas

šŸ’¾ Controle de senhas para atendimento

Este projeto foi desenvolvido para controle de senhas para atendimento com filas personalizadas, podendo cadastrar filas com Tipos de Prioridades DinĆ¢micos, permitindo ir alĆ©m do padrĆ£o "PrioritĆ”rio e Normal", ficando a critĆ©rio da necessidade. Com as senhas salvas em banco Ć© possĆ­vel tambĆ©m construir relatĆ³rios de como foi o atendimento.

šŸ“¼ Escopo

O sistema, considerando back e front-end deve atender os seguintes requisitos:

  • Ter cadastro de empresa;
  • Para os usuĆ”rios, ter os perfis de Administrador, Atendente e UsuĆ”rio;
  • Ter cadastro de filas com nome e sigla, exemplo: nome "Caixa" e sigla "CX";
  • As filas devem permitir prioridades personalizadas (Normal, PrioritĆ”rio, Idoso 80+ etc);
  • As senhas devem seguir sequencia numĆ©rica com o prefixo sendo a sigla da fila, exemplo: "CX001";
  • Senhas devem possuir um sufixo conforme abreviaĆ§Ć£o do Tipo de Atendimento, exemplo: "CX001N", onde o "N" Ć© abreviatura para Tipo de Atendimento Normal;
  • As senhas devem possuir data e hora de geraĆ§Ć£o e de finalizaĆ§Ć£o, se foi atendida, deve possuir quem foi o atendente;
  • O Administrador tem acesso total ao sistema, podendo inclusive alterar ou desativar outros usuĆ”rios;
  • O Atendente apenas chama e finaliza as senhas marcando como atendida ou nĆ£o atendida;
  • O Atendente pode ver apenas senhas das filas em que foi autorizado;
  • O UsuĆ”rio pode fazer a configuraĆ§Ć£o do sistema, como criar filas, zerar nĆŗmero da fila, vincular (ou desvincular) atendente de uma fila e editar dados da empresa que o UsuĆ”rio faz parte;
  • Deve possuir um terminal para emissĆ£o de senhas, este deve ser logado por um alguĆ©m com perfil de UsuĆ”rio para disponibilizar as filas para emissĆ£o de senhas da empresa em que estĆ” vinculado;
  • Gerar saĆ­da para emissĆ£o de senha em equipamento de impressĆ£o tĆ©rmica.

šŸ“œ Queue Service API - Back-End

Este projeto aborda somente a API em Back-End.
A aplicaĆ§Ć£o possui populador de dados, caso tabela esteja vazia o sistema irĆ” tentar popular com dados bĆ”sicos para se poder experimentar a aplicaĆ§Ć£o de forma mais imediata. Foi criado para fins de estudos, prĆ”tica e testes. Aproveite para fazer melhorias ou personalizaĆ§Ć£o.
Apesar de este projeto ser pĆŗblico e nĆ£o ter finalidade comercial, ainda assim foi pensado para resolver problema real, portanto Ć© possĆ­vel utilizar esta base para um projeto comercial.
LicenƧa: MIT License.

ā­ Destaques:

  • Diagrama de classes que foi base para visualizar e refletir sobre atributos, mĆ©todos e relaƧƵes
  • Resource Bundle para centralizar mensagens de aviso e erros para as Exceptions, com mensagens em idioma PortuguĆŖs e InglĆŖs
  • Constantes de Strings centralizadas no pacote enums.constants, proporcionando melhor reaproveitamento e manutenĆ§Ć£o de textos, inclusive para traduƧƵes
  • AbstraĆ§Ć£o de anotaƧƵes para o Swagger no pacote utils.annotations.swagger proporcionando diminuiĆ§Ć£o e repetiĆ§Ć£o de instruĆ§Ć£o
  • UtilizaĆ§Ć£o de Interface para centralizar anotaƧƵes do Swagger para os Controllers (*ControllerDocs)
  • Filtro por data aplicado com JPA utilizando a consulta criada com o nome de mĆ©todos, exemplo: "findAllByGeradaEmBetween"
  • Filtro de autorizaĆ§Ć£o em cada Endpoint para controle de permissƵes por Perfil ou
  • ServiƧo de popular banco para quando uma tabela/entidade estĆ” sem dados
  • Exception Handler para tratar excessƵes especĆ­ficas da aplicaĆ§Ć£o
  • Spring Banner personalizado
  • Regras de negĆ³cios centralizadas no pacote services e alinhadas para o escopo que o Back-End pode atender
  • ComentĆ”rios para javadoc nos mĆ©todos dos Services
  • UtilizaĆ§Ć£o de variĆ”veis de ambientes para que os valores de DATABASE_URL e TOKEN_API_SECRET nĆ£o fiquem expostos em repositĆ³rio
  • ConfiguraĆ§Ć£o do arquivo application-tests.properties como base de propriedades para serem utilizadas em testes e que possui configuraƧƵes que permitem que o carregamento e teste da classe principal execute normalmente

šŸ‘‰ TO DO:

  • Criar testes unitĆ”rios
  • Implementar Log
  • Implementar Cache
  • Revisar DTOs de respostas para melhor aproveitamento do Front-End

šŸ“— ConfiguraĆ§Ć£o do Projeto

Para carregar a aplicaĆ§Ć£o corretamente Ć© necessĆ”rio configurar as variĆ”veis de ambientes no servidor ou informar na execuĆ§Ć£o:

  • DATABASE_URL: URL da base de dados, este valor Ć© utilizado em spring.datasource.url no application.properties, exemplo de valor para esta variĆ”vel: jdbc:postgresql://host.db.elephantsql.com: 5432/database?user=usuario&password=senha
  • TOKEN_API_SECRET: Token de segredo para o JWT, este valor Ć© utilizado em queue-service-api.jwt.secret no application.properties, exemplo de valor da variĆ”vel: 46070d4bf934fb0d4b06d9e2c46e346944e322444900a435d7d9a95e6d7435f5

A URL para o banco de dados normalmente Ć© fornecida pelo serviƧo de banco de dados, caso a instalaĆ§Ć£o seja local, deve-se confirmar os parĆ¢metros.
Sobre o token para segredo do JWT, este pode ser gerado em sites que geram tokens ou algum token particular criado.

Abaixo, seguem maneiras de executar o projeto com terminal ou com IDE:

šŸ’» Executar com terminal

ApĆ³s configurar banco de dados e o segredo, basta se atentar em possuir o JDK do Java na versĆ£o 17 (vide versĆ£o na seĆ§Ć£o Tecnologias) e executar o comando: Bash ou PowerShell:

./mvnw clean package spring-boot:repackage
java -jar target/queue-service-api-0.2.0-RELEASE.jar

OBS: para CMD, no primeiro comando, basta remover o "./" antes do mvnw

šŸ’» Executar com IDE

A execuĆ§Ć£o com a IDE Ć© mais simples, primeiro deve carregar o projeto na IDE, verificar o JDK configurado, aguardar indexar e carregar as dependĆŖncias do Maven, depois confirmar se as variĆ”veis de ambiente existem no servidor, se nĆ£o existirem, basta configurar as variĆ”veis citadas acima na sua IDE, entĆ£o Ć© sĆ³ fazer a execuĆ§Ć£o.

šŸ”§ Tecnologias

  • Java JDK 17
  • Maven Wrapper 3.8.4
  • Springboot v.3.0.2
  • Spring Security
  • Lombok v.1.18.26
  • Springdoc v.2.1.0 (OpenApi - Swagger)
  • Mapstruct v.1.5.3.Final
  • Java JWT v.4.3.0
  • PostgreSQL - utilizando ElephantSQL
  • Jacoco 0.8.8

šŸ”Ø IDE Utilizada: IntelliJ v.2022.3.2 (Community Edition)


šŸšŖ Endpoints da API

Abaixo segue uma lista geral dos endpoints com resumo de suas funcionalidades:

šŸš¦ AutenticaĆ§Ć£o (Auth): Endpoints para autenticaĆ§Ć£o do usuĆ”rio

MĆ©todo Endpoint DescriĆ§Ć£o
POST /api/v1/auth Realizar autenticaĆ§Ć£o do UsuĆ”rio informando nome de usuĆ”rio e senha e se estiver ok retorna token de acesso.
POST /api/v1/auth/refresh/{usuarioId}/{refreshToken} Informar o Id de UsuƔrio (usuarioID) e o Refresh Token que possui (refreshToken) para gerar um novo token de acesso.
DELETE /api/v1/auth/invalidate-refresh/{usuarioId} Invalida refresh token do usuƔrio, normalmente utilizado ao usuƔrio sair do sistema.

šŸ¢ Empresa: Endpoints com CRUD para cadastro de empresa(s)

MĆ©todo Endpoint DescriĆ§Ć£o
POST /api/v1/empresa Cadastrar nova empresa
GET /api/v1/empresa Listar todas as empresas cadastradas
GET /api/v1/empresa/{id} Detalhar empresa
PUT /api/v1/empresa/{id} Atualizar empresa
DELETE /api/v1/empresa/{id} Apagar empresa

šŸ“Œ Departamento: Endpoints com CRUD para cadastro de departamento(s)

MĆ©todo Endpoint DescriĆ§Ć£o
POST /api/v1/departamento Cadastrar novo departamento
GET /api/v1/departamento Listar todos os departamentos cadastrados
GET /api/v1/departamento/{id} Detalhar departamento
PUT /api/v1/departamento/{id} Atualizar departamento
DELETE /api/v1/departamento/{id} Apagar departamento

šŸ‘¤ Atendente: Endpoints com CRUD para cadastro de atendente(s)

Quando um atendente Ć© criado, um usuĆ”rio serĆ” automaticamente criado com o nome de usuĆ”rio sendo igual ao e-mail do atendente e a senha padrĆ£o "Pw5@QueueService". ObservaĆ§Ć£o: Mesm em caso de jĆ” existir um e-mail de atendente igual Ć  um nome de usuĆ”rio existe o sistema irĆ” tentar um nome diferente atĆ© conseguir criar um usuĆ”rio novo sem conflito com nome de usuĆ”rio.

MĆ©todo Endpoint DescriĆ§Ć£o
POST /api/v1/atendente Cadastrar novo atendente
GET /api/v1/atendente Listar todos os atendentes cadastrados
GET /api/v1/atendente/{id} Detalhar atendente
PUT /api/v1/atendente/{id} Atualizar atendente
DELETE /api/v1/atendente/{id} Apagar atendente

šŸ”‘ UsuĆ”rio: Endpoints com CRUD para cadastro de usuĆ”rio(s)

Os usuĆ”rios sĆ£o diretamente vinculados aos atendentes, nas operaƧƵes Ć© checado o atendente vinculado ao usuĆ”rio.

MĆ©todo Endpoint DescriĆ§Ć£o
POST /api/v1/usuario Cadastrar novo usuƔrio
GET /api/v1/usuario Listar todos os usuƔrios cadastrados
GET /api/v1/usuario/{id} Detalhar usuƔrio
PATCH /api/v1/atendente/{id}/novo-nome-usuario Atualizar usuƔrio com novo nome de usuƔrio
PATCH /api/v1/atendente/{id}/atualizar-senha Atualizar senha de acesso do usuƔrio
PATCH /api/v1/atendente/{id}/perfil/adicionar Adicionar perfil ao usuƔrio
PATCH /api/v1/atendente/{id}/perfil/remover Remover perfil do usuƔrio
PATCH /api/v1/atendente/{id}/ativar Ativar usuƔrio no sistema
PATCH /api/v1/atendente/{id}/desativar Desativar usuƔrio no sistema

ā™æ Tipo de Atendimento: Endpoints com CRUD para cadastro de tipo(s) de atendimento

O Tipo de Atendimento foi um recurso criado para que se possa incluir priorizaƧƵes personalizadas Ơs filas.

MĆ©todo Endpoint DescriĆ§Ć£o
POST /api/v1/tipo-atendimento Cadastrar novo tipo de atendimento
GET /api/v1/tipo-atendimento Listar todos os tipos de atendimento cadastrados
GET /api/v1/tipo-atendimento/{id} Detalhar tipo de atendimento
PUT /api/v1/tipo-atendimento/{id} Atualizar tipo de atendimento
DELETE /api/v1/tipo-atendimento/{id} Apagar tipo de atendimento

šŸ”œ Fila: Endpoints com CRUD para cadastro de fila(s)

Uma fila depende de ao menos um tipo de atendimento vinculado.

MĆ©todo Endpoint DescriĆ§Ć£o
POST /api/v1/fila Cadastrar nova fila
GET /api/v1/fila Listar todas as filas cadastradas
GET /api/v1/fila/{id} Detalhar fila
PUT /api/v1/fila/{id} Atualizar fila
PATCH /api/v1/fila/{id}/tipo-atendimento/{tipoAtendimentoId}/adicionar Adiciona tipo de atendimento Ć  fila
PATCH /api/v1/fila/{id}/tipo-atendimento/{tipoAtendimentoId}/remover Remove tipo de atendimento da fila
DELETE /api/v1/fila/{id} Apagar fila

šŸ”” Senha: Endpoints com CRUD para gerar e operar senha(s)

Cada senha Ć© vinculada a uma fila e um tipo de serviƧo que define a sua prioridade na fila. Possui endpoints para chamar prĆ³xima senha de uma fila, chamar/rechamar senha especĆ­fica, operar para marcar uma senha como chamada, finalizada e atendida e tambĆ©m conseguir ver detalhe de senha e listar senhas conforme intervalo de dia(s)/data(s) e status.
Nas lista de "todas as senhas geradas" e de "todas as senhas geradas e nĆ£o finalizadas", se o utilizador possui perfil somente de ATENDENTE, entĆ£o retorna somente as senhas de filas vinculadas ao(s) departamento(s) que o atendente pertence/atende.

MĆ©todo Endpoint DescriĆ§Ć£o
POST /api/v1/senha Gera uma nova senha para fila e tipo de atendimento
GET /api/v1/senha Lista todas as senhas geradas
GET /api/v1/senha/nao-finalizadas Lista todas as senhas geradas e nĆ£o finalizadas
GET /api/v1/senha/{id} Detalha senha
GET /api/v1/senha/{dataInicio}/{dataFim} Lista as senhas por intervalo de dias/datas
GET /api/v1/senha/chamadas/{dataInicio}/{dataFim} Lista as senhas chamadas por intervalo de dias/datas
GET /api/v1/senha/finalizadas/{dataInicio}/{dataFim} Lista as senhas finalizadas por intervalo de dias/datas
GET /api/v1/senha/atendidas/{dataInicio}/{dataFim} Lista as senhas atendidas por intervalo de dias/datas
PATCH /api/v1/senha/{id}/chamar-senha Chama senha especificada
PATCH /api/v1/senha/fila/{filaId}/chamar-senha Chama prĆ³xima senha da fila especificada conforme definiƧƵes de prioridade do(s) tipo(s) de atendimento
PATCH /api/v1/senha/{id}/finalizar-senha Marca a senha especĆ­ficada como finalizada com respectivo motivo informado
PATCH /api/v1/senha/finalizar-senhas Marca as senhas como finalizadas conforme fila e tipo de atendimento especificados juntamente com devido motivo informado
PATCH /api/v1/senha/finalizar-todas-senhas Marca como finalizada todas as senhas que ainda nĆ£o estavam finalizadas no sistema com motivo informado
PATCH /api/v1/senha/{id}/atender-senha Marca a senha como atendida
PATCH /api/v1/senha/{id}/resetar-status Reseta status da senha, retira a marcaĆ§Ć£o de que foi chamada, atendida e finalizada

šŸ“‡ Para documentaĆ§Ć£o mais completa dos Endpoints, basta acessar o Swagger que fica disponĆ­vel em http://localhost:8080/swagger-ui.html quando o projeto Ć© executado.

šŸ’½ Para testar localmente os Endpoints, existe coleĆ§Ć£o do Postman que jĆ” possuĆ­ requisiƧƵes HTTP configuradas. O arquivo Queue Service API.postman_collection.json e Queue Service API - Enviroments.postman_collection estĆ£o na pasta postman. Basta importar os dois arquivos no aplicativo do Postman e selecionar o ambiente (environment) Localhost. A vantagem de utilizar a configuraĆ§Ć£o do domĆ­nio com ambientes (environments) Ć© permitir uma rĆ”pida utilizaĆ§Ć£o da aplicaĆ§Ć£o em local host e qualquer outro ambiente em que foi feito deploy.


šŸŽØ Visuais

Logotipo:
Filas Logo
UML - Diagrama de Classes:
UML - Diagrama de Classes
OpenAPI - Swagger:
Screenshot da tela de OpenAPI - Swagger
Spring Banner Personalizado:
Spring Banner Personalizado - Filas API

šŸ“± Frontend em React para este projeto

Em desenvolvimento.


šŸ“‹ Qualquer dĆŗvida, sugestĆ£o ou crĆ­tica Ć© sĆ³ entrar em contato ou abrir uma Issue (https://github.com/didifive).
šŸ’š Feito com muita dedicaĆ§Ć£o e aprendizado. #EnjoyThis


šŸ“Ž Links Interessantes:

Releases

No releases published

Packages

No packages published

Languages