STOCK MANAGEMENT SYSTEM

Matthieu Brühwiler - Spring 2023 - V.1.0.0

---

Table of Contents

1. Introduction
2. Requirements
3. Installation
   1. Specify the environments variables to Apache Tomcat
   2. Create the properties file
   3. WAR file of the application
   4. Start the server
4. Usage
   1. Authentication
   2. Employees
   3. Geolocations
   4. Customers
   5. Suppliers
   6. Brands
   7. Categories
   8. Products

---

1. Introduction

Stock Manager is a Java Spring application that allows you to manage: product stocks, supplier and customer orders, and your employees.

It was developed in the context of the Bachelor's thesis of Matthieu Brühwiler at the University of Applied Sciences Haaga-Helia in the spring of 2023.

This application is a starting point for a stock management system. It is possible to use it like this, but adapting it to your needs is recommended. You are free to modify the code as you wish. However, you must respect the license.

The application is a backend application that uses a MariaDB database. It is possible to interact with the system using the provided REST API. The author highly recommends using a front-end application to interact with the system. For the moment, the author has not developed a front-end application, but it is planned to do so in the future.

---

---

2. Requirements

The application uses Java Spring 3.0.0.RELEASE framework. In order to run the application, you need to have the following components:

• Java JDK 17 or higher,
• MariaDB 10.10.0 or higher,
• Apache Maven 4.0.0 or higher,
• A web server that supports Jakarta EE. (For example, Apache Tomcat 10.0.0 or higher.)

The application may work with another version of the components, but it has not been tested.

---

---

3. Installation

This installation tutorial is based on an Apache Tomcat server on a Windows operating system. The adaptation to another server or operating system is left to the user.

As stated in the requirements, you must have a web server that supports Jakarta EE. For this tutorial, we will use an Apache Tomcat server 11.0.0. The installation of the server is not covered in this tutorial. You can find the installation instructions on the Apache Tomcat website.

To run the project, you must specify various information to the Spring Framework in a properties file.

3.1 Specify the environment variables to Apache Tomcat.

In order to specify the environment variables to Apache Tomcat, you need to create a file named stockmanager.xml in the [TOMCAT_INSTALLATION]/conf/Catalina/localhost. This file should contain the following content:

<?xml version='1.0' encoding='utf-8'?>
<Context>
    <Environment name="spring.config.location" value="file:PATH/TO/PROPERTIES/FILE/stockManager.properties" type="java.lang.String"/>
</Context>

3.2 Create the properties file

The Spring application requires you to provide information about the profile, the database connection, the CORS properties, and the JWT properties. This file should be located in the PATH/TO/PROPERTIES/FILE specified in the previous step.

Below is an example of a properties file:

# Profile (dev or prod)
spring.profiles.active=prod

# Database properties
spring.datasource.url=jdbc:mariadb://localhost:3306/stockmanagement
spring.datasource.username=root
spring.datasource.password=
spring.sql.init.mode=always
spring.jpa.defer-datasource-initialization=true
spring.datasource.driver-class-name=org.mariadb.jdbc.Driver
spring.jpa.generate-ddl=true
spring.jpa.hibernate.ddl-auto=update

# Cors properties
spring.security.cors.allowed-origins=http://localhost:3000
spring.security.cors.allowed-methods=GET,POST,PUT,DELETE
spring.security.cors.allowed-headers=Authorization,Content-Type

# JWT properties
jwt.expiration.duration=8
jwt.expiration.unit=10
jwt.secret=THIS_IS_A_BAD_SECRET

3.3 WAR file of the application

To deploy the application on Apache Tomcat, you need to create a WAR file. As written in the requirements, the project is based on the Maven framework. Of this fact, to create the WAR file, you need to execute the following commands:

mvn clean package
mvn install

• The application contains several tests, and the duration of the tests can take 10 minutes. It is important not to skip the tests when creating the WAR file. If you skip the tests, the application may not work properly.*

