Architecture

Modèle de données

DocTypes, Documents et métadonnées dans Dodock

Modèle de données

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

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

Concept Dodock	Équivalent SQL	Description
DocType	Table + Schéma	Définition de la structure
Document	Ligne (row)	Enregistrement de données
DocField	Colonne	Champ du document
Link	Clé étrangère	Référence vers un autre DocType
Table	Table enfant	Relation 1-N intégrée

Fait amusant : Un DocType est lui-même un Document, stocké dans le DocType "DocType". Cette approche récursive permet de modifier la structure des données depuis l'interface utilisateur.

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

Type	Description	Exemple
Data	Texte court	Nom, référence
Text	Texte long	Description
Int	Nombre entier	Quantité
Float	Nombre décimal	Taux
Currency	Montant monétaire	Prix, total
Date	Date	Date de facturation
Datetime	Date et heure	Horodatage
Check	Case à cocher	Actif/Inactif
Select	Liste déroulante	Statut
Link	Référence vers un DocType	Client, Article
Table	Table enfant	Lignes de facture
Attach	Fichier joint	Document PDF

Champs de mise en page

Type	Description
Section Break	Nouvelle section
Column Break	Nouvelle colonne
Tab Break	Nouvel onglet
HTML	Contenu HTML personnalisé

Champs standards

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

Champ	Type	Description
`name`	Data	Identifiant unique du document
`owner`	Link (User)	Utilisateur créateur
`creation`	Datetime	Date de création
`modified`	Datetime	Date de dernière modification
`modified_by`	Link (User)	Dernier utilisateur modificateur
`docstatus`	Int	État du document

États du document (docstatus)

Pour les DocTypes soumissibles :

Valeur	État	Description
0	Brouillon	Modifiable, non validé
1	Soumis	Validé, non modifiable
2	Annulé	Annulé après soumission

Nommage des documents

Le champ name est l'identifiant unique de chaque document. Plusieurs stratégies de nommage sont disponibles :

Stratégie	Exemple	Usage
Série	`FACT-2024-00001`	Documents numérotés
Champ	Valeur d'un champ	Noms uniques naturels
Expression	`{client}-{date}`	Combinaison de valeurs
Hash	`a1b2c3d4e5`	Identifiants aléatoires
Prompt	Saisie manuelle	Cas particuliers

Exemple de série

# Dans le DocType, définir autoname :
autoname = "naming_series:"

# L'utilisateur choisit parmi les séries définies :
# FACT-.YYYY.-.#####  → FACT-2024-00001
# FAC-.MM.-.####      → FAC-01-0001

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 :

Facture de vente	Client A
Date	2024-01-15
Articles
ART-001	5 × 100 € = 500 €
ART-002	3 × 100 € = 300 €
Total	800 €

Cycle de vie d'un document

      flowchart TD
    A[before_insert] --> B[validate]
    B --> C{INSERT / SAVE}
    C --> D[after_insert<br/>after_save]
    D --> E{Soumission ?}
    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

Événement	Moment	Usage typique
`before_insert`	Avant création	Valeurs par défaut
`validate`	Avant sauvegarde	Validations métier
`before_save`	Avant sauvegarde	Calculs automatiques
`after_insert`	Après création	Notifications
`after_save`	Après sauvegarde	Actions post-sauvegarde
`on_submit`	À la soumission	Écritures comptables
`on_cancel`	À l'annulation	Contre-passations
`on_trash`	À la suppression	Nettoyage

Pour aller plus loin

Personnaliser les DocTypes

Ajouter des champs et comportements

API Documents

Référence complète de l'API

Rôles et permissions

Gérer les accès

Modèle de données

Modèle de données

Concepts fondamentaux

DocType et Document

Analogie avec les bases de données

Types de champs (DocField)

Types de champs disponibles

Champs de mise en page

Champs standards

États du document (docstatus)

Nommage des documents

Exemple de série

Relations entre DocTypes

Link (relation 1-1 ou N-1)

Table (relation 1-N)

Cycle de vie d'un document

Événements disponibles

Pour aller plus loin