Package com.v1rex.liftnexus.forklift.service

Class ForkliftService

java.lang.Object
com.v1rex.liftnexus.forklift.service.ForkliftService
@Service public class ForkliftService extends Object
Service layer for the Forklift bounded context.

Manages the full lifecycle of warehouse forklifts: registration, location tracking, operational status updates, and assignment of transport orders during solver solution persistence. Cross-domain communication follows the anti-corruption rule — all external entity lookups go through the respective service interfaces, never directly through repositories.

  • Constructor Details

    • ForkliftService

      public ForkliftService()

  • Method Details

    • createForklift

      @Transactional public ForkliftResponse createForklift(ForkliftRequest request)
      Registers a new forklift in the warehouse fleet.

      Validates that the fleet number is unique, resolves the forklift type (archetype) and optional initial storage bin from their respective domains, persists the aggregate, and returns a ForkliftResponse DTO.

      Parameters:
      request - the inbound payload containing fleet number, type ID, and optional initial storage bin ID (must not be null, must pass validation)
      Returns:
      a DTO representing the newly created forklift
      Throws:
      ForkliftFleetNumberExistsException - if a forklift with the given fleet number already exists in the system

    • findById

      @Transactional(readOnly=true) public ForkliftResponse findById(Long id)
      Retrieves a single forklift by its unique identifier.
      Parameters:
      id - the forklift's database identifier (must be positive and exist)
      Returns:
      a DTO representing the forklift
      Throws:
      ForkliftNotFoundException - if no forklift with that ID is found

    • findAll

      @Transactional(readOnly=true) public org.springframework.data.domain.Page<ForkliftResponse> findAll(org.springframework.data.domain.Pageable pageable)
      Returns a paginated list of all forklifts in the system.
      Parameters:
      pageable - pagination and sorting parameters (default sort: id ascending)
      Returns:
      a page of forklift DTOs

    • findWithCapacityGreaterThan

      @Transactional(readOnly=true) public org.springframework.data.domain.Page<ForkliftResponse> findWithCapacityGreaterThan(Integer minCapacity, org.springframework.data.domain.Pageable pageable)
      Searches for forklifts by minimum lifting capacity or operational status.

      If minCapacity is provided, results are filtered by the forklift type's max capacity.

      Parameters:
      minCapacity - the minimum weight capacity in kilograms (optional, >= 1)
      pageable - pagination parameters (default size: 10, sort: fleetNumber)
      Returns:
      a page of matching forklift DTOs

    • findByStatus

      @Transactional(readOnly=true) public org.springframework.data.domain.Page<ForkliftResponse> findByStatus(OperationalStatus status, org.springframework.data.domain.Pageable pageable)
      Searches for forklifts by operational status.
      Parameters:
      status - the operational status to filter by (e.g. ACTIVE, OFFLINE)
      pageable - pagination parameters
      Returns:
      a page of forklift DTOs matching the given status

    • updateForkliftLocation

      @Transactional public ForkliftResponse updateForkliftLocation(Long forkliftId, Long locationId)
      Moves a forklift to a new storage bin location.

      This operation updates the physical location of the forklift within the warehouse. Both the forklift and the target bin must exist.

      Parameters:
      forkliftId - the identifier of the forklift to relocate
      locationId - the identifier of the destination storage bin
      Returns:
      a DTO representing the updated forklift
      Throws:
      ForkliftNotFoundException - if no forklift with the given ID exists

    • updateOperationalStatus

      @Transactional public ForkliftResponse updateOperationalStatus(Long forkliftId, OperationalStatus status)
      Transitions a forklift's operational status (e.g. from OFFLINE to ACTIVE).
      Parameters:
      forkliftId - the identifier of the target forklift
      status - the new operational status
      Returns:
      a DTO representing the updated forklift
      Throws:
      ForkliftNotFoundException - if no forklift with the given ID exists

    • findEntityById

      @Transactional(readOnly=true) public Forklift findEntityById(Long id)
      Internal domain-level lookup: retrieves the managed Forklift entity by its ID.

      This method is exposed to other services within the same domain and to the planning service for solution persistence. External consumers receive a DTO; only domain-internal callers should use the entity directly.

      Parameters:
      id - the forklift's database identifier
      Returns:
      the persistent Forklift entity
      Throws:
      ForkliftNotFoundException - if no entity with that ID exists

    • findAllEntities

      @Transactional(readOnly=true) public org.springframework.data.domain.Page<Forklift> findAllEntities(org.springframework.data.domain.Pageable pageable)
      Returns a paginated list of raw Forklift entities for internal domain usage.
      Parameters:
      pageable - pagination and sorting parameters
      Returns:
      a page of Forklift entities

    • findAllEntities

      @Transactional(readOnly=true) public List<Forklift> findAllEntities()
      Returns all Forklift entities without pagination for solver consumption.

      Performance note: This method loads the entire fleet into memory and is called during WarehouseDispatcherService.buildCurrentState(). For large warehouses, consider paginated or selective fetching (addressed in Milestone 2).

      Returns:
      a list of all Forklift entities in the database

    • updateAssignedOrders

      @Deprecated @Transactional public void updateAssignedOrders(List<Forklift> forklifts)
      Deprecated.
      Persists the solver's assignment results back to the database.

      Called by WarehouseDispatcherService.saveFinalSolution() after the Timefold solver produces a solution. This method performs a bulk ID lookup to ensure all referenced forklifts exist before applying any assignment changes. If a forklift was deleted between solver completion and persistence, the operation fails with an IllegalStateException to prevent partial updates.

      Each database forklift's transport order list is cleared and repopulated with the solver-determined assignments.

      Parameters:
      forklifts - the list of solver-state forklifts containing updated order assignments
      Throws:
      IllegalStateException - if one or more forklift IDs from the solver solution no longer exist in the database (stale data)

    • findAllEntitiesForPlanning

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

      This is an internal method for planning use cases. It intentionally loads the full planning-relevant graph, including forklift type, current location and assigned transport orders, because the solver runs asynchronously outside the Hibernate session.

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

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