feat: update the facade

Author: serggalel

src/main/java/com/itasocialacademy/oitassist/user/api/facade/UserFacadeImpl.java

@@ -99,4 +99,12 @@ public Optional<UserProfileDetails> findProfileById(Long userId) {
     public List<UserProfileDetails> findProfilesByIds(List<Long> userIds) {
         return userService.findProfilesDetailsByIds(userIds);
     }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public Optional<List<Long>> findUserIdsBySearchWithinIds(String search, List<Long> candidateIds) {
+        return userService.findUserIdsBySearch(search, candidateIds);
+    }
 }

src/main/java/com/itasocialacademy/oitassist/user/api/interfaces/UserFacade.java

@@ -135,4 +135,21 @@ public interface UserFacade {
      * omitted from the result, consistent with {@link #findByIds}.
      */
     List<UserProfileDetails> findProfilesByIds(List<Long> userIds);
+
+    /**
+     * Filters a provided list of candidate user IDs based on a text search against
+     * the user's first name, surname or email, required by {@code participation}
+     * module.
+     * <p>
+     * This method is designed to perform a constrained search. Instead of searching
+     * the entire database, it only searches within the provided
+     * {@code candidateIds}.
+     * </p>
+     *
+     * @param search       the text search query (e.g., "Ivan", "ivan@email.com").
+     * @param candidateIds the pool of user IDs to restrict the search to.
+     * @return an {@code Optional} containing the filtered list of matching user
+     *         IDs, or {@code Optional.empty()} if the search string is null/blank.
+     */
+    Optional<List<Long>> findUserIdsBySearchWithinIds(String search, List<Long> candidateIds);
 }