aloli-crystal/partiduo-modeles

= partiduo-modeles — modèles de factures multiformats :toc: left :toc-title: Table des matières :icons: font

Partiduo est le portage en Crystal de https://noalyss.eu[NOALYSS], logiciel libre de comptabilité créé et maintenu par Dany De Bontridder. Partiduo n'est pas un projet officiel NOALYSS.

Ce dépôt est l'extension MODELES de Partiduo (ADR-010) : l'entreprise dépose son propre modèle de facture, de devis ou d'avoir en AsciiDoc, Markdown, OpenDocument (ODT) ou Microsoft Word (DOCX), avec des champs de fusion ; Partiduo le remplit avec un document de la Facturation et rend le résultat dans le même format et, quand le serveur a le convertisseur voulu, en PDF. Chaque rendu d'un document émis est conservé avec son empreinte SHA-256 et la version du modèle.

La spécification est dans ../partiduo-docs/adr/ADR-010-modeles-de-factures.adoc (D1 à D7), avec ADR-003 (contrat d'extension), ADR-004 D9 (factures non électroniques, copie PDF), ADR-005 (interface) et ADR-006 (Facturation). Les décisions et blocages propres à ce dépôt sont dans link:doc/ETAT.adoc[] (D-MOD-…, B-MOD-…).

IMPORTANT: Le PDF légal Factur-X de la Facturation reste la référence (plateforme agréée, copie PDF). Un rendu de modèle est une présentation de la facture, pour le papier et le courrier : il ne modifie jamais la facture (ni numéro, ni montants, ni empreinte).

== Fonctions

[cols="1,3",options="header"] |=== |Fonction |Dans MODELES

|Dépôt contrôlé (D3) |Syntaxe, balises et filtres admis, champs connus, mentions obligatoires du type de document ; un modèle incomplet est refusé avec la liste de ce qui manque. Rapport à l'écran ; remarque si le PDF n'est pas disponible pour ce format.

|Aperçu (D3) |Rendu avec une facture, un devis ou un avoir fictif marqué « Exemple — sans valeur », au format du modèle et en PDF ; rien n'est conservé.

|Versions (D3) |Chaque dépôt crée une version ; une version n'est en service qu'après son activation ; les documents déjà rendus gardent la leur.

|Défaut (D4) |Un modèle par défaut par type de document (facture, devis, avoir) et langue.

|Rendu (D4) |Depuis la fiche d'un devis, d'une facture, d'une facture d'acompte ou d'un avoir émis (bouton « Rendre avec un modèle » du panneau de l'extension) : fichier au format du modèle et PDF, conservés en pièces jointes du socle (empreintes SHA-256, version du modèle), listés sur la fiche du document et dans l'historique. Un brouillon est rendu en aperçu marqué « Brouillon — sans valeur », téléchargé aussitôt et non conservé.

|PDF (D5) |partiduo-modeles-pdf, exécutable de ce shard sur asciicrystal-pdf (AsciiDoc, et Markdown converti en AsciiDoc), LibreOffice (ODT, DOCX), facultatifs, déclarés par l'instance, lancés sans shell avec un délai.

|Modèles de départ (D6) |Facture, devis, avoir × AsciiDoc, Markdown, ODT, DOCX × français, anglais, néerlandais, complets et conformes, téléchargeables depuis l'écran (et lisibles dans starters/).

|Droits (D7) |modeles.read : rendre, télécharger ; modeles.admin : déposer, activer, désigner par défaut, retirer. Rendre un document exige aussi la lecture des factures (invoicing.invoice.read). |===

== Installation

L'extension est un shard ; elle dépend du cœur (partiduo-app) et de la Facturation (depends_on "INVOICING"). Une distribution la compose ainsi :

[source,crystal]

require "partiduo-ui-bulma/partiduo_ui" require "partiduo-modeles" require "partiduo-modeles/ui/bulma"

Marten.configure do |config| config.installed_apps = config.installed_apps + Modeles::INSTALLED_APPS + Modeles::Ui::INSTALLED_APPS end

et ajoute require "partiduo-modeles/cli" à sa ligne de commande pour les migrations (tables modeles_template, modeles_template_version, modeles_stored_file, modeles_rendition). L'extension s'active par dossier : PARTIDUO_MODULES=invoicing,modeles ou l'écran des modules. L'interface est montée sous /ext/MODELES/ ; le menu « Modèles de documents » est sous « Facturation ».

== Convertisseurs PDF (facultatifs)

Aucun convertisseur n'est requis : sans lui, seul le fichier au format du modèle est produit, et l'écran le dit (dépôt, fiche du modèle, rendu).

