Paisapp Pro

Aller au contenu

Développer un module

18/10/2026 · Guide du développeur

Synthèse

Principe : un module est un fichier JavaScript unique, sans import. L'application le charge après contrôle de son empreinte, lui accorde les ports qu'il déclare, affiche ses vues et lance ses automatisations.

  1. Créer : copier sdk/modele-module.js dans modules/<id>/<id>.js.
  2. Déclarer : besoins, réglages, vues, automatisations, styles.
  3. Essayer : essayerModule et rendreVue font tourner le module dans Node, sans navigateur ni relais.
  4. Publier : npm run registre construit le registre ; la relecture précède la copie vers paisapp.pro.

Un module ne touche jamais une clé. L'hôte signe, chiffre et publie à sa place.

1. Architecture

Le module suit l'architecture hexagonale d'App-core.

GarantieMécanisme
ProvenanceLe fichier vient toujours du registre relu ; un module absent de son index ne se charge pas
IntégritéEmpreinte SHA-384 épinglée dans le manifeste et dans l'index, contrôlée avant chaque chargement
Moindre droitL'hôte accorde seulement les ports déclarés, dans un objet figé
Aucune clé exposéeAucun port ne donne une clé ; l'hôte signe et chiffre
Aucun accès cachéLe registre refuse import, réseau direct, stockage du navigateur et code fabriqué à la volée
Isolement des stylesChaque sélecteur commence par .m-<id>

2. Créer un module

2.1 Arborescence

FichierRôle
modules/<id>/<id>.jsLe module, fichier unique
modules/<id>/README.mdAide courte, reprise par le registre et par paisapp.pro
modules/<id>/<id>.test.jsEssais node:test
registre.config.jsonCatégorie, auteur, licence et relecture, tenus par les mainteneurs du registre

2.2 Déclaration

L'export par défaut reçoit paisapp et renvoie paisapp.module({ … }).

export default (paisapp) => {
  const { html, montant } = paisapp.outils;
  return paisapp.module({
    id: 'fidelite', version: '1.0.0', socle: '^0.1',
    nom: 'Fidélité', description: 'Compte les commandes livrées de chaque client.',
    roles: ['pro'],
    besoins: { requis: ['commandes', 'stockage'], facultatifs: ['notifications'] },
    reglages: { palier: { type: 'nombre', libelle: 'Commandes avant un cadeau', defaut: 10, min: 1 } },
    vues: [{ id: 'clients', titre: 'Clients fidèles', role: 'pro', menu: true, ordre: 80, icone: 'equipe', rendre(ctx) { /* … */ } }],
    automatisations: [{ id: 'compter', titre: 'Compter les livraisons', declencheur: 'commande.etape', async executer(d, ports, reglages) { /* … */ } }],
    styles: '.m-fidelite .palier { color: var(--pa-couleur-secondaire); }',
  });
};
ChampRègle
idMinuscules, chiffres et tirets ; égal au nom du dossier
versionSemver ; toute modification publiée exige une nouvelle version
socleIntervalle accepté, par exemple ^0.1
nom, descriptionTextes affichés par l'atelier et le registre
rolesclient, pro ; déduits des vues s'ils manquent
besoinsPorts requis et facultatifs ; un port requis absent laisse le module inactif
reglagesSchéma typé, voir section 6
vuesÉcrans du module, voir section 5
automatisationsRéactions aux déclencheurs, voir section 4
stylesFeuille de 50 000 caractères au plus, sous .m-<id>

3. Ports

Chaque méthode répond par les formes d'App-core. Une méthode ne lève pas d'exception.

FormeSens
{ status: 'found', value }Donnée trouvée ; une liste répond toujours ainsi, vide au besoin
{ status: 'empty' }Rien ne correspond
{ status: 'unavailable' }Fonction absente de l'application
{ status: 'done', id }Écriture faite
{ status: 'failed', error: { code, message } }Refus, avec un code
PortMéthodes
sessionprofil() : pubkey, nom, role, entreprise, delegue, delegues, application
annuaireentreprises({ recherche, secteur, zone, limite }), entreprise(pubkey)
cataloguearticles({ vendeur, recherche, categorie, geohash, limite, avecIndisponibles }), evenements({ organisateur, depuis, limite })
publicationpublierArticle(article), retirerArticle(id), publierEvenement(evenement), retirerEvenement(id)
commandesliste({ role, etat, limite }), detail(commandeId)
commandepasser, etape, message, sousTraiter, deleguer
paniercontenu(), ajouter({ article, quantite }), changer({ article, quantite }), vider({ vendeur }) : chacune rend { lignes, total, nombre, parVendeur } ; un panier par application
stockagelire(cle), ecrire(cle, valeur), effacer(cle), cles()
notificationsavertir({ titre, texte, lien })
navigationaller('#/…')
horlogemaintenant(), synchrone, en secondes
journalecrire(niveau, message, donnees), synchrone

