diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..b09cd78 --- /dev/null +++ b/LICENSE @@ -0,0 +1,201 @@ +Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/README.md b/README.md index 36f5540..f46b53c 100644 --- a/README.md +++ b/README.md @@ -1 +1,207 @@ -# warehouse +# Warehouse Management Service + +## Overview + +This service is a warehouse management system designed to handle order and inventory operations. + +### Main Features + +* **Stock Management:** Keeps track of inventory levels, item locations, and stock movements. +* **Order Processing:** Manages the entire order lifecycle, including: + * Order assignment to relevant personnel. + * Packaging of orders. +* **User Role Management:** Defines and manages different user roles within the system, such as: + * Assigners: Responsible for assigning orders. + * Managers: Oversee warehouse operations. + * Packagers: Handle the packaging of orders. + +### Technologies Used + +* **Programming Language:** Java 23 +* **Framework:** Spring Boot 3.4.5 +* **Build Tool:** Maven +* **Containerization:** Docker +* **Message Broker:** RabbitMQ +* **Database:** PostgreSQL +* **Caching:** Redis +* **API Documentation:** Springdoc +* **Utility Library:** Lombok + +## Getting Started + +### Prerequisites + +- Java JDK 23 or later +- Maven 3.6.x or later +- Docker Engine and Docker Compose (for running with Docker) +- RabbitMQ server (if not using Docker) +- PostgreSQL server (if not using Docker) +- Redis server (if not using Docker) + +### Building the Project + +To build the project, navigate to the root directory and run the following Maven command: + +```bash +./mvnw clean install +``` + +This command will compile the code, run tests, and package the application. + +### Running the Project + +#### With Docker Compose + +The easiest way to run the project along with its dependencies (PostgreSQL, RabbitMQ, Redis) is by using the provided `docker-compose.yml` file. + +Navigate to the root directory and run: + +```bash +docker-compose up -d +``` + +The service will be available at `http://localhost:8080` (or the port configured in `docker-compose.yml` or your environment). + + +## Project Structure + +The main application code is located in `src/main/java/com/podzilla/warehouse`. Below is an overview of the key directories and their purposes: + +- **`Commands`**: Contains classes representing commands that can be executed within the application (e.g., `CreateStockCommand`, `AssignOrderCommand`). These are often used to encapsulate operations that modify the system's state. +- **`Config`**: Holds configuration classes for various parts of the application. This includes beans for `RedisConfig`, `SecurityConfig`, message queues, and other infrastructure components. +- **`Controllers`**: Includes Spring MVC controllers that handle incoming HTTP requests and define API endpoints. Examples include `StockController` for stock-related operations and `ManagerController` for manager-specific actions. +- **`Events`**: Contains classes related to event handling, particularly for messages received from RabbitMQ. This includes event handlers like `OrderPlacedEventHandler` and listeners such as `RabbitMqEventListener`. +- **`Models`**: Defines the data model entities (POJOs) used in the application, which are typically mapped to database tables. Examples are `Stock`, `AssignedOrders`, and `Packager`. +- **`Repositories`**: Contains Spring Data JPA repositories that provide an abstraction layer for database interactions with the entities. Examples include `StockRepository` and `AssignedOrdersRepository`. +- **`Services`**: Holds the core business logic of the application. Services mediate between controllers (or event handlers/commands) and repositories, orchestrating operations and ensuring data integrity. Examples are `StockService` and `AssignerService`. +- **`WarehouseApplication.java`**: The main Spring Boot application class. This class contains the `main` method and is responsible for bootstrapping the entire service. + +## API Documentation + +This service utilizes Springdoc to automatically generate OpenAPI 3.0 documentation for the RESTful APIs. + +Once the application is running, you can access the following: + +- **Swagger UI**: An interactive web UI that allows you to explore and test the API endpoints. + It is available at `/swagger-ui.html`. + For example, if the application is running locally on port 8080, you can access it at `http://localhost:8080/swagger-ui.html`. + +- **OpenAPI Specification (JSON)**: The raw OpenAPI 3.0 specification in JSON format. + It is available at `/v3/api-docs`. + For example, if the application is running locally on port 8080, you can access it at `http://localhost:8080/v3/api-docs`. + +## Configuration + +The primary configuration for the Warehouse Management Service is located in the `src/main/resources/application.yml` file. + +Spring Boot's externalized configuration mechanism is used, which means that many properties defined in `application.yml` can be overridden using: +- Environment variables (e.g., `SPRING_DATASOURCE_URL` overrides `spring.datasource.url`). +- Command-line arguments (e.g., `--spring.datasource.url=jdbc:...`). +- Other Spring Boot supported configuration sources. + +Refer to the [Spring Boot Externalized Configuration documentation](https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.external-config) for more details. + +### Key Configuration Sections + +Below are some of the main configuration sections found in `application.yml`: + +- **`server.servlet.context-path`**: Sets the base path for the API (e.g., `/api`). If not set, the application will be served from the root context (`/`). +- **`spring.datasource`**: Configures the connection to the primary PostgreSQL database. + - `url`: JDBC URL of the database. + - `username`: Database username. + - `password`: Database password. + - `driver-class-name`: The JDBC driver class (e.g., `org.postgresql.Driver`). + *(The project includes commented-out settings for an H2 in-memory database which can be useful for local development or testing.)* +- **`spring.jpa`**: Configures JPA (Java Persistence API) and Hibernate properties. + - `hibernate.ddl-auto`: Strategy for schema generation (e.g., `update`, `validate`, `create`, `create-drop`, `none`). **Use with caution in production.** + - `show-sql`: Enables logging of SQL statements generated by Hibernate. + - `properties.hibernate.dialect`: Specifies the SQL dialect (e.g., `org.hibernate.dialect.PostgreSQLDialect`). +- **`spring.rabbitmq`**: Configures the connection to the RabbitMQ message broker. + - `host`: RabbitMQ server host. + - `port`: RabbitMQ server port (default is 5672). + - `username`: RabbitMQ username. + - `password`: RabbitMQ password. +- **`spring.data.redis`**: Configures the connection to the Redis server for caching and other purposes. + - `host`: Redis server host. + - `port`: Redis server port (default is 6379). + - *(Other properties like password, SSL can also be configured here.)* +- **`spring.cache.type`**: Specifies the default cache provider to be used. For this project, it's typically set to `redis` to leverage Redis for caching. +- **`appconfig.cache.enabled`**: A custom application property that can be used to globally enable or disable caching features within the application. This allows for easily toggling caching without changing individual cache configurations. + +For a complete list of configurable properties and their default values, please refer directly to the `src/main/resources/application.yml` file. + +## Events + +The Warehouse Management Service employs an event-driven architecture, using RabbitMQ for asynchronous communication with other services. This allows for decoupled and resilient interactions. + +Incoming events are primarily consumed by the `RabbitMqEventListener` class located in the `com.podzilla.warehouse.Events` package. This listener acts as a central point for RabbitMQ messages and typically delegates the processing to specific event handler methods based on the type or routing key of the incoming event. + +### Main Events Handled + +The service listens for and processes the following key events: + +- **Order Placed Event**: + - **Trigger**: Received when a new order is successfully placed in an external service (e.g., an Order Management Service). + - **Purpose**: This event typically initiates processes within the warehouse, such as checking available stock for the ordered items, potentially reserving stock, and preparing for order assignment and packaging. +- **Order Cancelled Event**: + - **Trigger**: Received when an existing order is cancelled in an external service. + - **Purpose**: This event may involve releasing any stock that was previously reserved for the cancelled order, updating inventory records, and potentially halting any ongoing processes related to that order. +- **Order Stock Reservation Event**: + - **Trigger**: This event is likely related to the outcome or status of a stock reservation attempt made for an order, possibly originating from this service or another. + - **Purpose**: It could confirm that stock has been successfully reserved, indicate a failure to reserve stock (e.g., due to insufficient inventory), or update the status of a reservation. + +### Configuration + +The connection details for the RabbitMQ server (such as host, port, username, and password) are configured in the `src/main/resources/application.yml` file under the `spring.rabbitmq` section. + +Specific queue names, exchange names, and routing keys are defined within the event listener classes (e.g., using `@RabbitListener` annotations) or in dedicated RabbitMQ configuration classes within the `com.podzilla.warehouse.Config` package. For precise details on these, refer to the source code. + +## Database + +The Warehouse Management Service utilizes a relational database to persist its core data. While the primary target database is PostgreSQL, the application is often configured with an H2 in-memory database for development and testing purposes. + +Interaction with the database is managed through Spring Data JPA, which simplifies data access layers. The JPA entities, representing the database tables, are defined in the `com.podzilla.warehouse.Models` package. + +### Main Entities + +- **`Stock`**: Represents products or items available in the warehouse. This entity typically includes details such as item name, quantity on hand, location, and other relevant product information. +- **`Assigner`**: Represents users within the system who have the role and responsibility of assigning incoming orders to available packagers. +- **`Packager`**: Represents users who are responsible for the physical act of picking items from stock and packaging them for shipment according to order details. +- **`Manager`**: Represents users who have administrative or oversight roles within the warehouse system. They might have permissions to manage users, view reports, or configure system settings. +- **`AssignedOrders`**: Tracks orders that have been assigned to a specific packager and are currently in the process of being prepared. This entity likely links order identifiers (which may originate from external events) to `Packager` entities and potentially to the `Stock` items involved. +- **`PackagedOrders`**: Represents orders that have been fully packaged and are ready for the next stage in the fulfillment process, such as shipment or dispatch. + +### Configuration and Schema Management + +Database connection details (URL, username, password, driver class) are configured in the `src/main/resources/application.yml` file under the `spring.datasource` section. + +Schema management, including the creation and updating of database tables based on the JPA entities, is handled by Hibernate (the default JPA provider in Spring Boot) through the `spring.jpa.hibernate.ddl-auto` property. +- For **development and testing**, this is often set to `create` (tables are created at startup, dropping existing ones) or `create-drop` (tables are dropped when the application context closes). +- For **production environments**, it is typically set to `update` (attempts to update the schema to match entities, adding new columns/tables but not removing existing ones) or `validate` (validates that the schema matches the entities and throws an error if not). It's crucial to use `ddl-auto` with caution in production and prefer managed database migration tools for significant changes. + +## Contributing + +We welcome contributions to the Warehouse Management Service! If you're interested in helping to improve the project, please follow these general guidelines: + +1. **Fork the repository** on GitHub. +2. **Create a new branch** for your feature or bug fix from the `main` branch. + ```bash + git checkout -b feature/your-feature-name + # or + git checkout -b bugfix/issue-number + ``` +3. **Make your changes**, adhering to the existing code style and conventions. +4. **Add or update tests** as appropriate to cover your changes. +5. **Ensure all tests pass** locally before pushing. +6. **Commit your changes** with clear and descriptive commit messages. +7. **Push your branch** to your forked repository. +8. **Create a pull request** against the `main` branch of the original repository. + +The project maintainers will review your pull request, provide feedback, and merge it if everything looks good. We appreciate your contributions! + +## License + +This project is licensed under the Apache License 2.0. You can find the full license text here: +[Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0) + +See the `LICENSE` file for more details.