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.swaggerproporcionando 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
servicese 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_URLeTOKEN_API_SECRETnão fiquem expostos em repositório - Configuração do arquivo
application-tests.propertiescomo 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.urlnoapplication.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.secretnoapplication.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.jarOBS: 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: