From 125840933b0904698e5025e012b15a5658d3e947 Mon Sep 17 00:00:00 2001 From: bglamadrid Date: Sun, 8 Sep 2024 18:00:41 -0300 Subject: [PATCH 1/7] docs: finish incomplete `ExceptionsControllerAdvice` javadoc --- .../org/trebol/api/ExceptionsControllerAdvice.java | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/src/main/java/org/trebol/api/ExceptionsControllerAdvice.java b/src/main/java/org/trebol/api/ExceptionsControllerAdvice.java index 43ad3466..4fc58b1c 100644 --- a/src/main/java/org/trebol/api/ExceptionsControllerAdvice.java +++ b/src/main/java/org/trebol/api/ExceptionsControllerAdvice.java @@ -38,12 +38,13 @@ /** * Catches some known exceptions, commonly declared at the controller level.
* Then it sends custom responses to consumers of the REST API.
- * Supports: + * + * The following exceptions are supported and mapped to certain status codes: * * * @see org.springframework.http.HttpStatus From 3c130d06da5de58c25ff3ea0385f9c6d10e38fb6 Mon Sep 17 00:00:00 2001 From: bglamadrid Date: Sun, 8 Sep 2024 18:03:51 -0300 Subject: [PATCH 2/7] docs: update old spring boot documentation links --- src/main/resources/application.properties | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/main/resources/application.properties b/src/main/resources/application.properties index 7b3edcb5..21db5f55 100644 --- a/src/main/resources/application.properties +++ b/src/main/resources/application.properties @@ -1,5 +1,5 @@ # -# Copyright (c) 2023 The Trebol eCommerce Project +# Copyright (c) 2020-2024 The Trebol eCommerce Project # # Permission is hereby granted, free of charge, to any person obtaining a copy of this software # and associated documentation files (the "Software"), to deal in the Software without restriction, @@ -19,15 +19,15 @@ # ############################################################ # -# Read more about configuring Spring Boot applications in -# https://docs.spring.io/spring-boot/docs/2.6.2/reference/html/features.html#features.external-config.files -# https://docs.spring.io/spring-boot/docs/2.6.2/reference/html/application-properties.html -# ############################################################ # # THIS IS AN EXAMPLE CONFIGURATION FILE # IT ONLY CREATES THE BARE MINIMUM CONFIGURATION FOR PREVIEWING AND UNIT TESTING -# The application SHOULD NOT run just with these settings in a production environment +# The application SHOULD NOT run with these settings in a production environment +# +# Read more about configuring Spring Boot applications in +# https://docs.spring.io/spring-boot/docs/3.2.9/reference/html/features.html#features.external-config.files +# https://docs.spring.io/spring-boot/docs/3.2.9/reference/html/application-properties.html # ############################## # GENERAL SERVER & SPRING CONFIGURATION From 63d3146264081ceccd8eefb465c8319c94d7922f Mon Sep 17 00:00:00 2001 From: bglamadrid Date: Sun, 8 Sep 2024 18:05:15 -0300 Subject: [PATCH 3/7] chore: remove license header from resource files --- src/main/resources/META-INF/persistence.xml | 20 --------------- .../application-mailgun.empty.properties | 25 ------------------- src/main/resources/application.properties | 21 ---------------- 3 files changed, 66 deletions(-) diff --git a/src/main/resources/META-INF/persistence.xml b/src/main/resources/META-INF/persistence.xml index 1112261a..2f497b28 100644 --- a/src/main/resources/META-INF/persistence.xml +++ b/src/main/resources/META-INF/persistence.xml @@ -1,24 +1,4 @@ - - diff --git a/src/main/resources/application-mailgun.empty.properties b/src/main/resources/application-mailgun.empty.properties index 3d542460..64c9bd19 100644 --- a/src/main/resources/application-mailgun.empty.properties +++ b/src/main/resources/application-mailgun.empty.properties @@ -1,28 +1,3 @@ -# -# Copyright (c) 2023 The Trebol eCommerce Project -# -# Permission is hereby granted, free of charge, to any person obtaining a copy of this software -# and associated documentation files (the "Software"), to deal in the Software without restriction, -# including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, -# and/or sell copies of the Software, and to permit persons to whom the Software is furnished -# to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in all copies or substantial -# portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, -# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A -# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT -# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION -# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE -# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -# -############################################################ -# -# Read more about configuring Spring Boot applications in -# https://docs.spring.io/spring-boot/docs/2.6.2/reference/html/features.html#features.external-config.files -# https://docs.spring.io/spring-boot/docs/2.6.2/reference/html/application-properties.html -# ############################################################ # # THIS IS AN EMPTY CONFIGURATION FILE FOR USING MAILGUN AS YOUR MAIL SERVICE PROVIDER diff --git a/src/main/resources/application.properties b/src/main/resources/application.properties index 21db5f55..6074ce35 100644 --- a/src/main/resources/application.properties +++ b/src/main/resources/application.properties @@ -1,24 +1,3 @@ -# -# Copyright (c) 2020-2024 The Trebol eCommerce Project -# -# Permission is hereby granted, free of charge, to any person obtaining a copy of this software -# and associated documentation files (the "Software"), to deal in the Software without restriction, -# including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, -# and/or sell copies of the Software, and to permit persons to whom the Software is furnished -# to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in all copies or substantial -# portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, -# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A -# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT -# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION -# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE -# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -# -############################################################ -# ############################################################ # # THIS IS AN EXAMPLE CONFIGURATION FILE From 65ac6321157a2b20379007ae3559e505e886f8ad Mon Sep 17 00:00:00 2001 From: bglamadrid Date: Tue, 1 Oct 2024 18:53:16 -0300 Subject: [PATCH 4/7] docs: update readme --- README.md | 142 +++++++++++++++++++++++++++++------------------------- 1 file changed, 76 insertions(+), 66 deletions(-) diff --git a/README.md b/README.md index 469aed14..d63a66eb 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@
- + Spring Logo @@ -16,75 +16,84 @@ [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=trebol-ecommerce_spring-boot-backend&metric=coverage)](https://sonarcloud.io/summary/new_code?id=trebol-ecommerce_spring-boot-backend) A monolithic backend web application for the eCommerce project Trébol, -built using [Spring Boot v2.6](https://docs.spring.io/spring-boot/docs/2.6.x/reference/html/) -and since then migrated to [Spring Boot v3.2](https://docs.spring.io/spring-boot/docs/3.2.x/reference/html/). +built using [Spring Boot v2.6](https://docs.spring.io/spring-boot/docs/2.6.x/reference/html/). + +Since then it's been migrated migrated to [Spring Boot v3.2](https://docs.spring.io/spring-boot/docs/3.2.x/reference/html/).
## Current Status -Although some time has passed since I started working on Trébol, it is still far from a complete project. -I have learned many things in the process: from design patterns to working with the intricacies of -Spring Boot Web application. I've also gotten better at Git itself. +Recently, this project has been set up to work with Java 17, +and as such, the artifact id of the project object model was changed to reflect on that. -Recently, this project has been set up to work with Java 17, and as such, the artifact id of the project was changed too. +Currently, this backend implementation is aligned with [the Trébol API v3.0](https://github.com/trebol-ecommerce/api/blob/v3.0.0/src/trebol-api.json). +But at the same time, this application includes endpoints that are beyond the scope of that API. +These enable some important features: -Currently, this backend implementation is aligned to -[Trébol API v1.7.2](https://github.com/trebol-ecommerce/api/blob/v1.7.2/src/trebol-api.json). -It is planned to migrate towards -[version 3.0](https://github.com/trebol-ecommerce/api/blob/v3.0.0/src/trebol-api.json). +* Registering an user account +* Logging in with said account +* Placing orders using a guest account +* Querying level of authorization per-module -Please take a look at the [CHANGELOG file](CHANGELOG.md) to review the most recent changes, additions and fixes. +Please take a look at the [CHANGELOG file](CHANGELOG.md) +for full explanation on the most recent changes, additions and fixes. ## Features -* Exposes a [RESTful API](https://github.com/trebol-ecommerce/trebol-api) and supports - all the operations described by the document, such as - * CRUD operations on all declared data types - * Can filter, sort and paginate through query params - * Some endpoints support partial updates using `PATCH` requests - * Login, registration and optionally, guest customer accounts - * Checking out as a registered user or a guest (when enabled) -* Uses [Project Lombok](https://projectlombok.org) in all of its API models and JPA entities - * Here's a list of [compatible IDEs and their installation guides](https://projectlombok.org/setup/) - to get yourself an instance running in no time -* Uses [Spring Data JPA](https://spring.io/projects/spring-data-jpa) - * Annotated entity classes; including constraints and indexes where they are most needed at scale - * Bundles drivers for H2 and MariaDB; can virtually connect to any JDBC-compatible database with the correct driver -* Uses [Spring Security](https://spring.io/projects/spring-security) - * Implements stateless session authentication/autorization through [JSON Web Tokens](https://jwt.io/) - with aid from the [JJWT](https://github.com/jwtk/jjwt) library - * Paired with `users`, `roles`, and `permissions` database tables - * See [data.sql](/src/main/resources/data.sql) for an example setup with 4 roles and users) - * Do note that Authorities required in some controllers are hard-coded - These must match entries in the `permissions` database table - * Passwords encoded with BCrypt by default +* Exposes a [RESTful API](https://github.com/trebol-ecommerce/trebol-api) + and supports all the operations described by the document, such as: + * CRUD operations on all declared data types. + * Can filter, sort and paginate through query params. + * Some endpoints support partial updates using `PATCH` requests. + * Login, registration and optionally, guest customer accounts. + * Checking out as a registered user or a guest (when enabled). +* Uses [Project Lombok](https://projectlombok.org) + in all of its API models and JPA entities for an easier time reading. +* Uses [Spring Data JPA](https://spring.io/projects/spring-data-jpa). + * Includes annotated entity classes; specifying constraints and indexes where + they'll be most likely needed when scaling up. + * Bundles drivers for H2 and MariaDB, but can virtually connect to any JDBC-compatible database + with the correct driver. +* Uses [Spring Security](https://spring.io/projects/spring-security). + * Implements stateless authentication/authorization through [JSON Web Tokens](https://jwt.io/) + by using [JJWT](https://github.com/jwtk/jjwt). + * Constrained in tandem with database tables `users`, `roles`, and `permissions`. + * See [data.sql](/src/main/resources/data.sql) for an example setup with 4 roles and users. + * Do note that the Authorities required in REST controllers are hard-coded. + These must match entries in the `permissions` database table. + * Passwords encoded with BCrypt by default. * Integrates payments with [WebpayPlus](https://transbankdevelopers.cl/producto/webpay) - by Transbank ([Java SDK repo](https://github.com/TransbankDevelopers/transbank-sdk-java)) - * It is planned to integrate more internationally popular payment services such as PayPal and Stripe -* Integrates mail notifications with [Mailgun](https://mailgun.com) (an account and API key are required) -* Defines quite-evident properties, and provides a throughfully-explained example file with them, + by Transbank ([Java SDK repo](https://github.com/TransbankDevelopers/transbank-sdk-java)). + * It is planned to integrate more internationally popular payment services such as PayPal and Stripe. +* Integrates mail notifications with [Mailgun](https://mailgun.com) + (an account and API key are required). +* Defines self-evident application properties, and provides a throughfully-explained example file with them, with sane defaults for quickly testing in your local machine. - * Mission-critical - * WebpayPlus properties - * Mailgun & general mail properties - * Security-crucial - * CORS mappings - * JWT secret key and duration - * BCrypt algorithm strength + * Mission-critical properties, such as... + * Payments with WebpayPlus. + * Mailgun & general properties for mail-related services. + * Security-crucial properties; the likes of... + * CORS mappings, should one need to remap the API. + * JWT secret key and duration. + * BCrypt algorithm strength for storing passwords. ### Data model diagram -![Schema](./schema.png) +There was an Entity-Relationship diagram included in this part of the README file here, +but after some of the recent, more heavy changes, it became outdated so it was deleted. +_It's not very good practice to store binary data either..._ -This Entity-Relationship model diagram was designed quickly using -[Azimutt](https://github.com/azimuttapp/azimutt). +**However, please remember the repo does contain [the schema file](/src/main/resources/data.sql) +to spin up a new database from**. +If you need/want to have a diagram to look at, I recommend trying [Azimutt](https://github.com/azimuttapp/azimutt) +to create and design one from it. It's a powerful little program, _really intuitive and easy to use too_. -## Getting started 👍 +## Getting started ### Requirements -* [A supported version of the JDK](https://whichjdk.com) +* [A supported version of the JDK](https://whichjdk.com) (see table below) * [Apache Maven 3](https://maven.apache.org) #### Supported JDK versions @@ -98,27 +107,28 @@ This Entity-Relationship model diagram was designed quickly using ### Installation -First and foremost, don't forget to download, install and enable +First and foremost, please don't forget to download, install and enable [the correct Project Lombok plugin for your IDE](https://projectlombok.org/setup/) -if you haven't done so by the time you read this. +if you haven't done so by now. -After cloning the repository, run `mvn verify`, get yourself comfortable and wait until it is done. +After cloning the repository, run `mvn verify` and get yourself comfortable because it'll take a while. That command will: -- Download & install dependencies -- Generate some of the source code -- Compile the project -- Generate the WAR package file -- Install it to your local maven repo -- Run unit tests -- Check code coverage - -**An important step here that may confuse some people is the generation of source code**. -We have set up type-safe queries by relying on dynamically created QueryDSL classes such as `QUser` and `QProduct`, -which are un-versioned and only included through a Maven plugin within the project dependencies. - -If for any reason you fail to compile the project, -please try running `mvn clean generate-sources` instead and then try the former command again. +1. Download & install dependencies. +2. Generate some of the source code. +3. Compile the project. +4. Generate the WAR package file. +5. Install it to your local maven repo. +6. Run unit tests. +7. Check code coverage. + +**One very important step** that may confuse some, is no. 2, generating some source code. +We have set up type-safe queries by relying on dynamically-created QueryDSL classes such as `QUser` and `QProduct`, +which are un-versioned and only brought in to the code through a Maven plugin within the project dependencies. + +So if for any reason you fail to compile the project, +please reassure said step is successful by running `mvn clean generate-sources` first. +Then try the former command again. ### How to use From 9c74698c30e5c0381fce820a9d627e881407adfc Mon Sep 17 00:00:00 2001 From: bglamadrid Date: Fri, 4 Oct 2024 23:16:19 -0300 Subject: [PATCH 5/7] chore: remove duplicate functionality endpoint `/public/checkout/result/{token}` has the same purposes that `/public/receipt/{token}` does --- .../api/controllers/PublicCheckoutController.java | 15 --------------- .../controllers/PublicCheckoutControllerTest.java | 9 --------- 2 files changed, 24 deletions(-) diff --git a/src/main/java/org/trebol/api/controllers/PublicCheckoutController.java b/src/main/java/org/trebol/api/controllers/PublicCheckoutController.java index 9cf31289..3f538d3c 100644 --- a/src/main/java/org/trebol/api/controllers/PublicCheckoutController.java +++ b/src/main/java/org/trebol/api/controllers/PublicCheckoutController.java @@ -149,21 +149,6 @@ public ResponseEntity validateAbortedTransaction(@RequestParam Map tokenMatcher = Maps.of("token", token).build(); - Predicate withMatchingToken = ordersPredicateService.parseMap(tokenMatcher); - return ordersCrudService.readOne(withMatchingToken); - } - @ResponseStatus(INTERNAL_SERVER_ERROR) @ExceptionHandler(PaymentServiceException.class) public String handleException(PaymentServiceException ex) { diff --git a/src/test/java/org/trebol/api/controllers/PublicCheckoutControllerTest.java b/src/test/java/org/trebol/api/controllers/PublicCheckoutControllerTest.java index e4871e90..b9faedbd 100644 --- a/src/test/java/org/trebol/api/controllers/PublicCheckoutControllerTest.java +++ b/src/test/java/org/trebol/api/controllers/PublicCheckoutControllerTest.java @@ -97,13 +97,4 @@ void redirects_to_failure_page() throws BadInputException, PaymentServiceExcepti assertEquals(SEE_OTHER, response.getStatusCode()); assertEquals(failurePageUri, response.getHeaders().getLocation()); } - - @Test - void reads_result_of_transaction() { - OrderPojo expectedResult = OrderPojo.builder().build(); - when(ordersCrudServiceMock.readOne(nullable(Predicate.class))).thenReturn(expectedResult); - OrderPojo result = instance.getTransactionResultFor(ANY); - assertNotNull(result); - assertEquals(expectedResult, result); - } } From b67d3aafc1da805d6dfdd41af9f17562b4748246 Mon Sep 17 00:00:00 2001 From: bglamadrid Date: Fri, 4 Oct 2024 23:29:56 -0300 Subject: [PATCH 6/7] docs: update changelog [skip ci] --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 34d6fd8a..abc215e5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -66,6 +66,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `/data/orders/rejection` - `/data/orders/completion` - All PUT,PATCH,DELETE,OPTIONS requests return 204 + - Remove duplicated functionality endpoint `/public/checkout/result/{token}` + - Served the same purpose as `/public/receipt/{token}` ## [v0.2.4] - 2024-28-08 From f0ee7f6aa8e83dfad1ca881837c30d693913845f Mon Sep 17 00:00:00 2001 From: bglamadrid Date: Fri, 4 Oct 2024 23:35:56 -0300 Subject: [PATCH 7/7] fix(docs): previous changelog entry date [skip ci] --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index abc215e5..9b8d7560 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -69,7 +69,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Remove duplicated functionality endpoint `/public/checkout/result/{token}` - Served the same purpose as `/public/receipt/{token}` -## [v0.2.4] - 2024-28-08 +## [v0.2.4] - 2024-08-28 ### Changed