package de.gecheckt.pdf.umbenenner.application.port.out;

/**
 * Outbound port for processing-related logging operations.
 * <p>
 * The application delegates all logging to this port to remain decoupled from
 * specific logging frameworks. Concrete implementations are provided by adapters.
 * <p>
 * <h2>Sensitive AI content logging</h2>
 * <p>
 * The {@link #debugSensitiveAiContent(String, Object[])} method allows logging
 * of sensitive AI-generated content (complete raw response, complete reasoning)
 * subject to the {@link AiContentSensitivity} setting:
 * <ul>
 *   <li>When {@link AiContentSensitivity#PROTECT_SENSITIVE_CONTENT} is active (default),
 *       this method logs nothing.</li>
 *   <li>When {@link AiContentSensitivity#LOG_SENSITIVE_CONTENT} is explicitly enabled,
 *       this method logs the content to DEBUG level.</li>
 * </ul>
 * <p>
 * The complete sensitive content is always persisted in SQLite for traceability,
 * regardless of this logging setting. The logging decision controls only whether
 * the content also appears in log files.
 */
public interface ProcessingLogger {

    /**
     * Logs an information-level message.
     *
     * @param message the message template (may contain {} placeholders)
     * @param args    optional message arguments for placeholder substitution
     */
    void info(String message, Object... args);

    /**
     * Logs a debug-level message.
     *
     * @param message the message template (may contain {} placeholders)
     * @param args    optional message arguments for placeholder substitution
     */
    void debug(String message, Object... args);

    /**
     * Logs a debug-level message containing sensitive AI-generated content,
     * subject to the configured {@link AiContentSensitivity}.
     * <p>
     * This method is called with message and arguments containing sensitive AI content
     * (e.g., complete raw response, complete reasoning). The implementation must:
     * <ul>
     *   <li>Check the current {@link AiContentSensitivity} setting.</li>
     *   <li>If set to {@link AiContentSensitivity#PROTECT_SENSITIVE_CONTENT} (default),
     *       emit nothing to log.</li>
     *   <li>If set to {@link AiContentSensitivity#LOG_SENSITIVE_CONTENT}, log the
     *       message and arguments at DEBUG level normally.</li>
     * </ul>
     * <p>
     * This is the only method where sensitive AI content may be logged based on
     * configuration. Other logging methods ({@link #info}, {@link #debug}, etc.)
     * must never log sensitive content.
     *
     * @param message the message template (may contain {} placeholders)
     * @param args    optional message arguments that may include sensitive AI content
     */
    void debugSensitiveAiContent(String message, Object... args);

    /**
     * Logs a warning-level message.
     *
     * @param message the message template (may contain {} placeholders)
     * @param args    optional message arguments for placeholder substitution
     */
    void warn(String message, Object... args);

    /**
     * Logs an error-level message with optional arguments and exception.
     * <p>
     * If the last argument is a Throwable, it is treated as the exception to log.
     * Otherwise, all arguments are treated as message parameters.
     *
     * @param message the message template (may contain {} placeholders)
     * @param args    optional message arguments and/or exception
     */
    void error(String message, Object... args);

}
