Package com.v1rex.liftnexus.transportorder.service

Class TransportOrderService

java.lang.Object
com.v1rex.liftnexus.transportorder.service.TransportOrderService
@Service public class TransportOrderService extends Object
Service layer responsible for managing transport orders within the warehouse system.

Handles the full lifecycle of a transport order: creation, status transitions, assignment to forklifts, and retrieval. All public methods enforce business rules such as ensuring the load unit is physically present at the source bin before a transport order can be created.

  • Constructor Details

    • TransportOrderService

      public TransportOrderService()

  • Method Details

    • createTransportOrder

      @Transactional public TransportOrderResponse createTransportOrder(TransportOrderRequest request)
      Creates a new transport order that moves a load unit from a source storage bin to a destination storage bin.

      Validates that the specified load unit is currently located in the requested source bin before proceeding. Throws an exception if the load unit is not present at the source location.

      Parameters:
      request - DTO containing the target load unit ID, source bin ID, and destination bin ID.
      Returns:
      The persisted transport order wrapped in a response DTO.
      Throws:
      TransportOrderInvalidStateException - if the load unit is not in the specified source bin.

    • updateOrderStatus

      @Transactional public TransportOrderResponse updateOrderStatus(Long id, TransportOrderStatusUpdateRequest request)
      Advances (or changes) the status of an existing transport order.

      Applies state-machine rules defined in checkStatusBeforeUpdate(java.lang.Long, com.v1rex.liftnexus.transportorder.domain.TransportOrderStatus, com.v1rex.liftnexus.transportorder.domain.TransportOrderStatus) to prevent invalid transitions such as rolling back from IN_PROGRESS to OPEN or mutating a completed order.

      Parameters:
      id - The unique identifier of the transport order to update.
      request - DTO carrying the desired new status.
      Returns:
      The updated transport order wrapped in a response DTO.
      Throws:
      TransportOrderNotFoundException - if no order exists for the given ID.
      TransportOrderInvalidStateException - if the requested transition is not allowed.

    • findById

      @Transactional(readOnly=true) public TransportOrderResponse findById(Long id)
      Looks up a transport order by its ID and returns the response DTO.
      Parameters:
      id - The unique identifier of the transport order.
      Returns:
      The transport order response DTO.
      Throws:
      TransportOrderNotFoundException - if no order exists for the given ID.

    • searchOrders

      @Transactional(readOnly=true) public org.springframework.data.domain.Page<TransportOrderResponse> searchOrders(TransportOrderStatus status, Integer minWeight, org.springframework.data.domain.Pageable pageable)
      Searches for transport orders with optional filters and pagination.
      Parameters:
      status - Optional status filter (may be null).
      minWeight - Optional minimum weight filter (may be null).
      pageable - Pagination and sorting information.
      Returns:
      A page of matching transport order response DTOs.

    • findEntityById

      @Transactional(readOnly=true) public TransportOrder findEntityById(Long id)
      Retrieves the raw TransportOrder entity by its ID.

      This is used internally by other service methods that need to work with the managed JPA entity rather than the response DTO.

      Parameters:
      id - The unique identifier of the transport order.
      Returns:
      The managed TransportOrder entity.
      Throws:
      TransportOrderNotFoundException - if no order exists for the given ID.

    • findAllEntities

      public List<TransportOrder> findAllEntities()
      Returns all transport order entities without pagination.

      Caution: This method should only be used in batch/background operations where fetching the full dataset is acceptable (e.g., scheduled forklift-assignment jobs). Prefer the paginated searchOrders(com.v1rex.liftnexus.transportorder.domain.TransportOrderStatus, java.lang.Integer, org.springframework.data.domain.Pageable) method for user-facing features.

      Returns:
      A list of every TransportOrder in the database.

    • updateForkliftAssignments

      @Transactional public void updateForkliftAssignments(List<TransportOrder> orders)
      Assigns forklifts to a list of transport orders and transitions them to the TransportOrderStatus.ASSIGNED state.

      Each order in the provided list is fetched from the database to obtain the managed entity, then updated with the assigned forklift reference. The status is automatically advanced to ASSIGNED.

      Parameters:
      orders - List of transport order entities carrying at least the ID and the desired forklift assignment.

    • findAllEntitiesForPlanning

      @Transactional(readOnly=true) public List<TransportOrder> findAllEntitiesForPlanning()
      Retrieves all TransportOrder entities with the object graph required by the Timefold solver.

      This is an internal method for planning use cases. It intentionally loads load units, source bins, target bins and assigned forklifts because the solver evaluates constraints outside the Hibernate session.

      Do not use this method for normal paginated REST API access.

      Returns:
      an unmodifiable list of all planning-ready TransportOrder entities