feat(fts): replace ILIKE hasText with FTS two-phase search and RELEVANCE sort

- DocumentSort: add RELEVANCE enum value
- DocumentSpecifications: remove hasText() ILIKE, add hasIds(List<UUID>)
  for FTS-pre-filtered ID sets
- DocumentService.searchDocuments(): FTS two-phase path — findRankedIdsByFts()
  returns ranked UUIDs, hasIds() narrows subsequent Specification query,
  in-memory re-sort preserves rank order; RELEVANCE is the default when
  text is present and no explicit non-relevance sort is requested
- DocumentSpecificationsTest: remove hasText() tests (Specification removed)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

backend/src/main/java/org/raddatz/familienarchiv/dto/DocumentSort.java

@@ -1,5 +1,5 @@
 package org.raddatz.familienarchiv.dto;
 
 public enum DocumentSort {
-    DATE, TITLE, SENDER, RECEIVER, UPLOAD_DATE
+    DATE, TITLE, SENDER, RECEIVER, UPLOAD_DATE, RELEVANCE
 }

backend/src/main/java/org/raddatz/familienarchiv/repository/DocumentSpecifications.java

@@ -8,78 +8,17 @@ import java.util.UUID;
 
 import org.raddatz.familienarchiv.model.Document;
 import org.raddatz.familienarchiv.model.DocumentStatus;
