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.
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.
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.
- 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
eTOKEN_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
- Criar testes unitƔrios
- Implementar Log
- Implementar Cache
- Revisar DTOs de respostas para melhor aproveitamento do Front-End
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 emspring.datasource.url
noapplication.properties
, exemplo de valor para esta variƔvel: jdbc:postgresql://host.db.elephantsql.com: 5432/database?user=usuario&password=senhaTOKEN_API_SECRET
: Token de segredo para o JWT, este valor Ć© utilizado emqueue-service-api.jwt.secret
noapplication.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:
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
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.
- 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)
Abaixo segue uma lista geral dos endpoints com resumo de suas funcionalidades:
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. |
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 |
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 |
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 |
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 |
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 |
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 |
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.
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: