Join v0.1.2 reports

README.md

@@ -4,39 +4,47 @@ Mirante is a data-oriented educational system that aims to minimize the loss of
 
 This repository contains an implementation using Java and the Spring Boot Framework.
 
-A document explaining v0.1.0 can be found in the [docs](docs) directory. This currently is a PDF that was submitted as part of a capstone project for the Applied Software Engineering course of IFSP's graduation program in Systems Analysis and Development.
-
 ## Running
 
-After cloning or downloading this repository, you can use the included gradlew wrapper file to build it:
+After cloning or downloading this repository, you can use the included `gradlew` wrapper file to build it:
 
 ```sh
 ./gradlew build
 ```
 
-If you have Gradle locally installed, `gradle build` will work as well.
-
 This will build Java `.jar` files in the `build/libs` directory.
 
 Once built, you can start the server using:
 
 ```sh
-java -jar target/mirante-<version>.jar
+java -jar build/libs/mirante-<version>.jar
 ```
 
-Replace `<version>` with the current version.
+Replace `<version>` with the current version, for example: `java -jar build/libs/mirante-0.1.2-SNAPSHOT.jar`.
+
+If you are unsure about the current version number, look into the `build/libs` directory for what files were generated, or check the `build.gradle` file.
 
-HTML forms meant as a minimal working front-end are available under `src/web/`. Given default port `8080` is usually in use, the forms send requests to port 8888 instead. 
+HTML forms meant as a minimal working front-end demo are available under `src/web/`. Given default port `8080` is usually in use, the forms send requests to port `8888` instead. 
 
 To use them, set port 8888 when running:
 
 ```sh
-java -Dserver.port=8888 -jar target/mirante-<version>.jar
+java -Dserver.port=8888 -jar build/libs/mirante-<version>.jar
 ```
 
