Modèle de données

Dans Dodock, tout est Document. Cette abstraction uniforme simplifie le développement, l'extension et la maintenance des applications.

Concepts fondamentaux

DocType et Document

Un DocType est la définition d'un type de document : il décrit les champs, les comportements et les permissions. Un Document est une instance de ce DocType, c'est-à-dire un enregistrement en base de données.

      flowchart TB
    subgraph DocType["DocType : Facture de vente"]
        D1["Champs : client, montant, date, articles..."]
        D2["Permissions : lecture, création, soumission..."]
        D3["Comportements : soumissible, nommage auto..."]
    end

    DocType -->|définit| Documents

    subgraph Documents["Documents (instances)"]
        DOC1["FACT-00001<br/>Client A<br/>1 500 €"]
        DOC2["FACT-00002<br/>Client B<br/>2 300 €"]
        DOC3["FACT-00003<br/>Client A<br/>890 €"]
    end

    

Analogie avec les bases de données

Types de champs (DocField)

Chaque champ d'un DocType est défini par :

• fieldname : Nom technique (snake_case)
• fieldtype : Type de données
• label : Libellé affiché
• reqd : Obligatoire ou non

Types de champs disponibles

Champs de mise en page

Champs standards

Tous les documents possèdent automatiquement ces champs de métadonnées :

États du document (docstatus)

Pour les DocTypes soumissibles (option « Est soumissible ») :

Nommage des documents

Le champ name est l'identifiant unique de chaque document. La propriété « Règle de nommage » du DocType choisit la méthode. Elle remplit la propriété autoname :

Le contrôleur peut aussi définir une méthode autoname(self) qui calcule self.name.

Exemple de série

Avec la règle « Par série », l'utilisateur choisit la série dans le champ naming_series du document. Une série comme FACT-.YYYY.-.##### donne FACT-2026-00001. .YYYY. est remplacé par l'année et ##### par un compteur sur 5 chiffres.

Lire ou modifier le compteur d'une série depuis le code

La classe NamingSeries de frappe.model.naming donne accès au compteur d'une série. Le compteur est stocké dans le DocType Series, sous une clé qui est le préfixe calculé de la série : FACT-2026- pour FACT-.YYYY.-.#####.

Quand la série contient une partie {nom_du_champ}, le préfixe dépend de la valeur de ce champ. Passez alors le document en argument doc : sans lui, la partie n'est pas remplacée et le préfixe garde le texte littéral {nom_du_champ}. Les trois méthodes qui lisent ou écrivent le compteur (get_prefix, get_current_value, update_counter) acceptent ce paramètre facultatif. Un appel sans doc se comporte comme avant.

Exemple : avec un document Webhook dont le champ webhook_docevent vaut on_update :

from frappe.model.naming import NamingSeries

webhook = frappe.new_doc("Webhook")
webhook.webhook_docevent = "on_update"

series = NamingSeries("KOOH-.{webhook_docevent}.-.####")

series.get_prefix()         # "KOOH-{webhook_docevent}-"
series.get_prefix(webhook)  # "KOOH-on_update-"

series.update_counter(7, webhook)
series.get_current_value(webhook)  # 7

Relations entre DocTypes

Link (relation 1-1 ou N-1)

Un champ Link crée une référence vers un autre DocType.

      
erDiagram
    Facture ||--o{ Client : "client (Link)"
    Facture {
        string name
        string client
        date date_facturation
        float montant
    }
    Client {
        string name
        string nom_complet
        string email
    }

    

Table (relation 1-N)

Un champ Table intègre une table enfant directement dans le document parent.

      
erDiagram
    FactureDeVente ||--|{ LigneFacture : "articles (Table)"
    FactureDeVente {
        string name
        string client
        date date
        float total
    }
    LigneFacture {
        string parent
        string article
        int quantite
        float montant
    }

    

Exemple concret :

Cycle de vie d'un document

      flowchart TD
    A[before_insert] --> B[before_validate / validate]
    B --> B2[before_save]
    B2 --> C{INSERT / UPDATE}
    C --> D[after_insert<br/>on_update]
    D --> E{Validation ?}
    E -->|oui| F[on_submit]
    E -->|non| G{Suppression ?}
    F --> H{Annulation ?}
    H -->|oui| I[on_cancel]
    H -->|non| G
    I --> G
    G -->|oui| J[on_trash]
    G -->|non| K((Fin))
    J --> K

    

Événements disponibles

Une application peut aussi réagir à ces événements sans modifier le contrôleur, avec le hook doc_events. Voir Référence des hooks.

Pour aller plus loin