-import org.raddatz.familienarchiv.model.Person;
-import org.raddatz.familienarchiv.model.PersonNameAlias;
 import org.raddatz.familienarchiv.model.Tag;
 import org.springframework.data.jpa.domain.Specification;
 import org.springframework.util.StringUtils;
 
 public class DocumentSpecifications {
 
-    // Filtert nach Text (in Titel, Dateiname, Transkription, Ort, Absender- und Empfängername, Tags)
-    public static Specification<Document> hasText(String text) {
+    // Filtert nach einer vorberechneten ID-Liste (aus FTS-Abfrage)
+    public static Specification<Document> hasIds(List<UUID> ids) {
         return (root, query, cb) -> {
-            if (!StringUtils.hasText(text))
-                return null;
-            String likePattern = "%" + text.toLowerCase() + "%";
-
-            // LEFT JOIN on sender (ManyToOne — no duplicate rows)
-            Join<Document, Person> senderJoin = root.join("sender", JoinType.LEFT);
-
-            // LEFT JOIN sender → aliases (entity-graph navigation avoids a separate DB
-            // roundtrip while respecting domain boundaries — the alias table is part of
-            // the Person aggregate, navigated via @OneToMany, not via a cross-domain
-            // repository call from DocumentService)
-            Join<Person, PersonNameAlias> senderAliasJoin = senderJoin.join("nameAliases", JoinType.LEFT);
-
-            // EXISTS subquery for receiver name — avoids duplicate rows for multi-receiver docs
-            Subquery<Long> receiverSub = query.subquery(Long.class);
-            Root<Document> receiverRoot = receiverSub.from(Document.class);
-            Join<Document, Person> receiverJoin = receiverRoot.join("receivers");
-            receiverSub.select(cb.literal(1L))
-                    .where(
-                            cb.equal(receiverRoot.get("id"), root.get("id")),
-                            cb.or(
-                                    cb.like(cb.lower(receiverJoin.get("lastName")), likePattern),
-                                    cb.like(cb.lower(cb.coalesce(receiverJoin.get("firstName"), "")), likePattern)
-                            )
-                    );
-
-            // EXISTS subquery for receiver alias name
-            Subquery<Long> receiverAliasSub = query.subquery(Long.class);
-            Root<Document> receiverAliasRoot = receiverAliasSub.from(Document.class);
-            Join<Document, Person> recAliasPersonJoin = receiverAliasRoot.join("receivers");
-            Join<Person, PersonNameAlias> recAliasJoin = recAliasPersonJoin.join("nameAliases");
-            receiverAliasSub.select(cb.literal(1L))
-                    .where(
-                            cb.equal(receiverAliasRoot.get("id"), root.get("id")),
-                            cb.like(cb.lower(recAliasJoin.get("lastName")), likePattern)
-                    );
-
-            // EXISTS subquery for tag name — avoids duplicate rows for multi-tag docs
-            Subquery<Long> tagSub = query.subquery(Long.class);
-            Root<Document> tagRoot = tagSub.from(Document.class);
-            Join<Document, Tag> tagJoin = tagRoot.join("tags");
-            tagSub.select(cb.literal(1L))
-                    .where(
-                            cb.equal(tagRoot.get("id"), root.get("id")),
-                            cb.like(cb.lower(tagJoin.get("name")), likePattern)
-                    );
-
-            query.distinct(true);
-
-            return cb.or(
-                    cb.like(cb.lower(root.get("title")), likePattern),
-                    cb.like(cb.lower(root.get("originalFilename")), likePattern),
-                    cb.like(cb.lower(root.get("transcription")), likePattern),
-                    cb.like(cb.lower(root.get("location")), likePattern),
-                    cb.like(cb.lower(senderJoin.get("lastName")), likePattern),
-                    cb.like(cb.lower(cb.coalesce(senderJoin.get("firstName"), "")), likePattern),
-                    cb.like(cb.lower(senderAliasJoin.get("lastName")), likePattern),
-                    cb.exists(receiverSub),
-                    cb.exists(receiverAliasSub),
-                    cb.exists(tagSub)
-            );
+            if (ids == null || ids.isEmpty()) return cb.disjunction();
+            return root.get("id").in(ids);
         };
     }
 

backend/src/main/java/org/raddatz/familienarchiv/service/DocumentService.java

@@ -20,6 +20,7 @@ import org.raddatz.familienarchiv.exception.DomainException;
 import org.raddatz.familienarchiv.exception.ErrorCode;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
+import org.springframework.util.StringUtils;
 import org.springframework.web.multipart.MultipartFile;
 
 import java.io.IOException;
@@ -290,7 +291,16 @@ public class DocumentService {
 
     // 1. Allgemeine Suche (für das Suchfeld im Frontend)
     public List<Document> searchDocuments(String text, LocalDate from, LocalDate to, UUID sender, UUID receiver, List<String> tags, String tagQ, DocumentStatus status, DocumentSort sort, String dir) {
-        Specification<Document> spec = Specification.where(hasText(text))
+        boolean hasText = StringUtils.hasText(text);
+        List<UUID> rankedIds = null;
+
+        if (hasText) {
+            rankedIds = documentRepository.findRankedIdsByFts(text);
+            if (rankedIds.isEmpty()) return List.of();
+        }
+
+        Specification<Document> textSpec = hasText ? hasIds(rankedIds) : (root, query, cb) -> null;
+        Specification<Document> spec = Specification.where(textSpec)
                 .and(isBetween(from, to))
                 .and(hasSender(sender))
                 .and(hasReceiver(receiver))
@@ -300,7 +310,6 @@ public class DocumentService {
 
         // SENDER and RECEIVER are sorted in-memory because JPA's Sort.by("sender.lastName")
         // generates an INNER JOIN that silently drops documents with null sender/receivers.
-        // TODO: replace with a native @Query using ORDER BY ... NULLS LAST when pagination is added.
         if (sort == DocumentSort.RECEIVER) {
             List<Document> results = documentRepository.findAll(spec);
             return sortByFirstReceiver(results, dir);
@@ -309,13 +318,27 @@ public class DocumentService {
             List<Document> results = documentRepository.findAll(spec);
             return sortBySender(results, dir);
         }
+
+        // RELEVANCE: default when text present and no explicit non-relevance sort requested
+        boolean useRankOrder = hasText && (sort == null || sort == DocumentSort.RELEVANCE || sort == DocumentSort.DATE);
+        if (useRankOrder) {
+            List<Document> results = documentRepository.findAll(spec);
+            final List<UUID> ids = rankedIds;
+            return results.stream()
+                    .sorted(Comparator.comparingInt(doc -> {
+                        int idx = ids.indexOf(doc.getId());
+                        return idx < 0 ? Integer.MAX_VALUE : idx;
+                    }))
+                    .toList();
+        }
+
         Sort springSort = resolveSort(sort, dir);
         return documentRepository.findAll(spec, springSort);
     }
 
     private Sort resolveSort(DocumentSort sort, String dir) {
         Sort.Direction direction = "ASC".equalsIgnoreCase(dir) ? Sort.Direction.ASC : Sort.Direction.DESC;
-        if (sort == null || sort == DocumentSort.DATE) {
+        if (sort == null || sort == DocumentSort.DATE || sort == DocumentSort.RELEVANCE) {
             return Sort.by(direction, "documentDate");
         }
         // SENDER and RECEIVER are sorted in-memory before this method is called

backend/src/test/java/org/raddatz/familienarchiv/repository/DocumentSpecificationsTest.java

@@ -7,8 +7,6 @@ import org.raddatz.familienarchiv.config.FlywayConfig;
 import org.raddatz.familienarchiv.model.Document;
 import org.raddatz.familienarchiv.model.DocumentStatus;
 import org.raddatz.familienarchiv.model.Person;
-import org.raddatz.familienarchiv.model.PersonNameAlias;
-import org.raddatz.familienarchiv.model.PersonNameAliasType;
 import org.raddatz.familienarchiv.model.Tag;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.jdbc.test.autoconfigure.AutoConfigureTestDatabase;
@@ -30,7 +28,6 @@ class DocumentSpecificationsTest {
 
     @Autowired DocumentRepository documentRepository;
     @Autowired PersonRepository personRepository;
-    @Autowired PersonNameAliasRepository aliasRepository;
     @Autowired TagRepository tagRepository;
 
     private Person sender;
@@ -79,56 +76,6 @@ class DocumentSpecificationsTest {
                 .build());
     }
 
-    // ─── hasText ──────────────────────────────────────────────────────────────
-
-    @Test
-    void hasText_returnsAllDocuments_whenTextIsNull() {
-        List<Document> result = documentRepository.findAll(Specification.where(hasText(null)));
-        assertThat(result).hasSize(3);
-    }
-
-    @Test
-    void hasText_returnsAllDocuments_whenTextIsBlank() {
-        List<Document> result = documentRepository.findAll(Specification.where(hasText("   ")));
-        assertThat(result).hasSize(3);
-    }
-
-    @Test
-    void hasText_filtersOnTitle() {
-        List<Document> result = documentRepository.findAll(Specification.where(hasText("familienfoto")));
-        assertThat(result).extracting(Document::getTitle).containsExactly("Familienfoto");
-    }
-
-    @Test
-    void hasText_filtersOnOriginalFilename() {
-        List<Document> result = documentRepository.findAll(Specification.where(hasText("brief_late")));
-        assertThat(result).extracting(Document::getTitle).containsExactly("Neuerer Brief");
-    }
-
-    @Test
-    void hasText_filtersOnTranscription() {
-        List<Document> result = documentRepository.findAll(Specification.where(hasText("schreibe dir")));
-        assertThat(result).extracting(Document::getTitle).containsExactly("Alter Brief");
-    }
-
-    @Test
-    void hasText_filtersOnLocation() {
-        List<Document> result = documentRepository.findAll(Specification.where(hasText("berlin")));
-        assertThat(result).extracting(Document::getTitle).containsExactly("Alter Brief");
-    }
-
-    @Test
-    void hasText_isCaseInsensitive() {
-        List<Document> result = documentRepository.findAll(Specification.where(hasText("BRIEF")));
-        assertThat(result).extracting(Document::getTitle).containsExactlyInAnyOrder("Alter Brief", "Neuerer Brief");
-    }
-
-    @Test
-    void hasText_returnsEmpty_whenNoMatch() {
-        List<Document> result = documentRepository.findAll(Specification.where(hasText("xyznotexist")));
-        assertThat(result).isEmpty();
-    }
-
     // ─── hasSender ────────────────────────────────────────────────────────────
 
     @Test
@@ -253,36 +200,6 @@ class DocumentSpecificationsTest {
         assertThat(result).isEmpty();
     }
 
-    @Test
-    void hasText_findsByPartialSenderLastName() {
-        List<Document> result = documentRepository.findAll(Specification.where(hasText("üller")));
-        assertThat(result).extracting(Document::getTitle)
-                .containsExactlyInAnyOrder("Alter Brief", "Neuerer Brief");
-    }
-
-    @Test
-    void hasText_findsByPartialReceiverLastName() {
-        List<Document> result = documentRepository.findAll(Specification.where(hasText("schmid")));
-        assertThat(result).extracting(Document::getTitle).containsExactly("Alter Brief");
-    }
-
-    @Test
-    void hasText_findsByPartialTagName() {
-        List<Document> result = documentRepository.findAll(Specification.where(hasText("amili")));
-        assertThat(result).extracting(Document::getTitle)
-                .containsExactlyInAnyOrder("Alter Brief", "Familienfoto");
-    }
-
-    @Test
-    void hasText_doesNotProduceDuplicatesForDocumentWithMultipleReceivers() {
-        Person receiver2 = personRepository.save(Person.builder().firstName("Karl").lastName("Schmidt").build());
-        briefEarly.setReceivers(new java.util.HashSet<>(Set.of(receiver, receiver2)));
-        documentRepository.save(briefEarly);
-
-        List<Document> result = documentRepository.findAll(Specification.where(hasText("schmid")));
-        assertThat(result).hasSize(1);
-    }
-
     // ─── hasTagPartial ────────────────────────────────────────────────────────
 
     @Test
@@ -329,26 +246,4 @@ class DocumentSpecificationsTest {
         assertThat(result).isEmpty();
     }
 
-    // ─── hasText with aliases ────────────────────────────────────────────────
-
-    @Test
-    void hasText_findsDocumentBySenderAliasLastName() {
-        aliasRepository.save(PersonNameAlias.builder()
-                .person(sender).lastName("von Mueller").type(PersonNameAliasType.BIRTH).sortOrder(0).build());
-
-        List<Document> result = documentRepository.findAll(Specification.where(hasText("von Mueller")));
-
-        assertThat(result).isNotEmpty();
-        assertThat(result).extracting(Document::getTitle).contains("Alter Brief");
-    }
-
-    @Test
-    void hasText_findsDocumentByReceiverAliasLastName() {
-        aliasRepository.save(PersonNameAlias.builder()
-                .person(receiver).lastName("de Gruyter").type(PersonNameAliasType.BIRTH).sortOrder(0).build());
-
-        List<Document> result = documentRepository.findAll(Specification.where(hasText("de Gruyter")));
-
-        assertThat(result).isNotEmpty();
-    }
 }

frontend/src/routes/DocumentList.svelte

@@ -2,13 +2,16 @@
 import { goto } from '$app/navigation';
 import { m } from '$lib/paraglide/messages.js';
 import { formatDate } from '$lib/utils/date';
+import { groupDocuments } from '$lib/utils/groupDocuments';
+import GroupDivider from '$lib/components/GroupDivider.svelte';
 
 let {
 	documents,
 	canWrite,
 	error,
 	total = 0,
-	q = ''
+	q = '',
+	sort
 }: {
 	documents: {
 		id: string;
@@ -24,7 +27,14 @@ let {
 	error?: string | null;
 	total?: number;
 	q?: string;
+	sort?: string;
 } = $props();
+
+const fallbackLabel = $derived(sort === 'DATE' ? m.docs_group_undated() : m.docs_group_unknown());
+const groupedDocuments = $derived.by(() =>
+	groupDocuments(documents, sort ?? 'DATE', fallbackLabel)
+);
+const showDividers = $derived(groupedDocuments.length >= 2);
 </script>
 
 <!-- DOCUMENT LIST HEADER -->
@@ -57,107 +67,112 @@ let {
 			{error}
 		</div>
 	{:else if documents.length > 0}
-		<ul class="divide-y divide-line-2">
-			{#each documents as doc (doc.id)}
-				<li class="group transition-colors duration-200 hover:bg-muted/50">
-					<a href="/documents/{doc.id}" class="block p-6">
-						<div class="flex flex-col gap-6 sm:flex-row">
-							<!-- Main Info -->
-							<div class="flex-1">
-								<div class="mb-2 flex items-baseline justify-between">
-									<h3 class="font-serif text-xl font-medium text-ink group-hover:underline">
-										{doc.title || doc.originalFilename}
-									</h3>
-								</div>
-
-								<!-- Metadata Row -->
-								<div class="mb-4 flex flex-wrap gap-6 font-sans text-sm text-ink-2">
-									<div class="flex items-center">
-										<img
-											src="/degruyter-icons/Simple/Medium-24px/SVG/Action/Calendar/Calendar-Add-MD.svg"
-											alt=""
-											aria-hidden="true"
-											class="mr-1.5 h-4 w-4"
-										/>
-										{doc.documentDate ? formatDate(doc.documentDate) : '—'}
+		{#each groupedDocuments as group (group.label)}
+			{#if showDividers}
+				<GroupDivider label={group.label} />
+			{/if}
+			<ul class="divide-y divide-line-2">
+				{#each group.documents as doc (doc.id)}
+					<li class="group transition-colors duration-200 hover:bg-muted/50">
+						<a href="/documents/{doc.id}" class="block p-6">
+							<div class="flex flex-col gap-6 sm:flex-row">
+								<!-- Main Info -->
+								<div class="flex-1">
+									<div class="mb-2 flex items-baseline justify-between">
+										<h3 class="font-serif text-xl font-medium text-ink group-hover:underline">
+											{doc.title || doc.originalFilename}
+										</h3>
 									</div>
-									{#if doc.location}
+
+									<!-- Metadata Row -->
+									<div class="mb-4 flex flex-wrap gap-6 font-sans text-sm text-ink-2">
 										<div class="flex items-center">
 											<img
-												src="/degruyter-icons/Simple/Medium-24px/SVG/Action/Location-MD.svg"
+												src="/degruyter-icons/Simple/Medium-24px/SVG/Action/Calendar/Calendar-Add-MD.svg"
 												alt=""
 												aria-hidden="true"
 												class="mr-1.5 h-4 w-4"
 											/>
-											{doc.location}
+											{doc.documentDate ? formatDate(doc.documentDate) : '—'}
+										</div>
+										{#if doc.location}
+											<div class="flex items-center">
+												<img
+													src="/degruyter-icons/Simple/Medium-24px/SVG/Action/Location-MD.svg"
+													alt=""
+													aria-hidden="true"
+													class="mr-1.5 h-4 w-4"
+												/>
+												{doc.location}
+											</div>
+										{/if}
+									</div>
+
+									<!-- Sender/Receiver Info -->
+									<div class="grid grid-cols-1 gap-4 font-serif text-sm sm:grid-cols-2">
+										<div class="flex items-baseline">
+											<span
+												class="w-10 font-sans text-xs font-bold tracking-wide text-ink-3 uppercase"
+												>{m.docs_list_from()}</span
+											>
+											{#if doc.sender}
+												<span class="text-ink">{doc.sender.displayName}</span>
+											{:else}
+												<span class="text-ink-3 italic">{m.docs_list_unknown()}</span>
+											{/if}
+										</div>
+										<div class="flex items-baseline">
+											<span
+												class="w-10 font-sans text-xs font-bold tracking-wide text-ink-3 uppercase"
+												>{m.docs_list_to()}</span
+											>
+											{#if doc.receivers && doc.receivers.length > 0}
+												<span class="text-ink">
+													{doc.receivers.map((p) => p.displayName).join(', ')}
+												</span>
+											{:else}
+												<span class="text-ink-3 italic">{m.docs_list_unknown()}</span>
+											{/if}
+										</div>
+									</div>
+
+									<!-- Tags Display -->
+									{#if doc.tags && doc.tags.length > 0}
+										<div class="mt-4 flex flex-wrap gap-2 pt-3">
+											{#each doc.tags as tag (tag.id)}
+												<button
+													type="button"
+													class="relative z-10 inline-flex cursor-pointer items-center rounded bg-muted px-2 py-1 text-[10px] font-bold tracking-widest text-ink uppercase transition-colors hover:bg-primary hover:text-primary-fg"
+													onclick={(e) => {
+														e.preventDefault();
+														e.stopPropagation();
+														goto(`/?tag=${encodeURIComponent(tag.name)}`);
+													}}
+												>
+													{tag.name}
+												</button>
+											{/each}
 										</div>
 									{/if}
 								</div>
 
-								<!-- Sender/Receiver Info -->
-								<div class="grid grid-cols-1 gap-4 font-serif text-sm sm:grid-cols-2">
-									<div class="flex items-baseline">
-										<span
-											class="w-10 font-sans text-xs font-bold tracking-wide text-ink-3 uppercase"
-											>{m.docs_list_from()}</span
-										>
-										{#if doc.sender}
-											<span class="text-ink">{doc.sender.displayName}</span>
-										{:else}
-											<span class="text-ink-3 italic">{m.docs_list_unknown()}</span>
-										{/if}
-									</div>
-									<div class="flex items-baseline">
-										<span
-											class="w-10 font-sans text-xs font-bold tracking-wide text-ink-3 uppercase"
-											>{m.docs_list_to()}</span
-										>
-										{#if doc.receivers && doc.receivers.length > 0}
-											<span class="text-ink">
-												{doc.receivers.map((p) => p.displayName).join(', ')}
-											</span>
-										{:else}
-											<span class="text-ink-3 italic">{m.docs_list_unknown()}</span>
-										{/if}
-									</div>
+								<!-- Arrow Icon -->
+								<div
+									class="hidden items-center text-ink-3 transition-colors group-hover:text-accent sm:flex"
+								>
+									<img
+										src="/degruyter-icons/Simple/Medium-24px/SVG/Action/Arrow/Arrow-Right-MD.svg"
+										alt=""
+										aria-hidden="true"
+										class="h-6 w-6"
+									/>
 								</div>
-
-								<!-- Tags Display -->
-								{#if doc.tags && doc.tags.length > 0}
-									<div class="mt-4 flex flex-wrap gap-2 pt-3">
-										{#each doc.tags as tag (tag.id)}
-											<button
-												type="button"
-												class="relative z-10 inline-flex cursor-pointer items-center rounded bg-muted px-2 py-1 text-[10px] font-bold tracking-widest text-ink uppercase transition-colors hover:bg-primary hover:text-primary-fg"
-												onclick={(e) => {
-													e.preventDefault();
-													e.stopPropagation();
-													goto(`/?tag=${encodeURIComponent(tag.name)}`);
-												}}
-											>
-												{tag.name}
-											</button>
-										{/each}
-									</div>
-								{/if}
 							</div>
-
-							<!-- Arrow Icon -->
-							<div
-								class="hidden items-center text-ink-3 transition-colors group-hover:text-accent sm:flex"
-							>
-								<img
-									src="/degruyter-icons/Simple/Medium-24px/SVG/Action/Arrow/Arrow-Right-MD.svg"
-									alt=""
-									aria-hidden="true"
-									class="h-6 w-6"
-								/>
-							</div>
-						</div>
-					</a>
-				</li>
-			{/each}
-		</ul>
+						</a>
+					</li>
+				{/each}
+			</ul>
+		{/each}
 	{:else}
 		<!-- Empty State -->
 		<div class="p-16 text-center">