From 355f09c231122017d9a7f4beeac544aa15ee5e91 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sat, 24 May 2025 02:55:18 +0000 Subject: [PATCH 1/2] I've added comprehensive documentation to the README and included a LICENSE file. This commit introduces a detailed README.md file for the warehouse-service project, covering the following aspects: - Overview: Project purpose, main features, and technologies used. - Getting Started: Prerequisites, build instructions, and how to run the application using Docker Compose or locally. - Project Structure: Explanation of the main source code directories and their roles. - API Documentation: Information on accessing the Springdoc-generated OpenAPI documentation and Swagger UI. - Configuration: Details on service configuration via application.yml and environment variables. - Events: How the service uses RabbitMQ for event-driven communication and the main events handled. - Database: Information about database usage, main entities, and configuration. - Contributing: General guidelines for potential contributors. - License: Specifies that the project is licensed under Apache 2.0. Additionally, a `LICENSE` file containing the full text of the Apache License 2.0 has been added to the root of the repository. --- LICENSE | 201 ++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 217 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 417 insertions(+), 1 deletion(-) create mode 100644 LICENSE 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..7fc67a4 100644 --- a/README.md +++ b/README.md @@ -1 +1,216 @@ -# 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). + +#### Locally (without Docker) + +It is also possible to run the service locally without Docker. However, this requires you to set up and configure PostgreSQL, RabbitMQ, and Redis servers separately. You will need to update the connection details for these services in the `src/main/resources/application.yml` file. + +Once the external services are running and configured, you can start the application using the following Maven command: + +```bash +./mvnw spring-boot:run +``` + +## 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. From 9e66222e8cb2d289adc91892753c7001bdb0c59c Mon Sep 17 00:00:00 2001 From: Ahmed Haitham Date: Sat, 24 May 2025 06:01:31 +0300 Subject: [PATCH 2/2] Update README.md --- README.md | 9 --------- 1 file changed, 9 deletions(-) diff --git a/README.md b/README.md index 7fc67a4..f46b53c 100644 --- a/README.md +++ b/README.md @@ -62,15 +62,6 @@ docker-compose up -d The service will be available at `http://localhost:8080` (or the port configured in `docker-compose.yml` or your environment). -#### Locally (without Docker) - -It is also possible to run the service locally without Docker. However, this requires you to set up and configure PostgreSQL, RabbitMQ, and Redis servers separately. You will need to update the connection details for these services in the `src/main/resources/application.yml` file. - -Once the external services are running and configured, you can start the application using the following Maven command: - -```bash -./mvnw spring-boot:run -``` ## Project Structure