Gestion des adresses et contacts

Introduction

La gestion des adresses et des contacts est une fonctionnalité centrale de Dokos qui permet de maintenir des informations précises et à jour pour vos clients, fournisseurs et autres partenaires commerciaux. Cette documentation couvre les aspects techniques et les bonnes pratiques pour configurer et utiliser efficacement ces fonctionnalités.

Nouvelle interface des cartes d'adresse et de contact

La refonte des cartes d'adresse et de contact introduit une interface moderne basée sur les composants Espresso, offrant une meilleure expérience utilisateur et des fonctionnalités améliorées.

Architecture technique

      
flowchart TD
    A[Formulaire Client/Fournisseur] --> B[AddressAndContactCard]
    B --> C[AddressCard]
    B --> D[ContactCard]
    C --> E[Espresso Button]
    C --> F[Espresso Badge]
    C --> G[Espresso Dropdown]
    D --> E
    D --> F
    D --> G

    

Fichiers clés :

• frappe/public/js/frappe/utils/address_and_contact.js : Logique principale
• frappe/public/js/frappe/form/templates/address_list.html : Template des cartes d'adresse
• frappe/public/js/frappe/form/templates/contact_list.html : Template des cartes de contact

Fonctionnalités principales

1. Composants Espresso :
   • Boutons modernes avec états interactifs
   • Badges visuels pour les statuts
   • Menus déroulants (kebab) pour les actions
   • État vide avec bouton de création
2. Gestion des adresses :

   // Exemple de méthode pour définir une adresse comme principale
   set_as_primary_address: function(frm, address_name) {
       frappe.call({
           method: "frappe.contacts.address_and_contact.set_as_primary_address",
           args: {
               address_name: address_name,
               party_type: frm.doctype,
               party_name: frm.doc.name
           },
           callback: function() {
               frm.reload_doc();
           }
       });
   }
   

3. Gestion des contacts :

   // Exemple de méthode pour définir un contact comme principal
   set_as_primary_contact: function(frm, contact_name) {
       frappe.call({
           method: "frappe.contacts.address_and_contact.set_as_primary_contact",
           args: {
               contact_name: contact_name,
               party_type: frm.doctype,
               party_name: frm.doc.name
           },
           callback: function() {
               frm.reload_doc();
           }
       });
   }
   

4. Fonctionnalité Unlink :

   # Méthode backend pour détacher une adresse
   @frappe.whitelist()
   def unlink_address(party_type, party_name, address_name):
       frappe.db.set_value("Dynamic Link", {
           "parenttype": "Address",
           "parent": address_name,
           "link_doctype": party_type,
           "link_name": party_name
       }, "is_primary", 0)
   

5. Création rapide :
   • Formulaire simplifié pour créer une adresse ou un contact directement depuis la fiche client/fournisseur
   • Le contact créé est automatiquement lié à la fiche parente
   • Champ email inclus dans le formulaire de contact rapide

Configuration avancée

Personnalisation des cartes

Vous pouvez personnaliser l'apparence des cartes via le fichier SCSS :

// frappe/public/scss/common/controls.scss
.address-card, .contact-card {
    border: 1px solid var(--border-color);
    border-radius: var(--border-radius-md);
    padding: var(--padding-md);
    margin-bottom: var(--margin-sm);
    
    .primary-badge {
        background-color: var(--primary-color);
        color: white;
        padding: 2px 8px;
        border-radius: var(--border-radius-sm);
        font-size: 0.8em;
    }
}

Surcharge des templates

Pour modifier le contenu des cartes, vous pouvez surcharger les templates HTML :

