mon-entreprise/publicodes/docs/mecanisms.yaml

une de ces conditions:
  description: >-
    C'est un `ou` logique.
    Contient une liste de conditions.
    Renvoie `oui` si l'une des conditions est applicable.
  retourne: Booléen
  exemples:
    base: >-
      âge:
        formule: 17 ans

      mineur émancipé:
        formule: oui

      peut voter:
        formule:
          une de ces conditions:
            - âge >= 18 ans
            - mineur émancipé

toutes ces conditions:
  description: >-
    C'est un `et` logique.
    Contient une liste de conditions.
    Renvoie `oui` si toutes les conditions sont applicables.
  argument:
    - '*'
    - ...
  exemples:
    base: >-
      âge:
        formule: 17 ans

      citoyenneté française:
        formule: oui

      peut voter:
        formule:
          toutes ces conditions:
            - citoyenneté française
            - âge >= 18 ans

produit:
  description: >-
    C'est une multiplication un peu améliorée, très utile pour exprimer les
    cotisations.

    Sa propriété `assiette` est multipliée par un pourcentage, `taux`, ou par un
    `facteur` quand ce nom est plus approprié.

    La multiplication peut être plafonnée : ce plafond sépare l'assiette en
    deux, et la partie au-dessus du plafond est tout simplement ignorée. Dans ce
    cas, elle se comporte comme une barème en taux marginaux à deux tranches, la
    deuxième au taux nul et allant de `plafond` à l'infini.
  argument:
    assiette: Valeur à multiplier
    taux: Taux à appliquer
    facteur: Facteur multiplicatif
    plafond: Plafond au dessus duquel le taux appliqué est nul

  exemples:
    base: >-
      cotisation:
        formule:
          produit:
            assiette: 2000 €/mois
            taux: 5%

    assiette plafonnée: >-
      plafond sécurité sociale:
        formule: 3000 €/mois

      assiette cotisation:
        formule: 15000 €/mois

      chômage:
        formule:
          produit:
            assiette: assiette cotisation
            plafond: 400% * plafond sécurité sociale
            taux: 4%

variations:
  description: >-
    Contient une liste de conditions (`si`) et leurs conséquences associées
    (`alors`).

    Pour la première condition vraie dans la liste, on retient la valeur qui lui
    est associée.

    Si aucune condition n'est vraie, alors ce mécanisme renvoie implicitement
    `non applicable`

    Ce mécanisme peut aussi être utilisé au sein d'un mécanisme compatible, tel qu'un produit ou un barème.
  arguments:
    - si: condition à vérifier
      alors: consequence évaluée si la condition est vrai
    - ...
    - sinon: consequence évaluée si aucune des conditions précédente n'était applicable
  exemples:
    base: >-
      taux réduit:
        formule: oui

      taux allocation familiales:
        formule:
          variations:
            - si: taux réduit
              alors: 3.45%
            - sinon: 5.25%

    dans un produit: >-
      assiette cotisation:
        formule: 2300 €/mois

      taux réduit:
        formule: oui

      allocation familiales:
        formule:
          produit:
            assiette: assiette cotisation
            variations:
              - si: taux réduit
                alors:
                  taux: 3.45%
              - sinon:
                  taux: 5.25%

somme:
  description: >-
    C'est tout simplement la somme de chaque terme de la liste. Si un des terme
    n'est pas applicable, il vaut zéro.

    On peut aussi retrancher des valeurs avec l'opérateur unaire `-`
  arguments:
    - '*'
    - ...

  exemples:
    base: >-
      exemple:
        formule:
          somme:
            - 15.89 €
            - 12% * 14 €
            - (-20 €)
    terme non applicable: >-
      a:
        formule: 50 €

      b:
        applicable si: non
        formule: 20 €

      somme:
        formule:
          somme:
            - a
            - b
            - 40 €

le maximum de:
  description: >-
    Renvoie la valeur numérique de la liste de propositions fournie qui est la
    plus grande.

    Pour ajouter un plancher à une valeur, préférer l'utilisation du
    mécanisme `encadrement`.
  exemples:
    base: >-
      max: 
        formule:
          le maximum de:
            - 50
            - 100

le minimum de:
  description: >-
    Renvoie la valeur numérique de la liste de propositions fournie qui est la
    plus petite.

    Pour plafonner une valeur, préférer l'utilisation du mécanisme `encadrement`.
  exemples:
    base: >-
      min: 
        formule:
          le minimum de:
            - 50
            - 100

arrondi:
  description: >-
    Arrondi à l'entier le plus proche, ou à une précision donnée.
  exemples:
    base: >-
      arrondi:
        formule:
          arrondi:
            valeur: 12.45
            décimales: 1