4. Déclencheurs

DéclencheurDonnées reçues
commande.recueRésumé de la commande, rôle vendeur
commande.etape{ commande, code, auteur, message }
commande.message{ commande, texte, auteur }
sous-commande.etape{ commande, parent, code } : commande est la sous-commande
minute{ maintenant }

5. Vues

5.1 Contexte

ChampRôle
elementÉlément où la vue dessine
ports, reglages, outilsPorts accordés, réglages contrôlés, outils de rendu
roleclient ou pro
parametres, requeteSegments après #/m/<module>/<vue>/ et paramètres après ?
applicationApplication métier courante, ou null dans l'application Paisapp
afficher(fragment)Remplace le contenu de l'élément
icone(nom, libelle)Icône de l'hôte en fragment sûr ; sans libellé, elle reste décorative
aller(chemin)Ouvre une autre vue
rafraichir()Relance rendre
surChangement(sujet, fn)Rappel quand commandes, catalogue, evenements, annuaire, panier, session ou modules (manifestes des applications) changent
reglagesEntreprise(cle)Dans l'application Paisapp seulement : réglages du module publiés par l'entreprise de cette clé, dans le manifeste le plus récent qu'elle a signé et qui contient le module. Résultat found (valeurs contrôlées comme reglages), empty (aucune application publiée) ou failed. Absente dans une application métier, où reglages sont ceux de l'entreprise, et chez un hôte plus ancien : la vue garde alors reglages
signalSignal levé quand l'utilisateur quitte la vue

5.2 Patron d'une vue

Le gabarit html échappe chaque valeur. La vue dessine par ctx.afficher, écoute une seule fois sur ctx.element et repère ses boutons par data-action. Elle renvoie une fonction de nettoyage.

async rendre(ctx) {
  const { html } = ctx.outils;
  let message = '';
  const dessiner = async () => {
    const r = await ctx.ports.commandes.liste({ role: 'vendeur', etat: 'ouvertes' });
    const liste = r.status === 'found' ? r.value : [];
    ctx.afficher(html`<section class="pa-page m-fidelite">
      ${message ? html`<p class="pa-alerte pa-alerte-succes" role="status">${message}</p>` : ''}
      <ul class="pa-liste">${liste.map((c) => html`<li class="pa-liste-element">${c.commandeId}</li>`)}</ul>
      <form data-action="noter"><label class="pa-champ"><span>Note</span><input name="note"></label>
      <button class="pa-bouton" type="submit">Enregistrer</button></form>
    </section>`);
  };
  const surEnvoi = async (e) => {
    const f = e.target.closest('form[data-action="noter"]');
    if (!f) return;
    e.preventDefault();
    const note = [...f.elements].find((x) => x.name === 'note')?.value ?? '';
    await ctx.ports.stockage.ecrire('note', note);
    message = 'Note enregistrée.';
    await dessiner();
  };
  ctx.element.addEventListener('submit', surEnvoi);
  ctx.surChangement('commandes', dessiner);
  await dessiner();
  return () => ctx.element.removeEventListener('submit', surEnvoi);
}

5.3 Vocabulaire CSS de l'hôte

ClasseRôle
pa-page, pa-pile, pa-ligne, pa-grilleVue, pile verticale, ligne souple, grille de cartes
pa-titre, pa-sous-titre, pa-texte-douxTitres et texte secondaire
pa-carte, pa-carte-image, pa-carte-corpsCarte
pa-bouton, pa-bouton-secondaire, pa-bouton-discret, pa-bouton-dangerBoutons
pa-badge, pa-badge-succes, pa-badge-alerte, pa-badge-erreurPastilles
pa-prixMontant mis en valeur
pa-liste, pa-liste-elementListe à lignes
pa-vide, pa-chargementÉtat vide, chargement
pa-alerte, pa-alerte-succes, pa-alerte-erreurEncadrés
pa-formulaire, pa-champ, pa-aide, pa-actionsFormulaires
pa-tableauTableau
pa-etapes, pa-etape, pa-etape-faite, pa-etape-couranteFrise des étapes
pa-quantiteChoix d'une quantité

Icônes : accueil, catalogue, panier, commandes, evenement, entreprise, equipe, automatisation, reglages, message, recherche, ajouter, retour.

5.4 Styles

