package dev.lions.unionflow.server.service.pep;

import java.time.LocalDate;
import java.util.List;

/**
 * Interface des fournisseurs de PEP (Personnes Exposées Politiquement) screening.
 *
 * <p>Aucune liste PEP publique officielle UEMOA/CI au 2026-04-25 → recommandation : intégrer un
 * fournisseur SaaS commercial (Youverify, ComplyAdvantage, Refinitiv, Dow Jones, LexisNexis).
 *
 * <p>Plusieurs implémentations sont prévues :
 *
 * <ul>
 *   <li>{@link InMemoryPepScreeningProvider} — liste statique maintenue en interne (mode
 *       fallback / dev / petite organisation)
 *   <li>{@code YouverifyPepScreeningProvider} (à créer post-contractualisation Youverify)
 *   <li>{@code ComplyAdvantagePepScreeningProvider} (alternatif)
 * </ul>
 *
 * <p>Référence : Instruction BCEAO 003-03-2025 du 18 mars 2025 — vérification systématique des
 * PEP requise dans le KYC.
 *
 * @since 2026-04-25 (P1-NEW-11)
 */
public interface PepScreeningProvider {

  /**
   * Vérifie si une personne figure parmi les PEP référencés.
   *
   * @param nom nom de famille
   * @param prenoms prénoms
   * @param dateNaissance date de naissance (peut être null pour recherche partielle)
   * @param nationalite code ISO 3166-1 alpha-3
   * @return résultat du screening (jamais null)
   */
  PepScreeningResult screen(String nom, String prenoms, LocalDate dateNaissance, String nationalite);

  /** Identifiant du fournisseur (pour logs / audit). */
  String providerName();

  /** True si le provider est disponible (configuré, accessible réseau). */
  boolean isAvailable();

  /** Résultat du screening PEP. */
  record PepScreeningResult(
      boolean estPep,
      List<PepMatch> matches,
      String providerUtilise,
      String warningMessage
  ) {
    public static PepScreeningResult notFound(String provider) {
      return new PepScreeningResult(false, List.of(), provider, null);
    }
  }

  /** Détail d'un match PEP. */
  record PepMatch(
      String nomComplet,
      String fonction,
      String pays,
      LocalDate dateDebutFonction,
      LocalDate dateFinFonction,
      String categorie,         // ex: HEAD_OF_STATE, MINISTER, MP, JUDICIARY, MILITARY, etc.
      String source,
      double scoreSimilarite    // 0.0 à 1.0
  ) {}
}