+## Documentation
+
+To know more, go to the [documentation website](https://jultty.github.io/mirante/) for access to the latest available documentation.
+
+If you are looking for more formal descriptions of the system, a document explaining v0.1.0 can be found in the [docs](docs) directory. This document was adapted from the version submitted as part of a capstone project for the Applied Software Engineering course in IFSP's graduation program in Systems Analysis and Development.
+
+This main document will only be updated on major versions. For more up-to-date information, check the reports, also in the `docs` directory, or access the [documentation website](https://jultty.github.io/mirante/).
+
 ## Development
 
-Gradle is used to resolve dependencies and build this project. You can use the included wrapper or [install Gradle locally](https://gradle.org/install/).
+Mirante is developed and tested on Java 17, more specifically [Eclipse Temurin JDK 17.0.10+7](https://adoptium.net/temurin/archive/?version=17).
+
+Gradle is used as a build tool to resolve dependencies and build this project. You can use the included wrapper, use Devbox (see below) or [install Gradle locally](https://gradle.org/install/).
 
 To build and run the server:
 
@@ -65,5 +73,4 @@ The following options allow access to the H2 console:
 - **User Name:** `dev`
 - **Password:** Empty 
 
-If you have [Nix](https://nixos.org/manual/nix/stable/introduction) available on your system and flake support enabled, you can use the flake file to setup a development environment with JDK 21 and Gradle using `nix develop`.
-
+If you have [Devbox](https://www.jetpack.io/devbox/) available on your system, you can run `devbox shell` to get a development environment with JDK 17 and Gradle 8 already set up. You can also use `devbox run <script>` to run `build`, `test` and `run` scripts. These scripts will all run inside the Devbox shell and come with port `8888` preconfigured.

docs/v0.1.2/relatorio.md

@@ -7,6 +7,9 @@
 - [ ] Adicionar etruturas de dados para nĩíveis de acesso
 - [ ] Adicionar estruturas de dados para receber resultados
 
+### Subtarefas
+- [x] Resolução de uma regressão de recursão infinita ao tentar implementar a lógica de autenticação
+
 ## Desenvolvimento
 
 Foram levantadas as opções atuais para o armazenamento seguro de senhas. Conforme [recomedações da OWASP][#1] e da própria [documentação do framework Spring][#2], a opção selecionada foi o algoritmo Argon2, que fornece forte segurança criptográfica resistente a ataques de força bruta, com [suporte nativo][#3] no framework através do Spring Security.
@@ -40,12 +43,47 @@ Para facilitar a captura do token nos testes com o Hurl, ele será retornado com
 { "token": "3a321f5a-ddaf-4800-9530-49cb39a2effc" }
 ```
 
-Uma classe `Result` foi criada para armazenar resultados. Esta classe tem apenas um campo do tipo `Timestamp`, que armazena a data e o horário em um formato padronizado e compatível com o banco de dados, e um campo da classe `Exercise`, que corresponde a um objeto equivalente ao exercício recebido como resposta. 
+Uma classe `Result` foi criada para armazenar resultados. Esta classe tem apenas um campo do tipo `Timestamp`, que armazena a data e o horário em um formato padronizado e compatível com o banco de dados, e um campo da classe `Exercise`, que corresponde a um objeto equivalente ao exercício recebido como resposta.
 
 Esse exercício conterá um conjunto de opções que poderá ser comparado com o conjunto armazenado no conjunto de exercícios original para obter a acuidade do resultado. A partir desse valor e da data, será possível calcular também as métricas de retenção e assiduidade.
 
 Os diagramas de casos de uso, sequência e telas foram atualizados para corresponder à nova implementação. O diagrama de casos de uso da ferramenta usada (PlantUML) torna-se confuso quando há grande quantidade de setas. Para os próximos, planejo utilizar a ferramenta Draw.io neste tipo de diagrama especificamente.
 
+### Regressão: Regressão infinita na serialização para JSON
+A implementação da versão v0.1.1 fornecia todos os dados apenas no endpoint `/option`, que retornava todas as opções existentes.
+
+Para a versão `0.2.0` previa-se o oposto: `/option` não deveria retornar nada, e `/option/{id}` deveria retornar apenas as informações daquela opção, com seu exercício na forma simples do _id_  e não toda a estrutura do exercício.
+
+Embora esta questão tenha sido resolvida com o uso do padrão de `DTOs`, foi introduzida uma regressão de recursão infinita onde, ao tentar criar opções, elas tentavam referenciar o exercício a que pertenciam, que por sua vez referenciava todas as suas opções, e assim por diante.
+
+A primeira solução encontrada relaciona-se ao uso das anotações e `@JsonManagedReference` e `@JsonBackReference`, fornecidas no pacote `com.fasterxml.jackson.annotation.JsonBackReference`, que instruem o serializador de JSON saber em qual ponta da relação ele deve colocar a listagem completa, e em qual ponta apenas o _id_.
+
+Como próximo passo, prossegui à listagem das opções de um exercício ao solicitá-lo pelo _id_, por exemplo, `/exercise/ex002`.
+
+O endpoint `/exercise` passou a construir manualmente os DTOs aninhados, através da seguinte lógica:
+
+```java
+    exercises.forEach(e -> {
+      ExerciseDTO dto = new ExerciseDTO();
+      dto.id = e.getId();
+      dto.instruction = e.getInstruction();
+      dto.set = e.getSetId();
+      dto.options = new HashSet<OptionDTO>();
+      e.getOptions().forEach(o -> {
+        OptionDTO optionDTO = new OptionDTO();
+        optionDTO.id = o.getId();
+        optionDTO.content = o.getContent();
+        optionDTO.place = o.getPlace();
+        optionDTO.correct = o.getCorrect();
+        optionDTO.exercise = o.getExerciseId();
+        dto.options.add(optionDTO);
+      });
+      exerciseDTOs.add(dto);
+    });
+```
+
+Este código pode ainda ser melhorado com o uso da biblioteca `modelMapper`, que reduziria muito o código. De toda forma, ele agora atende à necessidade atual.
+
 [#1]: https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html
 [#2]: https://docs.spring.io/spring-security/reference/features/authentication/password-storage.html#authentication-password-storage-argon2
 [#3]: https://docs.spring.io/spring-security/site/docs/6.2.1/api/org/springframework/security/crypto/argon2/Argon2PasswordEncoder.html#encode(java.lang.CharSequence)