Hooks et personnalisations avancées

Dokos et son framework sous-jacent (Frappe) offrent un système puissant de hooks pour personnaliser le comportement des applications sans modifier le code source principal. Les hooks permettent d'étendre ou de modifier des fonctionnalités existantes de manière propre et maintenable.

1. Qu'est-ce qu'un hook ?

Un hook est un point d'ancrage dans le code qui permet d'exécuter une fonction personnalisée à un moment précis du cycle de vie d'une application ou d'une transaction. Les hooks sont définis dans le fichier hooks.py de votre application.

2. Types de hooks courants

2.1. Hooks de validation

Permettent de valider des données avant qu'elles ne soient sauvegardées.

Exemple :

validate = ["mon_app.hooks.validate_client"]

2.2. Hooks de calcul

Permettent de personnaliser des calculs, comme les taxes ou les totaux.

Exemple :

# Déjà documenté dans la section taxes
erpnext_taxable_base_resolvers = {"Sur MRP": "mon_app.taxes.calcul_sur_mrp"}

2.3. Hooks d'événements

Permettent de déclencher des actions après un événement spécifique (création, mise à jour, suppression).

Exemple :

after_insert = ["mon_app.hooks.envoyer_email_confirmation"]

3. Hook taxable-base resolver pour les taxes

Ce hook permet de personnaliser la base taxable pour des types de taxes spécifiques, comme les taxes sur le prix public conseillé (MRP) ou d'autres règles locales.

3.1. Définition du hook

Ajoutez le hook dans le fichier hooks.py de votre application :

erpnext_taxable_base_resolvers = {
    "Sur MRP": "mon_app.taxes.calcul_sur_mrp",
    "Taxe Brésilienne": "mon_app.taxes.calcul_taxes_bresil"
}

3.2. Implémentation de la fonction

Créez une fonction Python qui calcule la base taxable :

# mon_app/taxes.py
def calcul_sur_mrp(calc, item, tax):
    """
    Calcule la base taxable basée sur le prix public conseillé (MRP).
    
    Args:
        calc: Objet de calcul des taxes.
        item: Ligne d'article dans la transaction.
        tax: Ligne de taxe dans le modèle de taxe.
    
    Returns:
        float: Base taxable calculée.
    """
    return item.price_list_rate * item.qty

3.3. Mise en miroir côté client

Pour que le calcul soit également effectué côté client (par exemple, dans les formulaires de vente), définissez une fonction JavaScript équivalente :

// Dans un fichier JavaScript personnalisé
erpnext.taxable_base_resolvers["Sur MRP"] = (calc, item) => {
    return item.price_list_rate * item.qty;
};

3.4. Exemple complet : Taxe sur le MRP en Inde

Scénario :

• Article : Vendu à 1000 €, MRP de 1200 €.
• Taxe : 10 % incluse dans le prix (soit 120 €).
• Résultat : Base taxable = 1200 €, montant net = 880 €.

Configuration :

1. Créez un modèle de taxe de vente avec une ligne de taxe de type Sur MRP.
2. Appliquez ce modèle à une facture de vente.
3. Le calcul sera automatiquement effectué en utilisant le hook.

      
flowchart TD
    A[Transaction de vente] --> B[Sélection du modèle de taxe]
    B --> C[Détection du type de charge personnalisé]
    C --> D[Appel du hook taxable-base resolver]
    D --> E[Calcul de la base taxable sur MRP]
    E --> F[Application de la taxe]

    

4. Bonnes pratiques

• Nommez clairement vos hooks : Utilisez des noms explicites pour les types de charge (ex: "Sur MRP", "Taxe Brésilienne").
• Documentez vos fonctions : Ajoutez des docstrings pour expliquer le rôle de chaque fonction.
• Testez vos hooks : Créez des tests unitaires pour valider le comportement de vos calculs personnalisés.
• Synchronisez Python et JavaScript : Assurez-vous que les calculs côté serveur et côté client sont cohérents.

::: warning Les hooks personnalisés doivent être utilisés avec précaution pour éviter des comportements inattendus dans les transactions financières. Testez toujours vos modifications dans un environnement de développement avant de les déployer en production. :::