<!-- Exemple de surcharge pour les cartes d'adresse -->
<div class="address-card">
    <div class="address-header">
        <h4>{{ address.address_title }}</h4>
        {% if address.is_primary %}
        <span class="primary-badge">Principal</span>
        {% endif %}
    </div>
    <div class="address-body">
        {{ address.address_line1 }}<br>
        {{ address.address_line2 }}<br>
        {{ address.city }} {{ address.pincode }}<br>
        {{ address.country }}
    </div>
    <div class="address-actions">
        <button class="espresso-button espresso-button--secondary">
            <i class="i-mdi-pencil"></i>
        </button>
        <espresso-dropdown>
            <button slot="trigger" class="espresso-button espresso-button--secondary">
                <i class="i-mdi-dots-vertical"></i>
            </button>
            <espresso-dropdown-item @click="set_as_primary">Définir comme principal</espresso-dropdown-item>
            <espresso-dropdown-item @click="unlink">Détacher</espresso-dropdown-item>
        </espresso-dropdown>
    </div>
</div>

Bonnes pratiques

1. Gestion des adresses partagées :
   • Utilisez la fonction Unlink plutôt que Supprimer pour les adresses utilisées par plusieurs entités
   • Une adresse supprimée est définitivement perdue, tandis qu'une adresse détachée reste disponible pour d'autres entités
2. Adresses principales :
   • Définissez toujours une adresse principale pour chaque client/fournisseur
   • L'adresse principale est automatiquement utilisée dans les documents commerciaux
   • Seule une adresse peut être marquée comme principale à la fois
3. Contacts multiples :
   • Créez des contacts distincts pour différents services (commercial, comptabilité, logistique)
   • Utilisez le champ email dans le formulaire rapide pour capturer les informations de contact
4. Performance :
   • Limitez le nombre d'adresses et contacts par fiche pour maintenir de bonnes performances
   • Archivez les adresses/contacts inutilisés plutôt que de les supprimer
5. Sécurité :
   • Les données sensibles dans les cartes sont désormais échappées pour prévenir les attaques XSS
   • Vérifiez toujours les permissions avant d'afficher des informations sensibles

Dépannage

Problèmes courants

1. Les cartes ne s'affichent pas :
   • Vérifiez que les fichiers JavaScript sont correctement chargés (address_and_contact.js)
   • Assurez-vous que les templates HTML sont dans le bon répertoire
   • Vérifiez la console pour les erreurs JavaScript
2. Les actions ne fonctionnent pas :
   • Vérifiez que les méthodes backend sont correctement exposées via @frappe.whitelist()
   • Assurez-vous que l'utilisateur a les permissions nécessaires
   • Vérifiez les logs pour les erreurs Python
3. Les adresses/contacts ne se mettent pas à jour :
   • Vérifiez que frm.reload_doc() est appelé après les modifications
   • Assurez-vous que les hooks de document sont correctement configurés

Journalisation

Activez la journalisation pour le débogage :

# frappe/contacts/address_and_contact.py
import frappe
import logging

logger = logging.getLogger(__name__)

@frappe.whitelist()
def set_as_primary_address(address_name, party_type, party_name):
    logger.debug(f"Setting {address_name} as primary for {party_type}: {party_name}")
    # ... logique existante ...

Exemples d'utilisation

Scénario 1 : Gestion d'un client avec plusieurs sites

Pour la société "Maison Verte SARL" :

1. Créez une adresse principale pour le siège social
2. Ajoutez des adresses secondaires pour chaque magasin
3. Définissez l'adresse du siège comme principale
4. Créez des contacts pour chaque responsable de magasin
5. Définissez le contact du siège comme principal

Scénario 2 : Fournisseur avec plusieurs contacts

Pour le fournisseur "Bureau Moderne" :

1. Créez une adresse pour le siège social
2. Ajoutez un contact commercial avec son email
3. Ajoutez un contact logistique
4. Ajoutez un contact comptable
5. Définissez le contact commercial comme principal

Évolutions futures

1. Intégration avec les services de cartographie :
   • Affichage des adresses sur une carte
   • Calcul d'itinéraires
2. Gestion des horaires :
   • Ajout d'horaires d'ouverture pour les adresses
   • Intégration avec le module de planification
3. Améliorations des contacts :
   • Ajout de champs personnalisés
   • Intégration avec les réseaux sociaux
   • Gestion des préférences de communication
4. Synchronisation :
   • Synchronisation avec les carnets d'adresses externes
   • Import/export CSV amélioré