Scopes et consentement de l'organisation

Le principe

Le tableau permissions du manifeste liste des scopes : un par accès
réel à des données de l’organisation. Un scope s’écrit ressource:action
avec une ressource feuille (crm.contacts, shop.orders,
billing-fr.documents…) et une action read ou write.

{ "permissions": ["crm.contacts:read", "crm.activities:write"] }

Deux règles, appliquées à la validation du manifeste :

• Jamais un module entier. crm:read est refusé : par la hiérarchie des
  droits de Capibara, il donnerait tout crm.* d’un coup. Le message
  d’erreur nomme les scopes feuilles à demander à la place.
• Uniquement le catalogue ci-dessous. Chaque scope accepté ouvre au moins
  une façade ; un scope hors catalogue n’ouvrirait rien,
  il est refusé.

Le catalogue (généré)

CRM

Scope	Ce que l’organisation accepte
crm.contacts:read	Lire vos contacts (nom, coordonnées, étiquettes, notes)
crm.contacts:write	Créer et modifier des contacts
crm.companies:read	Lire vos sociétés
crm.companies:write	Créer et modifier des sociétés
crm.opportunities:read	Lire vos opportunités (pipeline, montants)
crm.opportunities:write	Créer et faire avancer des opportunités
crm.activities:read	Lire l’historique et les tâches du CRM
crm.activities:write	Ajouter des notes et des tâches dans le CRM

Facturation

Scope	Ce que l’organisation accepte
billing-fr.documents:read	Lire vos devis, factures et avoirs (statut, lignes, totaux)
billing-fr.documents:write	Créer des brouillons de devis et de factures, les émettre et les envoyer
billing-fr.pos:read	Lire vos encaissements par carte (statut, montant)
billing-fr.pos:write	Créer des encaissements par carte (montant + libellé) réglés sur votre page de paiement

Boutique

Scope	Ce que l’organisation accepte
shop.products:read	Lire votre catalogue (produits, déclinaisons, stock vendable)
shop.products:write	Modifier des produits (nom, description, prix, publication)
shop.orders:read	Lire vos commandes
shop.orders:write	Faire avancer vos commandes (expédiée, livrée) et poser un numéro de suivi

Projets

Scope	Ce que l’organisation accepte
projects:read	Lire vos projets et leurs tâches
projects.tasks:write	Créer et déplacer des tâches, commenter, enregistrer du temps

Planning

Scope	Ce que l’organisation accepte
planning.resources:read	Lire vos ressources réservables
planning.bookings:read	Lire vos réservations
planning.bookings:write	Créer des réservations (mêmes gardes que la réservation en ligne)

Site

Scope	Ce que l’organisation accepte
site.members:read	Lire les membres de votre site (nom, e-mail, statut)

Formation

Scope	Ce que l’organisation accepte
formation.catalogue:read	Lire votre catalogue de formations
formation.sessions:read	Lire vos sessions inter-entreprises et leurs inscriptions

Ce que voit l’administrateur

À l’installation, l’écran de consentement affiche chaque scope en français
(la colonne de droite ci-dessus), avec son module et l’identifiant technique
en petit. Les scopes sont tout ou rien : l’app s’installe avec l’ensemble
ou pas du tout (patron Discord / Shopify). Une version qui ajoute un scope
n’est jamais appliquée automatiquement chez les organisations déjà
installées : l’administrateur voit la liste avec les nouveaux scopes marqués
« nouveau » et ré-accepte — ou reste sur sa version. Tant qu’il n’a pas
ré-accepté, vos handlers ne s’exécutent pas et vos surfaces l’expliquent.

Le compte de service

À l’installation, Capibara crée dans l’organisation un compte de service
app:<clé> : un utilisateur technique, masqué des listes, sans connexion
possible, dont l’avatar est l’icône de votre app, et dont l’unique rôle porte
exactement les scopes accordés. Toute écriture de votre app passe par les
services de la plateforme sous ce compte — les mêmes que ceux d’un humain :
contrôle des droits, journal d’activité (« App Météo a créé le contact
Dupont »), notifications, événements de domaine. Il n’existe aucune seconde
porte d’écriture.

Deux contextes d’exécution :

• contexte utilisateur — pages, panneaux, widgets, actions : les façades
  s’exécutent sous la personne qui interagit, bornée par vos scopes (une
  app ne fait jamais plus que l’humain qui clique) ;
• contexte app — événements, planifications, HTTP entrant, backend
  externe : les façades s’exécutent sous le compte de service.

« Utiliser l’app »

Chaque app installée génère une ressource app.<clé> : app.<clé>:read
= ouvrir ses pages, widgets et panneaux. Les rôles par défaut Manager et
Employé la reçoivent à l’installation (l’Administrateur a le wildcard) ; pour
un rôle personnalisé, l’administrateur coche « Utiliser l’app » dans
Mon organisation › Rôles. Sans ce droit, l’app n’apparaît ni dans le menu,
ni dans le sélecteur de widgets, ni sur les fiches.

Revalidés en base, jamais en confiance

À chaque appel de façade, la plateforme vérifie : scope déclaré dans le
manifeste et accordé à l’installation et porté par l’acteur (compte de
service ou personne) dans les droits de l’organisation. Un scope retiré (app
désinstallée, module désactivé) est refusé immédiatement.

Bonnes pratiques

• Un scope par usage réel — lire les contacts pour un résumé =
  crm.contacts:read, pas crm.contacts:write « au cas où ».
• Lecture et écriture sont distinctes — demandez write seulement si
  vous créez ou modifiez.
• Moins de scopes = review plus rapide et plus d’installations : une
  longue liste fait hésiter.
• Expliquez les scopes inhabituels dans votre fiche : un scope sans
  rapport visible avec l’app est un motif de refus fréquent en review.