package dev.lions.unionflow.server.security;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Annotation déclarative pour le contrôle d'accès par module métier.
 *
 * <p>Placée sur un endpoint JAX-RS, elle vérifie que l'organisation active
 * du contexte de la requête a bien le module requis activé.
 *
 * <p>Le module est déterminé par le type d'organisation (Option C) et non
 * par le plan tarifaire.
 *
 * <p>Exemple d'utilisation :
 * <pre>{@code
 *   @GET
 *   @Path("/cycles")
 *   @RequiresModule("TONTINE")
 *   @RolesAllowed({"ADMIN", "TONTINE_MANAGER"})
 *   public Response getCycles() { ... }
 * }</pre>
 */
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface RequiresModule {

    /**
     * Nom du module requis (ex: "TONTINE", "CREDIT", "EPARGNE", "AGRICULTURE").
     * Doit correspondre à l'une des valeurs de {@link dev.lions.unionflow.server.service.OrganisationModuleService#MODULES_COMMUNS}
     * ou des modules métier définis par type d'organisation.
     */
    String value();

    /**
     * Message d'erreur personnalisé affiché si le module n'est pas actif.
     * Par défaut, un message générique est généré.
     */
    String message() default "";
}