After creating the WAR file named stockmanager.war, you need to copy it into the [TOMCAT_INSTALLATION]/webapps` folder.

3.4 Start the server

At this point, you can now start the server. The Spring application manages by itself the database schema automatically. It will create, update, and delete the tables as needed.

To run the Apache Tomcat server, you must execute the catalina.bat file located in the [TOMCAT_INSTALLATION]/bin folder.

The application should be available at the following URL: http://IP_ADDRESS:8080/stockmanager/api.

---

---

4. Usage

This chapter is an overview of the different endpoints of the application.

Before reading details about the endpoints, all of them have four common HTTP status codes:

• 200 / 201: The request has succeeded.
• 400: The request has failed because of a bad request.
• 401: The request has failed because the employee is not authenticated.
• 500: The request has failed because of an internal server error.

However, in the case of an error, whatever the status code is, the server always logs the error and returns a JSON object explaining the error.

Before using the application, you should consider the following properties:

• Some endpoints can be accessed depending on the employee's role.
• The application roles are:
  • ROLE_ADMIN: id= 1
  • ROLE_MANAGER: id= 2
  • ROLE_EMPLOYEE: id= 3
• The application has a default admin user with the following credentials:
  • username: main
  • password: A1234
  • ⚠️ This employee should be deactivated after the first connection.

It is important to note that most endpoints that return a list have paging, searching, and sorting methods. As in the following example: /api/brands?page=0&size=100&sort=name,asc&searchQuery=B.

• page: The page number.
• size: The number of elements per page.
• sort: The sorting method. The first parameter is the field to sort, and the second parameter is the sorting order (asc or desc).
• searchQuery: The search query.

4.1 Authentication

To access the application, you need to be authenticated. The authentication is based on the JWT token.

Endpoint	Method	Description	Request Body	HTTP Status
/api/auth/login	POST	Authenticate an employee	Field Type Description username String The password of the employee password String The password of the employee	Status Description 401 Wrong credentials.
/api/auth/password	PUT	Change the password of an employee	Field Type Description currentPassword String The current password of the employee newPassword String The new password of the employee newPasswordVerification String The new password of the employee	Status Description 400 Current password is incorrect. 412 New password is invalid, or not the same.

---

4.2 Employees

Endpoint	Method	Description	Request Body	HTTP Status
/api/employees	GET	Get the list of all the employees		Status Description 204 No employee found.
/api/employees/{id}	GET	Get an employee by his/her id.		Status Description 400 No employee matches given id.
/api/employees	POST	Create a new employee.	Field Type Description email String The email address of the employee username String The username of the employee firstName String The first name of the employee lastName String The last name of the employee password String The password of the employee	Status Description 201 Employee created. 400 A value provided is null or empty. 409 Username or email already exists.
/api/employees/{id}	PUT	Modify an employee by his/her id.	Field Type Description email String The email address of the employee username String The username of the employee firstName String The first name of the employee lastName String The last name of the employee	Status Description 200 Employee modified. 400 No employee matches the given id.
/api/employees/{id}/activate	PUT	Activate an employee id		Status Description 200 The employee has been modified. 400 No employee found, or the given email and username do not correspond.
/api/employees/{empId}/add-role/{roleId}	PUT	Assign a role to an employee.		Status Description 400 Wrong role or employee id. 409 Role already assigned.
/api/employees/{empId}/remove-role/{roleId}	PUT	Unassign a role to an employee.		Status Description 400 Wrong role or employee id. 406 Role is not assigned to this employee.
/api/employees/{id}	DELETE	Deactivate an employee account.		Status Description 400 No employee matches the given id.

4.2.1 Employee statistics

Endpoint	Method	Description	Request Body	HTTP Status
/api/statistics/suppliers?date={optionalDate}	GET	Get general statistics about suppliers.		Status Description 204 No suppliers found.
/api/statistics/customers?date={optionalDate}	GET	Get general statistics about customers.		Status Description 204 No customers found.
/api/statistics/employee={empId}?date={optionalDate}	GET	Calculate statistics for an employee on a defined month and year.		Status Description 204 No orders related to this employee were found. 400 Wrong employee id.
/api/statistics/stock-to-sale-ratio?date={optionalDate}	GET	Calculate the stock-to-sale ratio.		Status Description 204 No customer orders found.
/api/statistics/sell-through-rate?date={optionalDate}	GET	Calculate the sell-through rate.		Status Description 204 No customer or supplier orders found. 412 No product was received during this period.
/api/statistics/stock-outs?date={optionalDate}	GET	Calculate the stock out rate.		Status Description 204 No product found. 412 No available product for this period.
/api/statistics/service-level	GET	Calculate the service level.		Status Description 204 No customer or supplier order.

---

4.3 Geolocations

Endpoint	Method	Description	Request Body	HTTP Status
/api/geolocations	GET	Get all the geolocations.		Status Description 204 No geolocation found.
/api/geolocations/{id}	GET	Get a geolocations by its id.		Status Description 400 No geolocation matches with the given id.
/api/geolocations	POST	Create a new geolocation.	Field Type Description streetName String The street name of the geolocation streetNumber String The street number of the geolocation postcode String The postcode of the geolocation locality String The locality of the geolocation country String The country of the geolocation	Status Description 400 A given value is null or empty. 409 Street name, number, locality, and country already exists together.
/api/geolocations	DELETE	Delete geolocation.		Status Description 400 No geolocation matches with the given id. 409 Supplier or customer is still using this address.

---

4.4 Customers

Endpoint	Method	Description	Request Body	HTTP Status
/api/customers	GET	Get all the customers.		Status Description 204 No customer found.
/api/customers/{email}	GET	Get a customer by his/her email.		Status Description 400 No customer matches the given email.
/api/customers	POST	Create a new customer.	Field Type Description firstName String The first name of the customer lastName String The last name of the customer email String The email of the customer geolocationId Long The id of the geolocation of the customer	Status Description 400 A given value is null or empty. (geolocation can be null) 404 Geolocation not found. 409 Email already exists.
/api/customers/{email}	PUT	Update a customer.	Field Type Description firstName String The first name of the customer lastName String The last name of the customer geolocationId Long The id of the geolocation of the customer	Status Description 400 Customer not found or a given value is null or empty. (geolocation can be null) 404 Geolocation not found.
/api/customers/{email}	DELETE	Delete a customer, but not his/her command(s).		Status Description 400 Customer not found.

4.4.1 Customer orders

Endpoint	Method	Description	Request Body	HTTP Status
/api/customers/orders	GET	Get all the customer orders.		Status Description 204 No customer order found.
/api/customers/{customerId}/orders	GET	Get all the customer orders.		Status Description 204 No customer order found. 400 No customer corresponds to the given id.
/api/customers/orders/{id}	GET	Get a customer order by its id.		Status Description 400 No customer order matches with the given id.
/api/customers/orders	POST	Create a new customer order.	Field Type Description date LocalDate The date of the order deliveryDate LocalDate The delivery date of the order isSent Boolean True if the order is sent, false otherwise productId Long The id of the product customerId Long The id of the customer	Status Description 400 Order date or delivery date is null.
/api/customers/orders/{id}	PUT	Update the delivery date of a customer order.	Field Type Description deliveryDate LocalDate The delivery date of the order	Status Description 400 Order not found.
/api/customers/orders/{id}/send	PUT	Change the state of the customer order as shipped.		Status Description 400 No customer order matches with the given id. 304 A product of the order had a problem. 409 No customer order is already sent.

4.4.2 Customer order lines

Endpoint	Method	Description	Request Body	HTTP Status
/api/customers/orders/order={orderId}/details	GET	Get all the customer order lines of a customer order.		Status Description 204 No customer order line found. 400 No customer order corresponds to the given id.
/api/customers/orders/order={orderId}/details/product={productId}	GET	Get a customer order line by its id.		Status Description 204 No customer order line for this order. 400 Wrong customer order or product id.
/api/customers/orders/order={orderId}/details/product={productId}	POST	Create a new customer order line.	Field Type Description quantity Integer The quantity of the product sellPrice Double The selling price of the line.	Status Description 400 Wrong customer order or product id. 409 Order line already exists for this order. 412 Already sent or delivery date is passed. 412 Product stock is too low. 422 Order quantity is too low.
/api/customers/orders/order={orderId}/details/product={productId}	DELETE	Delete a customer order line.		Status Description 400 Wrong customer order or product id. 412 Already sent or delivery date is passed.

---

4.5 Suppliers

Endpoint	Method	Description	Request Body	HTTP Status
/api/suppliers/	GET	Get all the suppliers.		Status Description 204 No supplier found.
/api/suppliers/{id}	GET	Get a supplier by its id.		Status Description 400 No supplier found.
/api/suppliers	POST	Create a new supplier.	Field Type Description name String The name of the supplier. email String The email of the supplier. phoneNumber String The phone number of the supplier. geolocationId Long The id of the geolocation of the supplier.	Status Description 400 Name is null or empty 404 Geolocation not found. 409 Supplier already exist by name.
/api/suppliers/{id}	PUT	Update a supplier. (email or phone number)	Field Type Description name String The name of the supplier. email String The email of the supplier. phoneNumber String The phone number of the supplier. geolocationId Long The id of the geolocation of the supplier.	Status Description 400 Supplier not found ; name is null or empty 404 Geolocation not found. 409 Supplier already exist by name.
/api/suppliers/{id}	DELETE	Delete a supplier.		Status Description 400 Supplier not found 409 Supplier has related orders or products

4.5.1 Supplier orders

Endpoint	Method	Description	Request Body	HTTP Status
/api/suppliers/orders	GET	Get all supplier orders.		Status Description 204 No supplier orders found.
/api/suppliers/{supplierId}/orders	GET	Get all supplier orders of a supplier.		Status Description 204 No supplier orders found. 400 No corresponding supplier.
/api/suppliers/orders/{id}	GET	Get a supplier order.		Status Description 400 No corresponding supplier order.
/api/suppliers/orders	POST	Create a supplier order.	Field Type Description date LocalDate The date of the order. deliveryDate LocalDate The delivery date of the order. orderIsSent Boolean True if the order is sent. isReceived Boolean True if the order is received. supplierId Long The id of the supplier.	Status Description 400 Supplier not found ; date is null ; deliveryDate is null; orderIsSent is null ; isReceived is null
/api/suppliers/orders/{id}	PUT	Update a supplier order delivery date.	Field Type Description date LocalDate The date of the order. deliveryDate LocalDate The delivery date of the order. orderIsSent Boolean True if the order is sent. isReceived Boolean True if the order is received. supplierId Long The id of the supplier.	Status Description 400 Supplier order not found.
/api/suppliers/orders/{id}/send	PUT	Update a supplier order to send.		Status Description 400 No corresponding supplier order. 409 Supplier order is already sent or has no line.
/api/suppliers/orders/{id}/received	PUT	Receive a supplier order.		Status Description 304 Product stock of the order had a problem. 400 No corresponding supplier order. 409 Supplier order is already received.
/api/suppliers/orders/{id}/cancel-reception	PUT	Cancel the reception of a supplier order.		Status Description 304 Product stock of the order had a problem. 400 No corresponding supplier order. 409 Supplier order is not received.
/api/suppliers/orders/{id}	DELETE	Delete a supplier order.		Status Description 400 No corresponding supplier order. 412 Supplier order is too old.
/api/suppliers/orders/{id}/force	DELETE	Delete a supplier order by force.		Status Description 400 No corresponding supplier order.

4.5.2 Supplier order lines

Endpoint	Method	Description	Request Body	HTTP Status
/api/suppliers/orders/order={orderId}/details	GET	Get all supplier order lines of a supplier order.		Status Description 204 No supplier order lines found. 400 No corresponding supplier order.
api/suppliers/orders/order={orderId}/details/product={productId}	GET	Get a supplier order line of a supplier order.		Status Description 204 No supplier order line found. 400 No corresponding supplier order or product.
/api/suppliers/orders/order={orderId}/details/product={productId}	PUT	Update a supplier order line of a supplier order.	Field Type Description quantity Integer Quantity of the product. buyPrice Double Buy price of the product.	Status Description 400 Supplier order not found ; product not found. 409 Supplier order already exists. 412 Supplier order is already sent ; wrong product supplier ; invalid quantity.
/api/suppliers/orders/order={orderId}/details/product={productId}	DELETE	Delete a supplier order line of a supplier order.		Status Description 400 No corresponding supplier order line. 412 Supplier order is already sent.

---

4.6 Brands

Endpoint	Method	Description	Request Body	HTTP Status
/api/brands	GET	Get all brands.		Status Description 204 No brand found.
/api/brands/{id}	GET	Get a brand.		Status Description 400 No brand found.
/api/brands	POST	Create a brand.	Field Type Description name String Name of the brand.	Status Description 400 Brand already exists, or the name is null or empty. 409 Brand name already exists.
/api/brands/{id}	DELETE	Delete a brand.		Status Description 400 Brand not found. 409 Brand has related products.

---

4.7 Categories

Endpoint	Method	Description	Request Body	HTTP Status
/api/categories	GET	Get all categories.		Status Description 204 No category found.
/api/categories/{id}	GET	Get a category.		Status Description 400 No category found.
/api/categories	POST	Create a category.	Field Type Description name String Name of the category. description String Name of the category.	Status Description 400 Category name is null or empty. 409 Category name already exists.
/api/categories/{id}	PUT	Update a category description.	Field Type Description name String Name of the category. description String Name of the category.	Status Description 400 Category not found.
/api/categories/{id}	DELETE	Delete a category.		Status Description 400 Category not found. 409 Category has related products.

---

4.8 Products

Endpoint	Method	Description	Request Body	HTTP Status
/api/products	GET	Get all products.		Status Description 204 No product found.
/api/products/{id}	GET	Get a product.		Status Description 400 No product found.
/api/products/{id}/details	GET	Get product details.		Status Description 400 No product found.
/api/products/low	GET	Get all products with low stock.		Status Description 204 No product found.
/api/products	POST	Create a product.	Field Type Description name String Name of the product. description String Description of the product. purchasePrice Double Purchase price of the product. salePrice Double Sale price of the product. stock Integer Stock of the product. minStock Integer Minimum stock of the product. batchSize Integer Batch size of the product. brandId Long Brand id of the product. categoryId Long Category id of the product. supplierId Long Supplier id of the product.	Status Description 400 Invalid product information. 404 Category, brand, or supplier not found. 409 Product already exists by name and supplier id.
/api/products/{id}	PUT	Update a product.	Field Type Description name String Name of the product. description String Description of the product. purchasePrice Double Purchase price of the product. salePrice Double Sale price of the product. stock Integer Stock of the product. minStock Integer Minimum stock of the product. batchSize Integer Batch size of the product. brandId Long Brand id of the product. categoryId Long Category id of the product. supplierId Long Supplier id of the product.	Status Description 400 Invalid product information. 404 Category, brand, or supplier not found.
/api/products/{id}	DELETE	Delete a product.		Status Description 400 Product not found. 409 Product has relationships.