package org.raddatz.familienarchiv.document;

import io.swagger.v3.oas.annotations.media.Schema;

import java.util.List;
import java.util.UUID;

/**
 * Match signals for a single document in a full-text search result.
 * All fields are non-null except {@code transcriptionSnippet} and {@code summarySnippet},
 * which are null when the respective field did not match the query.
 */
public record SearchMatchData(
        /**
         * Best-ranked matching transcription line, or null if no block matched.
         */
        String transcriptionSnippet,

        /**
         * Character offsets of highlighted terms within the document title.
         * Empty when the title did not contribute to the match.
         */
        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
        List<MatchOffset> titleOffsets,

        /**
         * True when the sender's name matched the query.
         */
        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
        boolean senderMatched,

        /**
         * IDs of receiver persons whose names matched the query.
         */
        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
        List<UUID> matchedReceiverIds,

        /**
         * IDs of tags whose names matched the query.
         */
        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
        List<UUID> matchedTagIds,

        /**
         * Character offsets of highlighted terms within the transcription snippet.
         * Empty when no transcription block matched or the snippet has no highlights.
         */
        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
        List<MatchOffset> snippetOffsets,

        /**
         * Highlighted summary excerpt, or null if the summary did not match the query.
         */
        String summarySnippet,

        /**
         * Character offsets of highlighted terms within the summary snippet.
         * Empty when the summary did not match or has no highlights.
         */
        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
        List<MatchOffset> summaryOffsets
) {
    /** Canonical "no match data" value for a single document. */
    public static SearchMatchData empty() {
        return new SearchMatchData(null, List.of(), false, List.of(), List.of(), List.of(), null, List.of());
    }
}
