feat: CARITAS-286

* create new endpoint to return an agency by postcode and topic id for the current tenant

api/agencyservice.yaml

@@ -75,6 +75,46 @@ paths:
           description: FORBIDDEN - no/invalid CSRF token
         500:
           description: INTERNAL SERVER ERROR - server encountered unexpected condition
+  /agencies/private:
+    get:
+      tags:
+        - agency-controller
+      summary: 'Returns a list of agencies from a specific tenant. If no agency is found No Content
+        is being returned. [Authorization: none]'
+      operationId: getTenantAgencies
+      parameters:
+        - name: postcode
+          in: query
+          required: true
+          description: The postcode the user entered
+          schema:
+            type: string
+            minLength: 5
+            maxLength: 5
+            example: "56789"
+        - name: topicId
+          in: query
+          required: true
+          description: The main topic of the registration form
+          schema:
+            type: integer
+            format: int32
+            example: 7
+      responses:
+        200:
+          description: OK - successfull operation
+          content:
+            'application/json':
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/FullAgencyResponseDTO'
+        400:
+          description: BAD REQUEST - invalid/incomplete request or body object
+        403:
+          description: FORBIDDEN - no/invalid CSRF token
+        500:
+          description: INTERNAL SERVER ERROR - server encountered unexpected condition
   /agencies/topics:
     get:
       tags:

src/main/java/de/caritas/cob/agencyservice/api/controller/AgencyController.java

@@ -57,6 +57,25 @@ public ResponseEntity<List<FullAgencyResponseDTO>> getAgencies(
         : new ResponseEntity<>(HttpStatus.NO_CONTENT);
   }
 
+  /**
+   * Gets a randomly sorted list of AgencyResponseDTOs (from database) and returns the list and a
+   * 200 OK on success depending on the post code that is given via query parameter.
+   *
+   * @param postcode       the postcode for regarding agencies
+   * @param topicId        the (optional) main topicId to filter the agencies
+   * @return the List of agencies with information
+   */
+  @Override
+  public ResponseEntity<List<FullAgencyResponseDTO>> getTenantAgencies(String postcode,
+      Integer topicId) {
+
+    var agencies = agencyService.getAgencies(postcode, topicId);
+
+    return !CollectionUtils.isEmpty(agencies)
+        ? new ResponseEntity<>(agencies, HttpStatus.OK)
+        : new ResponseEntity<>(HttpStatus.NO_CONTENT);
+  }
+
   /**
    * Returns information of the provided agencies.
    *

src/main/java/de/caritas/cob/agencyservice/api/service/AgencyService.java

@@ -69,6 +69,8 @@ public class AgencyService {
   @Value("${feature.multitenancy.with.single.domain.enabled}")
   private boolean multitenancyWithSingleDomain;
 
+  private static final String DB_POSTCODES_ERROR = "Database error while getting postcodes";
+
   /**
    * Returns a list of {@link AgencyResponseDTO} which match the provided agencyIds.
    *
@@ -142,6 +144,23 @@ public List<FullAgencyResponseDTO> getAgencies(Optional<String> postCode,
     return mutableResponseDTO;
   }
 
+  /**
+   * Returns a list of {@link AgencyResponseDTO} from the current tenant, which match to the provided
+   * postCode. If no agency is found, returns empty list.
+   *
+   * @param postCode the postcode for regarding agencies
+   * @param topicId  the topic id used for filtering agencies
+   * @return a list containing regarding agencies
+   */
+  public List<FullAgencyResponseDTO> getAgencies(String postCode, Integer topicId) {
+
+    var agencies = findAgencies(postCode, topicId);
+    Collections.shuffle(agencies);
+    return agencies.stream()
+        .map(this::convertToFullAgencyResponseDTO)
+        .toList();
+  }
+
   public List<Integer> getAgenciesTopics() {
     return agencyRepository.findAllAgenciesTopics();
   }
@@ -175,6 +194,16 @@ private List<Agency> findAgencies(Optional<String> postCode, Optional<Integer> c
     }
   }
 
+  private List<Agency> findAgencies(String postCode, Integer topicId) {
+
+    AgencySearch agencySearch = AgencySearch.builder()
+        .postCode(Optional.of(postCode))
+        .topicId(Optional.of(topicId))
+        .build();
+
+    return findAgenciesWithTopicForCurrentTenant(agencySearch);
+  }
+
   private List<Agency> findAgencies(AgencySearch agencySearch) {
     try {
       return getAgencyRepositoryForSearch()
@@ -186,7 +215,7 @@ private List<Agency> findAgencies(AgencySearch agencySearch) {
               TenantContext.getCurrentTenant());
     } catch (DataAccessException ex) {
       throw new InternalServerErrorException(LogService::logDatabaseError,
-          "Database error while getting postcodes");
+          DB_POSTCODES_ERROR);
     }
   }
 
@@ -250,7 +279,23 @@ private List<Agency> findAgenciesWithTopic(AgencySearch agencySearch) {
 
     } catch (DataAccessException ex) {
       throw new InternalServerErrorException(LogService::logDatabaseError,
-          "Database error while getting postcodes");
+          DB_POSTCODES_ERROR);
+    }
+  }
+
+  private List<Agency> findAgenciesWithTopicForCurrentTenant(AgencySearch agencySearch) {
+    try {
+      return agencyRepository
+          .searchWithTopic(agencySearch.getPostCode().orElse(null), agencySearch.getPostCode().orElse("").length(),
+              agencySearch.getConsultingTypeId().orElse(null),
+              agencySearch.getTopicId().orElseThrow(),
+              agencySearch.getAge().orElse(null), agencySearch.getGender().orElse(null),
+              agencySearch.getCounsellingRelation().orElse(null),
+              TenantContext.getCurrentTenant());
+
+    } catch (DataAccessException ex) {
+      throw new InternalServerErrorException(LogService::logDatabaseError,
+          DB_POSTCODES_ERROR);
     }
   }