régularisation:
  description: |
    Permet de régulariser progressivement un calcul de cotisation en fonction du
    cumul de variables numériques mensuelles.

    Ce mécanisme spécifique est utilisé pour le calcul des cotisations
    mensuelles, afin de "lisser" un plafond ou un calcul sur plusieurs mois.

    La régularisation progressive s'opère le long d'une année civile complète.

    ## Explication du calcul

    Pour chaque mois, on évalue la valeur à régulariser en faisant le cumul des
    éléments nécessaires au calcul sur la période écoulée depuis le premier
    jour de l’année.

    Par exemple, pour la cotisation suivante : 

    ```yaml
      cotisation: 
        formule: 
          produit:
            assiette: brut
            plafond: 2000 €/mois
            taux: 10%
    ```

    Avec un brut de 1000 € en janvier et 3500 € en février et 1000€ en mars, le cumul sera le
    suivant :

    |     | brut   | plafond | cotisation         |
    | --- | ------ | ------- |------------------- |
    | JAN | 1000 € | 2000 €  | 1000 × 10% = 100 € |
    | FEV | 4500 € | 4000 €  | 4000 × 10% = 400 € |
    | MAR | 5500 € | 6000 €  | 5500 × 10% = 550 € |

      
    On regarde ensuite le cumul des valeurs déjà versées les mois précédents, pour
    ne garder que la différence entre les deux montants. Dans notre exemple, on
    aboutit aux valeurs suivantes :

    |     | cotisation cumul | cotisation régularisée |
    | --- | ---------------- | ---------------------- |
    | JAN |  100 €           |  100 €                 |
    | FEV |  400 €           |  400 € - 100 € = 300 € |
    | MAR |  550 €           |  550 € - 300 € = 150 € |

  arguments:
    règle: règle à régulariser
    valeurs cumulées:
      - liste de variables cumulée mensuellement pour calculer la régularisation. Doivent être
        numérique, et avoir une unité `/mois`

  exemples:
    base: >-
      brut:
        formule:
          somme:
            - 1000 €/mois | du 01/01/2020 | au 31/01/2020
            - 3500 €/mois | du 01/02/2020 | au 29/02/2020
            - 1000 €/mois | du 01/03/2020 | au 31/03/2020

      cotisation:
        formule:
          régularisation:
            règle:
              produit:
                assiette: brut
                plafond [ref]: 2000 €/mois
                taux: 10%
            valeurs cumulées:
              - brut
              - plafond

    valeur cumulée à partir d'une date: >-
      SMIC: 1521.22 €/mois

      primes:
        formule:
          somme:
            - 2470 €/mois | du 01/01/2019 | au 31/01/2019
            - 1470 €/mois | du 01/05/2019 | au 31/05/2019

      rémunération:
        formule:
          somme:
            - 1530 €/mois | du 01/01/2019 | au 31/12/2019
            - primes

      réduction sur AC au 1er janvier:
        formule: non

      réduction générale chômage . coefficient:
        formule:
          arrondi:
            valeur: (0.0405 / 0.60 ) * (1.60 * SMIC / rémunération - 1)
            décimales: 4

      réduction générale chômage . réduction sans régularisation:
        formule:
          encadrement:
            plancher: 0
            valeur:
              arrondi:
                valeur:
                  multiplication:
                    assiette: rémunération
                    taux: coefficient
                décimales: 2

      réduction générale chômage:
        formule:
          régularisation:
            règle: réduction sans régularisation
            valeurs cumulées:
              - 'SMIC | à partir du 01/10/2019'
              - 'rémunération | à partir du 01/10/2019'

recalcul:
  description: >-
    Relance le calcul d'une règle dans une situation différente de la situation
    courante. Permet par exemple de calculer le montant des cotisations au niveau du
    SMIC, même si le salaire est plus élevé dans la situation actuelle.

  exemples:
    base: >-
      brut: 
        formule: 2000€

      cotisations: 
        formule:
          produit:
            assiette: brut
            taux: 20%

      cotisations pour un SMIC:
        formule:
          recalcul:
            règle: cotisations
            avec:
              brut: 1500 €

