Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/didifive/queue-service-api
Controller for queues - Controle de senhas e filas
https://github.com/didifive/queue-service-api
backend backend-api java postgresql rest-api spring-boot
Last synced: 3 months ago
JSON representation
Controller for queues - Controle de senhas e filas
- Host: GitHub
- URL: https://github.com/didifive/queue-service-api
- Owner: didifive
- License: mit
- Created: 2022-02-14T00:35:31.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2024-04-11T16:40:00.000Z (10 months ago)
- Last Synced: 2024-04-11T19:22:03.230Z (10 months ago)
- Topics: backend, backend-api, java, postgresql, rest-api, spring-boot
- Language: Java
- Homepage:
- Size: 745 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# š¶š¶š¶ 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](https://mit-license.org/).
### ā 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:
```bash
./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](https://github.com/didifive/queue-service-api/tree/master/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:
UML - Diagrama de Classes:
OpenAPI - Swagger:
Spring Banner Personalizado:
---
## ~~š± 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:
* [Java 17 - Documentation]
* [IntelliJ]
* [ElephantSQL]
* [spring]
* [spring initializr]
* [SQLite Database with Spring Boot]
* [Jakarta Validation]
* [Lombok]
* [Maven]
[Jakarta Validation]: https://beanvalidation.org/
[Lombok]: https://projectlombok.org/
[Java 17 - Documentation]: https://docs.oracle.com/en/java/javase/17/
[IntelliJ]: https://www.jetbrains.com/pt-br/idea/
[Maven]: https://maven.apache.org/
[H2 Database]: https://h2database.com/
[spring initializr]: https://start.spring.io/
[spring]: https://spring.io/
[ElephantSQL]: https://www.elephantsql.com/
[didifive/queue-service-api]: https://github.com/didifive/queue-service-api
[SQLite Database with Spring Boot]: https://fullstackdeveloper.guru/2020/05/01/how-to-integrate-sqlite-database-with-spring-boot/#:~:text=SQLite%20is%20the%20most%20used%20database%20engine%20in,you%20don%E2%80%99t%20have%20to%20do%20for%20other%20databases.
[Postman]: https://www.postman.com/