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

/**
 * Outbound port for loading external prompt templates.
 * <p>
 * This interface abstracts the loading of prompt content from external sources
 * (files, resources, databases, etc.), allowing the Application layer to remain
 * independent of how or where prompts are stored.
 * <p>
 * <strong>Design principles:</strong>
 * <ul>
 *   <li>Prompt is not embedded in code; it is loaded from an external source</li>
 *   <li>Each prompt receives a stable identifier for traceability across batch runs</li>
 *   <li>Results are returned as structured types ({@link PromptLoadingResult}),
 *       never as exceptions</li>
 * </ul>
 * <p>
 * <strong>Adapter responsibilities:</strong>
 * <ul>
 *   <li>Locate and read the prompt file/resource from the configured source</li>
 *   <li>Derive a stable prompt identifier (e.g., filename, semantic version, content hash)</li>
 *   <li>Validate that the loaded content is not empty or otherwise invalid</li>
 *   <li>Return either success or a classified failure</li>
 *   <li>Encapsulate all file I/O, resource loading, and configuration details</li>
 * </ul>
 * <p>
 * <strong>Non-goals of this port:</strong>
 * <ul>
 *   <li>Prompt parsing or templating logic</li>
 *   <li>Combining prompt with document text (Application layer handles this)</li>
 *   <li>Template variable substitution</li>
 *   <li>Validation of prompt content against domain rules</li>
 * </ul>
 */
public interface PromptPort {

    /**
     * Loads the configured external prompt template.
     * <p>
     * This method is called once per batch run to obtain the current prompt.
     * The prompt content and its stable identifier are returned together.
     * <p>
     * If loading fails for any reason (file not found, I/O error, content validation),
     * a {@link PromptLoadingFailure} is returned rather than throwing an exception.
     *
     * @return a {@link PromptLoadingResult} encoding either:
     *         <ul>
     *           <li>Success: prompt content and identifier loaded successfully</li>
     *           <li>Failure: prompt could not be loaded or is invalid</li>
     *         </ul>
     *
     * @see PromptLoadingSuccess
     * @see PromptLoadingFailure
     */
    PromptLoadingResult loadPrompt();
}