barème:
  description: C'est un barème en taux marginaux, mécanisme de calcul connu son utilisation
    dans le calcul de l'impôt sur le revenu.

    L'assiette est décomposée en plusieurs tranches, qui sont multipliées par un
    taux spécifique.

    Les tranches sont souvent exprimées sous forme de facteurs d'une variable
    que l'on appelle `multiplicateur`, par exemple `1 x le plafond de la
    sécurité sociale`.
  exemples:
    base: >-
      revenu imposable:
        formule: 54126 €

      impôt sur le revenu:
        formule:
          barème:
            assiette: revenu imposable
            tranches:
              - taux: 0%
                plafond: 9807 €
              - taux: 14%
                plafond: 27086 €
              - taux: 30%
                plafond: 72617 €
              - taux: 41%
                plafond: 153783 €
              - taux: 45%

grille:
  description: >-
    C'est un barème sous la forme d'une grille de correspondance. C'est le
    mécanisme de calcul de l'impôt neutre, aussi appelé impôt non personnalisé.

    Il est composé de tranches qui se suivent. Il suffit de trouver l'assiette
    qui correspond à la tranche, et de selectionner le montant associé à
    l'assiette.
  exemples:
    grille avec multiplicateur et unité: >-
      SMIC horaire: 
        formule: 10 €/heure

      revenu moyen: 
        formule:
          250 €/mois

      trimestres validés:
        formule:
          grille:
            unité: trimestres validés/an
            assiette: revenu moyen
            multiplicateur: SMIC horaire
            tranches:
              - montant: 0
                plafond: 150 heures/an
              - montant: 1
                plafond: 300 heures/an
              - montant: 2
                plafond: 450 heures/an
              - montant: 3
                plafond: 600 heures/an
              - montant: 4

taux progressif:
  description: >-
    Ce mécanisme permet de calculer un taux progressif. On spécifie pour chaque
    tranche le plafond et le taux associé. Le taux effectif renvoyé est calculé
    en lissant la différence de taux entre la borne inférieure et supérieure de
    l'assiette

    > Par exemple, si nous nous avons les tranches suivantes :

    - taux: 50% / plafond: 0
    - taux: 100% / plafond: 1000

    > Pour une assiette de 500, le taux retourné sera 75%, car il correspond au
    > taux situé à la moitié de la tranche correspondante.
  exemples:
    base: >-
      chiffre d'affaires: 
        formule: 30000 €/an

      plafond: 
        formule: 3000 €/mois

      taux réduction de cotisation:
        formule:
          taux progressif:
            assiette: chiffre d'affaires
            multiplicateur: plafond
            tranches:
              - taux: 100%
                plafond: 75%
              - taux: 0%
                plafond: 100%
composantes:
  description: >-
    Beaucoup de cotisations sont composées de deux parties qui partagent la
    méthode de calcul mais diffèrent par des paramètres différents.

    Pour ne pas définir deux variables presque redondantes, on utilise le
    mécanisme de composante. Il se comportera comme une somme dans les calculs,
    mais son affichage sur les pages /règle sera adapté.

    Il est même possible, pour les mécanismes `barème` et `produit` de garder en
    commun un paramètre comme l'assiette, puis de déclarer des composantes pour
    le taux.

    > L'exemple le plus courant de composantes, c'est la distinction part
    employeur, part salarié (ex. retraite AGIRC).

allègement:
  description: >-
    Permet de réduire le montant d'une variable.
    Très utilisé dans le contexte des impôts.

encadrement:
  description: Permet d'ajouter un plafond et/ou un plancher à une valeur.
  exemples:
    base: >-
      assiette plafonnée:
        formule:
          encadrement:
            plancher: 0 €
            valeur: 2000 €
            plafond: 1500 €

durée:
  description: Permet d'obtenir le nombre de jours entre deux dates
  exemples:
    base: >-
      date d'embauche: 
        formule: 14/04/2008

      ancienneté en fin d'année:
        unité: an
        formule:
          durée:
            depuis: date d'embauche
            jusqu'à: 31/12/2020

synchronisation:
  description: Pour éviter trop de saisies à l'utilisateur, certaines informations sont
    récupérées à partir de ce que l'on appelle des API. Ce sont des services
    auxquels ont fait appel pour obtenir des informations sur un sujet précis.
    Par exemple, l'État français fournit gratuitement l'API géo, qui permet à
    partir du nom d'une ville, d'obtenir son code postal, son département, la
    population etc.

    Ce mécanismes `synchronisation` permet de faire le lien entre les règles de
    notre système et les réponses de ces API.

inversion numérique:
  description: >-
    La formule de calcul de cette variable n'est pas connue, souvent elle n'a
    même pas de sens. Mais le mécanisme `inversion` indique qu'elle peut être
    _estimée_ à partir de l'un des _objectifs_ listés sous l'attribut `avec`. Il
    faut alors renseigner une valeur cible pour cet objectif.

    Voilà comment ça marche : on va donner à la variable une valeur au hasard,
    calculer _l'objectif_, puis grâce à des calculs savants améliorer notre
    choix jusqu'à ce que l'écart entre le calcul et la valeur cible devienne
    satisfaisant.

    Concrètement, si l'on demande au moteur (même indirectement) la valeur d'une
    variable qui a pour formule une inversion, il va vérifier qu'une des
    possibilités d'inversion a bien une valeur calculée ou saisie, et procéder à
    l'inversion décrite plus haut à partir de celle-ci. Sinon, ces possibilités
    d'inversions seront listées comme manquantes.