6. Réglages

L'atelier construit le formulaire depuis le schéma. L'hôte contrôle chaque valeur et remplace une valeur refusée par le défaut.

TypeValeurOptions du schéma
texteTexte d'une ligne, 200 caractères par défautlongueur
texteLongTexte de 5 000 caractères par défautlongueur
nombreNombre finimin, max
booleenVrai ou faux
choixUne valeur parmi optionsoptions: [{ valeur, libelle }]
couleur#rrggbb
liste100 textes de 200 caractères au plus
cleClé publique hexadécimale

Chaque réglage porte libelle, aide et defaut. Un défaut invalide fait refuser le module.

7. Outils

paisapp.outils et ctx.outils donnent les mêmes fonctions.

OutilUsage
html, brut, echapper, adresseSureGabarit échappé, fragment sûr, échappement, adresse https ou locale
markdownMarkdown réduit, rendu en fragment sûr
montant, montantTexte12,50 € ; 12.50
date, heure, dateHeure, dateLongue, depuisFormats de Paris
versSecondes, versChampsChamps date et heure vers secondes, et retour
etapes, etapeÉtapes des commandes et leurs libellés
identifiant, geohashIdentifiant aléatoire ; geohash d'une position

8. Essayer

Le kit d'essai charge le module comme l'application : empreinte, hôte, ports accordés. Les ports en mémoire simulent un marché complet.

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { essayerModule, rendreVue, texteDe } from '#sdk/essai.js';

test('compte une livraison', async () => {
  const e = await essayerModule(new URL('./fidelite.js', import.meta.url), { reglages: { palier: 2 } });
  assert.equal(e.actif, true, e.raison);
  const article = e.demo.articles[0];
  const id = await e.simuler.recevoirCommande({ acheteur: 'c'.repeat(64), lignes: [{ article: article.adresse, quantite: 1 }] });
  await e.ports.commande.etape({ commandeId: id, code: 'livree' });
  const vue = await rendreVue(e, 'clients');
  assert.match(texteDe(vue.html), /Clients fidèles/);
  await vue.emettre('submit', { action: 'noter', champs: { note: 'Merci' } });
});
Option de essayerModuleRôle
moiUtilisateur : propriétaire de l'entreprise de démonstration par défaut ; client ou délégué au besoin
reglagesValeurs des réglages
articles, evenements, entreprisesDonnées du marché simulé
deleguesClés autorisées par le manifeste
maintenantHorloge de l'essai, en secondes
sansPortsPorts retirés, pour essayer un module privé d'un port
outilsOutils de l'hôte à la place de ceux du socle, pour essayer le module avec ceux d'une application
portsFonction qui reçoit les ports en mémoire et rend ceux qui les remplacent : un port qui se fait attendre, pour redessiner la vue pendant l'attente (ctx.rafraichir())
manifestesFonction (clé) → manifestes signés (kind 30078) publiés par cette clé ; avec elle, ctx.reglagesEntreprise existe, comme dans l'application Paisapp
RésultatRôle
actif, raison, declarationÉtat du chargement
ports, etatPorts complets et état du marché : commandes, notifications, navigation, journal
simulerrecevoirCommande, recevoirEtape, recevoirMessage, minute
stockageStockage propre au module
declencher(nom, donnees)Lance un déclencheur et rend les résultats

rendreVue(essai, id, { role, parametres, requete }) rend une vue dans un faux élément. emettre('click', { action, donnees }) simule un clic ; emettre('submit', { action, donnees, champs }) simule un formulaire. quitter() vérifie le nettoyage.

npm test lance tous les essais. npm run check y ajoute le contrôle des règles et du registre.

9. Publier au registre

  1. Déclarer le module dans registre.config.json : catégorie, auteur, licence, relecture. Catégories : presentation, vente, organisation, automatisation, delegation.
  2. Construire : npm run registre. Le script charge chaque module par l'hôte, applique les règles, copie le fichier à l'octet près dans registre/modules/<id>/<version>.js et écrit registre/index.json.
  3. Contrôler : npm run check.
  4. Relire : un mainteneur relit le code, puis passe relu à vrai.
  5. Diffuser : scripts/publier-registre.sh ../paisapp-fr-pro, puis scripts/publier-registre.sh ../paisapp-fr-site. paisapp.pro sert le registre ; paisapp.fr en garde une copie.

10. Relecture

Le registre refuse un module qui contient :

Le relecteur vérifie ensuite le sens : ports demandés justifiés, aucune donnée envoyée hors des ports, textes échappés, messages clairs pour l'utilisateur.

11. Limites actuelles