Rapprochement bancaire — Types de pièces extensibles

Principe

Le dialogue « Créer une pièce » de l'outil de rapprochement bancaire propose deux types natifs : Saisie de paiement et Écriture au journal. Il lit ses types dans un registre JavaScript : erpnext.accounts.bank_reconciliation.voucher_types. Une application peut y inscrire ses propres types de pièces, avec leurs champs de dialogue, leurs conditions d'affichage et leur logique de création côté serveur.

Enregistrer un type de pièce

Inscrivez votre type dans le registre avant le chargement du bundle de l'outil de rapprochement (typiquement via un hook boot ou un script global de votre application) :

frappe.provide("erpnext.accounts.bank_reconciliation.voucher_types");

erpnext.accounts.bank_reconciliation.voucher_types["Loan Repayment"] = {
  is_applicable: (bank_transaction) => bank_transaction.deposit > 0,
  get_fields: (dialog_manager) => [
    // champs de dialogue affichés pour ce type
  ],
  create: (dialog_manager, values, allow_edit) =>
    frappe.xcall("lending.api.create_loan_repayment", { ... }),
};

Contrat de chaque entrée

Une entrée du registre peut définir trois fonctions :

• get_fields(dialog_manager) — renvoie un tableau de champs de dialogue supplémentaires affichés sous le sélecteur « Type de document ». Utilisez dialog_manager pour accéder au contexte (compte bancaire, transaction sélectionnée) si nécessaire.
• is_applicable(bank_transaction) — renvoie true/false pour masquer ou afficher ce type selon la transaction. Par exemple, ne proposer « Remboursement de prêt » que pour les dépôts (bank_transaction.deposit > 0).
• create(dialog_manager, values, allow_edit) — effectue l'appel serveur et renvoie la transaction bancaire réconciliée. Si allow_edit est vrai (chemin « Éditer en pleine page »), renvoyez le brouillon pour que l'utilisateur puisse le compléter avant soumission ; la réconciliation est alors déclenchée automatiquement après soumission.

Comportement de l'interface

• Le menu déroulant Type de document est rafraîchi pour chaque transaction : les types non applicables via is_applicable sont masqués.
• Les types enregistrés par d'autres applications avant le chargement de l'outil sont conservés, et les types natifs (Saisie de paiement, Écriture au journal) restent toujours en premier dans la liste.
• Les champs supplémentaires définis par get_fields sont injectés avant le bloc « Détails de la transaction ».
• Le bouton Valider et l'action Éditer en pleine page utilisent la même fonction create_voucher(values, allow_edit), qui appelle create du type sélectionné.

Réconciliation après soumission (pleine page)

Si un type de pièce propose l'édition en pleine page, l'utilisateur peut corriger le brouillon avant de le soumettre. À la soumission :

1. Le document est enregistré comme brouillon.
2. L'utilisateur est redirigé vers le formulaire complet.
3. À la soumission, la transaction bancaire est automatiquement réconciliée avec ce document — une seule fois.

Ce comportement s'applique aux types natifs et aux types inscrits avant le chargement de l'outil : Dodock ajoute le suivi de soumission aux DocTypes présents dans le registre à ce moment.

      
sequenceDiagram
  participant U as Comptable
  participant D as Dialogue de rapprochement
  participant S as Serveur
  U->>D: Sélectionne une transaction
  D->>D: Filtre les types via is_applicable
  U->>D: Choisit « Remboursement de prêt »
  D->>U: Affiche les champs spécifiques (get_fields)
  U->>D: Remplit les champs
  alt Soumission directe
    U->>D: Clique « Soumettre »
    D->>S: create(values, allow_edit=false)
    S-->>D: Transaction bancaire réconciliée
    D->>U: Mise à jour des cartes + fermeture
  else Édition pleine page
    U->>D: Clique « Éditer en pleine page »
    D->>S: create(values, allow_edit=true)
    S-->>D: Document brouillon
    D->>U: Ouvre le formulaire
    U->>S: Soumet le document
    S->>S: Réconcilie la transaction bancaire
  end

    

Cas d'usage — Remboursement de prêt

Exemple fictif : une application de prêts inscrit un type « Loan Repayment » :

• is_applicable : true uniquement pour les dépôts (remboursements reçus).
• get_fields : ajoute un champ « prêt » obligatoire pour rattacher le remboursement au contrat.
• create : appelle une méthode serveur de l'application (ici lending.api.create_loan_repayment) qui crée l'écriture de remboursement et renvoie la transaction réconciliée.

Le comptable voit « Loan Repayment » dans le sélecteur de type de pièce pour les transactions entrantes et peut créer le remboursement sans quitter le rapprochement bancaire.

Points de vigilance

• Le type doit être inscrit avant le chargement du bundle de l'outil de rapprochement. Privilégiez un hook déclenché tôt dans le cycle de vie de l'application cliente.
• Le nom du type dans le registre est la clé utilisée pour l'affichage dans le sélecteur. Évitez les doublons avec les types natifs.
• Si is_applicable n'est pas défini, le type est proposé pour toutes les transactions.
• La fonction create doit toujours renvoyer la transaction bancaire réconciliée (chemin direct) ou le brouillon (pleine page) pour que l'outil puisse mettre à jour l'interface.

Référence

• Fichier concerné : erpnext/public/js/bank_reconciliation_tool/dialog_manager.js
• Tests : erpnext/tests/js/bank_reconciliation_dialog_manager.test.mjs