[cols="1,2,2",options="header"] |=== |Format |Outil |Variable de l'instance

Les lignes d'un modèle AsciiDoc qui désignent des fichiers du serveur (:pdf-theme:, :pdf-themesdir:, :pdf-fontsdir:) sont retirées avant la conversion.

La valeur d'une variable est le chemin de l'outil, ou auto pour le chercher à côté de l'exécutable du serveur, puis dans le PATH ; absente ou vide, le PDF du format est désactivé.
PARTIDUO_MODELES_CONVERT_TIMEOUT : délai maximal en secondes (60 par défaut) ; au-delà, l'outil est tué et l'échec noté sur le rendu.
Chaque conversion est lancée sans shell (tableau d'arguments), dans un répertoire temporaire propre effacé ensuite (HOME et TMPDIR y pointent, profil LibreOffice compris). L'absence de réseau repose sur les modes sûrs des outils et sur le déploiement (voir B-MOD-003).

Installation : apt install libreoffice-writer-nogui (Debian, Ubuntu) ; partiduo-modeles-pdf se construit avec ce shard, aux versions de shard.lock :

[source,sh]

shards build partiduo-modeles-pdf --release

Construisez-le sur la machine qui sert, ou à un chemin identique : ses polices (DejaVu) sont lues dans lib/asciicrystal-pdf/data/fonts du répertoire de construction, chemin fixé à la compilation.

== Écrire un modèle

Le langage de fusion est la syntaxe des gabarits de Marten, bridée au seul contexte de fusion (ADR-010 D2) :

champs : {{ facture.numero }}, {{ client.nom|upcase }}, {{ facture.notes|default:"—" }} ;
conditions : {% if totaux.acompte %}…{% elsif … %}…{% else %}…{% endif %}, {% unless … %} ; opérateurs &&, ||, not, ==, !=, <, >, in ;
boucles : {% for ligne in lignes %}…{% endfor %}, avec loop.index, loop.first?, loop.last? ;
texte littéral : {% verbatim %}…{% endverbatim %}.

Toute autre balise (include, extend, url, translate, assign…) et les filtres safe, escape, linebreaks sont refusés : le modèle ne voit que le vocabulaire ci-dessous, jamais les modèles de données ni la requête. Une valeur vide est fausse dans une condition et remplacée par default.

Les valeurs sont échappées selon le format : XML pour ODT et DOCX (retours à la ligne rendus par <text:line-break/> ou <w:br/>), références numériques pour les caractères actifs d'AsciiDoc, barre oblique inverse pour ceux de Markdown (et retour à la ligne remplacé par une espace dans une ligne de tableau). Montants et dates suivent la langue du document, comme le PDF légal : 1 234,56 et 15/09/2026 (fr), 1,234.56 et 2026-09-15 (en), 1.234,56 et 15-09-2026 (nl) ; les montants sont imprimés sans symbole, la devise est {{ facture.devise }}.

=== ODT et DOCX

Un traitement de texte coupe volontiers un champ en plusieurs fragments de mise en forme : le modèle est normalisé avant la fusion (fragments d'une même balise réunis dans le premier, entités décodées, guillemets typographiques redressés).
Ligne de tableau répétée : une ligne qui ouvre {% for ligne in lignes %} dans une cellule et le ferme ({% endfor %}) dans une autre cellule, ou dans une ligne suivante, est répétée pour chaque ligne de la facture. De même, un {% if %} sans else ouvert et fermé dans des cellules différentes rend ces lignes conditionnelles (acomptes déduits). Ouvert et fermé dans la même cellule, le bloc reste dans le texte de la cellule.
Un paragraphe du corps qui ne contient que des balises de bloc ({% if facture.notes %} seul sur sa ligne) disparaît à la fusion.
ODT : content.xml et styles.xml (en-têtes et pieds de page) ; DOCX : word/document.xml, word/header*.xml, word/footer*.xml.

=== Mentions obligatoires

Un modèle doit imprimer le numéro, la date, le nom et l'adresse du vendeur et du client, la boucle des lignes (désignation, quantité, prix unitaire hors taxe, montant hors taxe), le taux et le montant de la TVA, les totaux hors taxe et TTC, et les mentions légales calculées par le cœur. Le bloc {{ mentions }} (ou une boucle qui imprime mention.texte) couvre à lui seul les mentions légales : SIREN et numéros de TVA du vendeur et de l'acheteur, dates d'émission, de livraison et d'échéance, pénalités de retard, indemnité forfaitaire de recouvrement, escompte, exonération ou autoliquidation de la TVA, facture d'origine d'un avoir, validité d'un devis.

== Vocabulaire de fusion

=== facture — Le document