@liorian/sdk 0.28.0-alpha.56010ca

package/schemas/module.schema.json

@@ -0,0 +1,818 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "module-manifest.schema.json",
+  "$comment": "Schéma canonique du manifest.json des modules Liorian (@liorian/sdk). Référencé par les modules du socle (frontend/liorian-socle/src/modules/*) et les modules externes (frontend/liorian-socle/external_modules/*).",
+  "title": "Module Manifest (Liorian)",
+  "description": "Manifeste d'installation et de déclaration d'un module Liorian. Ce fichier décrit l'identité du module, sa compatibilité (plateformes, versions manager/API), ses permissions, ses prérequis fonctionnels (requirements/optionalRequirements) et ses dépendances runtime (dependencies/devDependencies). Il est la source de vérité des métadonnées techniques d'un module, consommée par le Module Store et l'outillage de distribution.",
+  "type": "object",
+  "default": {},
+  "examples": [
+    {
+      "schemaVersion": 1,
+      "id": "hello-world",
+      "domain": "mod.liorian.helloworld",
+      "key": "HELLO_WORLD",
+      "name": "Hello World",
+      "description": "Module d'exemple pour l'onboarding des développeurs",
+      "version": "1.0.0",
+      "icon": "WandSparklesIcon",
+      "type": "INTERNAL",
+      "entry": "index.tsx",
+      "uri": "/hello-world",
+      "publisher": {
+        "id": "liorian",
+        "name": "Liorian Workspace"
+      },
+      "platforms": {
+        "web": {"supported": true, "modes": ["web"]},
+        "desktop": {"supported": true, "modes": ["local-webview"], "os": ["windows", "macos", "linux"]},
+        "mobile": {"supported": true, "modes": ["local-webview"], "os": ["android"], "iosSupported": false}
+      },
+      "managerCompatibility": {"min": "0.17.1", "max": "0.17.x"},
+      "apiCompatibility": {"min": "0.27.0", "max": "0.27.x"},
+      "permissions": ["hello-world.read", "hello-world.write", "hello-world.manage"],
+      "apiScopes": ["hello-world.read", "hello-world.write"],
+      "capabilities": {
+        "needsNetwork": true,
+        "supportsOffline": false,
+        "requiresOrganization": true,
+        "requiresAuthenticatedUser": true
+      },
+      "isEnabled": true,
+      "isDefault": false,
+      "requirements": {
+        "organization": ">=1.0.0",
+        "identity": ">=1.0.0"
+      },
+      "optionalRequirements": {},
+      "dependencies": {
+        "@liorian/sdk": "workspace:*",
+        "react": "^19.0.0",
+        "react-dom": "^19.0.0"
+      },
+      "devDependencies": {
+        "@types/react": "^19.2.17",
+        "typescript": "^6.0.3"
+      },
+      "widgets": ["analytics"],
+      "routines": ["helloWorldAnalyticsRoutine"],
+      "providers": ["layout"]
+    }
+  ],
+  "required": [
+    "schemaVersion",
+    "id",
+    "domain",
+    "key",
+    "name",
+    "description",
+    "version",
+    "icon",
+    "type",
+    "entry",
+    "uri",
+    "publisher",
+    "platforms",
+    "managerCompatibility",
+    "apiCompatibility",
+    "permissions",
+    "apiScopes",
+    "capabilities",
+    "isEnabled",
+    "isDefault",
+    "requirements",
+    "optionalRequirements",
+    "dependencies",
+    "devDependencies"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "schemaVersion": {
+      "type": "integer",
+      "const": 1,
+      "default": 1,
+      "title": "Version de schéma",
+      "description": "Version du schéma de manifeste. Garantit la compatibilité ascendante de l'outillage de validation et de distribution. Doit rester à 1 tant que le schéma n'introduit pas de rupture."
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+      "minLength": 2,
+      "maxLength": 64,
+      "title": "Identifiant technique",
+      "description": "Identifiant court et unique du module (slug kebab-case, sans domaine). Correspond au dossier racine du module, au champ « id » du package.json et à la clé d'enregistrement dans le registre de modules.",
+      "examples": ["accounting", "project-management", "hello-world"]
+    },
+    "domain": {
+      "type": "string",
+      "pattern": "^mod\\.[a-z0-9]+(\\.[a-z0-9-]+)*$",
+      "minLength": 5,
+      "title": "Domaine / identifiant pleinement qualifié",
+      "description": "Identifiant de type reverse-DNS unique du module, préfixé par « mod. ». Utilisé comme `identifier` dans la déclaration (ModuleDeclarationInterface) et comme clé de synchronisation avec le backend.",
+      "examples": ["mod.liorian.accounting", "mod.liorian.pos-management"]
+    },
+    "key": {
+      "type": "string",
+      "pattern": "^[A-Z][A-Z0-9_]*$",
+      "minLength": 2,
+      "maxLength": 64,
+      "title": "Clé publique",
+      "description": "Clé lisible et stable du module (SCREAMING_SNAKE_CASE), utilisée pour les permissions, l'occultation des logs et comme identifiant secondaire dans le Module Store.",
+      "examples": ["ACCOUNTING", "POS_MANAGEMENT", "HELLO_WORLD"]
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80,
+      "title": "Nom d'affichage",
+      "description": "Nom du module tel qu'affiché dans la navigation, le Module Store et les tableaux de bord.",
+      "examples": ["Comptabilité", "Point de vente", "E-Commerce"]
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512,
+      "title": "Description",
+      "description": "Description du périmètre fonctionnel du module, utilisée dans la fiche produit du Module Store.",
+      "examples": ["Plan comptable, écritures, journaux et rapports financiers"]
+    },
+    "version": {
+      "$ref": "#/definitions/semver",
+      "title": "Version du module",
+      "description": "Version sémantique du module distribuée. Incrémentée selon les conventions SemVer (feat -> mineur, fix -> correctif, rupture -> majeure)."
+    },
+    "icon": {
+      "$ref": "#/definitions/icon-reference",
+      "title": "Icône",
+      "description": "Nom de l'icône utilisée pour représenter le module (clés `IconKey` du SDK, issues de lucide-react / remix / tabler)."
+    },
+    "logo": {
+      "oneOf": [
+        {"type": "string", "minLength": 1},
+        {"type": "null"}
+      ],
+      "title": "Logo",
+      "description": "Identifiant média ou URL du logo du module (affiché en priorité face à `icon` dans le Module Store)."
+    },
+    "banner": {
+      "oneOf": [
+        {"type": "string", "minLength": 1},
+        {"type": "null"}
+      ],
+      "title": "Bannière",
+      "description": "Identifiant média ou URL de la bannière produit (affichée en tête de fiche du Module Store)."
+    },
+    "type": {
+      "type": "string",
+      "enum": ["INTERNAL", "EXTERNAL"],
+      "title": "Type de module",
+      "description": "Nature du module : `INTERNAL` pour les modules livrés avec le socle dans le monorepo, `EXTERNAL` pour les modules distribués de manière indépendante et installables via le Module Store.",
+      "default": "INTERNAL"
+    },
+    "entry": {
+      "type": "string",
+      "pattern": "^[a-zA-Z0-9_./-]+\\.tsx?$",
+      "default": "index.tsx",
+      "title": "Point d'entrée",
+      "description": "Chemin relatif du fichier contenant l'export default de la `ModuleDeclarationInterface` du module.",
+      "examples": ["index.tsx"]
+    },
+    "uri": {
+      "type": "string",
+      "pattern": "^/",
+      "minLength": 1,
+      "title": "URL racine",
+      "description": "URL de base de la navigation du module (doit commencer par « / »). C'est la route mère sous laquelle le module déclare ses pages.",
+      "examples": ["/accounting", "/pos-management"]
+    },
+    "category": {
+      "type": "string",
+      "enum": ["ADMINISTRATION", "COMMERCIAL", "FINANCE", "OPERATIONS", "COMMUNICATION", "DATA", "AUTOMATION", "SYSTEM"],
+      "title": "Catégorie",
+      "description": "Catégorie du module utilisée pour le filtrage et le regroupement dans le Module Store (alignée sur l'enum `ModuleCategory` du SDK).",
+      "examples": ["FINANCE", "COMMERCIAL", "SYSTEM"]
+    },
+    "publisher": {
+      "$ref": "#/definitions/publisher",
+      "title": "Éditeur",
+      "description": "Identité de l'éditeur du module, affichée dans le Module Store et utilisée pour la vérification de signature."
+    },
+    "platforms": {
+      "$ref": "#/definitions/platforms",
+      "title": "Plateformes supportées",
+      "description": "Matrice de support du module par plateforme (web, desktop, mobile) et par modes d'exécution."
+    },
+    "managerCompatibility": {
+      "$ref": "#/definitions/version-range",
+      "title": "Compatibilité manager",
+      "description": "Plage de versions du manager (frontend liorian-socle) acceptées par le module. Hors de cette plage, le module est marqué `incompatible`."
+    },
+    "apiCompatibility": {
+      "$ref": "#/definitions/version-range",
+      "title": "Compatibilité API",
+      "description": "Plage de versions de l'API backend attendues par le module. Hors de cette plage, les appels de service peuvent ne pas être conformes."
+    },
+    "permissions": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/permission-code"
+      },
+      "minItems": 1,
+      "uniqueItems": true,
+      "title": "Permissions",
+      "description": "Liste des permissions demandées par le module (format `<module>.<action>`). Ces permissions sont exposées au moteur d'autorisation via le composant `PermissionActionBadge` / `permission.util`.",
+      "examples": [["accounting.read", "accounting.write", "accounting.manage"]]
+    },
+    "apiScopes": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/permission-code"
+      },
+      "minItems": 1,
+      "uniqueItems": true,
+      "title": "Scopes API",
+      "description": "Scopes OAuth/API recensés par le module, généralement un sous-ensemble des permissions demandées (lecture/écriture). Utilisés lors de la négociation des accès avec l'API backend.",
+      "examples": [["accounting.read", "accounting.write"]]
+    },
+    "capabilities": {
+      "$ref": "#/definitions/capabilities",
+      "title": "Capacités",
+      "description": "Déclaration des capacités techniques du module (réseau, hors-ligne, organisation requise, utilisateur authentifié, etc.)."
+    },
+    "isEnabled": {
+      "type": "boolean",
+      "default": true,
+      "title": "Activé par défaut",
+      "description": "État d'activation initial du module à l'installation. Peut être modifié par l'utilisateur depuis le Module Store."
+    },
+    "isDefault": {
+      "type": "boolean",
+      "default": false,
+      "title": "Module par défaut",
+      "description": "Si `true`, le module ne peut être ni désactivé ni déplacé (exemple : dashboard, compte, notifications)."
+    },
+    "requirements": {
+      "$ref": "#/definitions/module-version-map",
+      "title": "Prérequis fonctionnels",
+      "description": "Modules obligatoirement présents et en version suffisante pour que le module fonctionne. Clé : `id` du module requis ; valeur : plage de versions acceptées (comparateurs npm/SemVer).",
+      "examples": [{"organization": ">=1.0.0", "identity": ">=1.0.0"}]
+    },
+    "optionalRequirements": {
+      "$ref": "#/definitions/module-version-map",
+      "title": "Prérequis optionnels",
+      "description": "Modules optionnels dont le module enrichit le comportement s'ils sont présents (intégrations facultatives). La valeur `{}` indique aucun prérequis optionnel.",
+      "examples": [{"messenger": ">=1.0.0"}]
+    },
+    "dependencies": {
+      "$ref": "#/definitions/dependency-map",
+      "title": "Dépendances npm",
+      "description": "Dépendances de packages npm nécessaires à l'exécution du module (nom de package -> plage de versions ou `workspace:*` pour les packages du monorepo).",
+      "examples": [{"@liorian/sdk": "workspace:*", "@tanstack/react-query": "^5.101.2"}]
+    },
+    "devDependencies": {
+      "$ref": "#/definitions/dependency-map",
+      "title": "Dépendances de développement",
+      "description": "Dépendances npm nécessaires uniquement au développement et à la compilation du module (types, toolchain).",
+      "examples": [{"typescript": "^6.0.3", "@types/react": "^19.2.17"}]
+    },
+    "widgets": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-zA-Z0-9]*$"
+      },
+      "uniqueItems": true,
+      "default": [],
+      "title": "Widgets",
+      "description": "Clés des widgets de dashboard fournis par le module (ex. : `analytics`, `recentOrders`, `topProducts`), référencées dans la propriété `widgets` de la déclaration React.",
+      "examples": [["analytics"], ["analytics", "recentOrders", "topProducts"]]
+    },
+    "routines": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-zA-Z][a-zA-Z0-9]*$"
+      },
+      "uniqueItems": true,
+      "default": [],
+      "title": "Routines",
+      "description": "Routines temps réel (rafraîchissement, synchronisation, notifications push) instanciées et déclenchées par le module. Clés : noms exportés des singletons `Routine`.",
+      "examples": [["helloWorldAnalyticsRoutine"], ["storeSyncRoutine"]]
+    },
+    "providers": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-zA-Z0-9]*$"
+      },
+      "uniqueItems": true,
+      "default": [],
+      "title": "Providers de layout",
+      "description": "Points d'injection de providers rendus par le socle (ex. : `layout` pour personnaliser le header de l'application). Clés référencées dans la propriété `providers` de la déclaration React.",
+      "examples": [["layout"]]
+    },
+    "configSettings": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/config-settings-field"
+      },
+      "uniqueItems": true,
+      "title": "Paramètres configurables",
+      "description": "Champs de configuration du module affichés dans sa fiche du Module Store et persistés par organisation (préférences). Aligné sur `ModuleConfigSettingsFieldInterface` du SDK.",
+      "examples": [
+        [
+          {
+            "key": "webhookUrl",
+            "label": "URL du webhook",
+            "type": "URL",
+            "required": false,
+            "placeholder": "https://example.com/hook"
+          }
+        ]
+      ]
+    },
+    "menu": {
+      "$ref": "#/definitions/menu",
+      "title": "Menu de navigation",
+      "description": "Déclaration des éléments de menu du module injectés dans le menu de démarrage (start menu). Les entrées purement programmatiques (`action`) restent dans la déclaration React et ne sont pas représentables en JSON."
+    }
+  },
+  "definitions": {
+    "semver": {
+      "type": "string",
+      "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$",
+      "title": "Version sémantique (SemVer)",
+      "description": "Version au format `majeure.mineure.correctif`, avec pré-version (prerelease) et métadonnées de build optionnelles.",
+      "examples": ["1.0.0", "0.27.1", "2.0.0-beta.1"]
+    },
+    "semver-range": {
+      "oneOf": [
+        {
+          "type": "string",
+          "pattern": "^(?:\\^|~|=|>=|<=|>|<)?[Vv]?(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?(\\s+(?:\\^|~|=|>=|<=|>|<)?[Vv]?(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*))?$"
+        },
+        {
+          "type": "string",
+          "pattern": "^(?:\\^|~|=|>=|<=|>|<)?[Vv]?(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(?:[xX*])$"
+        },
+        {
+          "type": "string",
+          "pattern": "^(?:\\^|~|=|>=|<=|>|<)?[Vv]?(0|[1-9]\\d*)\\.(?:[xX*])$"
+        },
+        {
+          "type": "string",
+          "pattern": "^(?:\\^|~|=|>=|<=|>|<)?[Vv]?(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$"
+        },
+        {
+          "type": "string",
+          "pattern": "^(\\*|x|X|latest|workspace:\\*)$"
+        }
+      ],
+      "title": "Plage de versions (npm/SemVer)",
+      "description": "Plage de versions acceptées au format des comparateurs npm : exacte (`1.2.3`), caret (`^1.2.3`), tilde (`~1.2.3`), comparateurs (`>=1.0.0`), intervalles (`>=1.0.0 <2.0.0`), plages partielles et jokers (`0.17.x`, `0.x`, `*`, `latest`, `workspace:*`).",
+      "examples": ["^1.2.3", ">=1.0.0", ">=1.0.0 <2.0.0", "0.17.x", "workspace:*"]
+    },
+    "version-range": {
+      "type": "object",
+      "required": ["min"],
+      "properties": {
+        "min": {
+          "$ref": "#/definitions/semver-range",
+          "title": "Version minimale acceptée",
+          "description": "Borne basse de compatibilité."
+        },
+        "max": {
+          "$ref": "#/definitions/semver-range",
+          "title": "Version maximale acceptée",
+          "description": "Borne haute de compatibilité (ex. plage `0.17.x`)."
+        },
+        "strict": {
+          "type": "boolean",
+          "default": false,
+          "title": "Échec strict",
+          "description": "Si `true`, une version hors plage rend le module inutilisable (blocage dur). Si `false`, un avertissement est émis."
+        }
+      },
+      "additionalProperties": false,
+      "title": "Plage de compatibilité",
+      "description": "Contrainte de compatibilité avec le manager (`managerCompatibility`) ou l'API (`apiCompatibility`) : borne minimale requise, borne maximale et sévérité.",
+      "examples": [{"min": "0.17.1", "max": "0.17.x"}]
+    },
+    "module-version-map": {
+      "type": "object",
+      "propertyNames": {
+        "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+      },
+      "patternProperties": {
+        "^[a-z0-9]+(-[a-z0-9]+)*$": {
+          "$ref": "#/definitions/semver-range"
+        }
+      },
+      "additionalProperties": false,
+      "title": "Carte module -> version",
+      "description": "Association d'identifiants de modules (`requirements` / `optionalRequirements`) à des plages de versions acceptées.",
+      "examples": [{"organization": ">=1.0.0", "media-library": ">=1.0.0"}]
+    },
+    "dependency-map": {
+      "type": "object",
+      "propertyNames": {
+        "pattern": "^(?:@[a-z0-9-~][a-z0-9-._~]*\\/)?[a-z0-9-~][a-z0-9-._~]*$"
+      },
+      "patternProperties": {
+        "^(?:@[a-z0-9-~][a-z0-9-._~]*\\/)?[a-z0-9-~][a-z0-9-._~]*$": {
+          "$ref": "#/definitions/semver-range"
+        }
+      },
+      "additionalProperties": false,
+      "title": "Carte package npm -> version",
+      "description": "Association de noms de packages npm (avec ou sans scope `@scope/package`) à des plages de versions acceptées.",
+      "examples": [{"@liorian/sdk": "workspace:*", "react": "^19.0.0"}]
+    },
+    "publisher": {
+      "type": "object",
+      "required": ["id", "name"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+([-_][a-z0-9]+)*$",
+          "title": "Identifiant de l'éditeur",
+          "description": "Identifiant technique de l'éditeur (ex. `liorian`)."
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "title": "Nom de l'éditeur",
+          "description": "Nom affiché de l'éditeur (ex. `Liorian Workspace`)."
+        },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "title": "Site de l'éditeur",
+          "description": "URL du site officiel de l'éditeur."
+        },
+        "email": {
+          "type": "string",
+          "format": "email",
+          "title": "Contact",
+          "description": "Adresse de contact du support."
+        },
+        "description": {
+          "type": "string",
+          "maxLength": 256,
+          "title": "Description",
+          "description": "Courte présentation de l'éditeur."
+        },
+        "avatar": {
+          "type": "string",
+          "format": "uri",
+          "title": "Avatar",
+          "description": "URL de l'avatar logo de l'éditeur."
+        }
+      },
+      "additionalProperties": false,
+      "title": "Éditeur",
+      "description": "Identité de l'entité publiant le module.",
+      "examples": [{"id": "liorian", "name": "Liorian Workspace"}]
+    },
+    "platforms": {
+      "type": "object",
+      "required": ["web", "desktop", "mobile"],
+      "properties": {
+        "web": {
+          "$ref": "#/definitions/platform-support",
+          "title": "Support web",
+          "description": "Support du module dans le navigateur / client web."
+        },
+        "desktop": {
+          "$ref": "#/definitions/platform-support",
+          "title": "Support desktop",
+          "description": "Support du module dans le client desktop (Tauri)."
+        },
+        "mobile": {
+          "$ref": "#/definitions/platform-support",
+          "title": "Support mobile",
+          "description": "Support du module dans le client mobile (Android/iOS)."
+        }
+      },
+      "additionalProperties": false,
+      "title": "Matrice de plateformes",
+      "description": "Déclaration du support par plateforme. Chaque plateforme fournit un objet `platform-support` (supporté ou non, modes d'exécution et systèmes d'exploitation).",
+      "examples": [
+        {
+          "web": {"supported": true, "modes": ["web"]},
+          "desktop": {"supported": true, "modes": ["local-webview"], "os": ["windows", "macos", "linux"]},
+          "mobile": {"supported": false, "modes": [], "os": []}
+        }
+      ]
+    },
+    "platform-support": {
+      "type": "object",
+      "required": ["supported"],
+      "properties": {
+        "supported": {
+          "type": "boolean",
+          "title": "Supporté",
+          "description": "Indique si le module est disponible sur cette plateforme."
+        },
+        "modes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "uniqueItems": true,
+          "title": "Modes d'exécution",
+          "description": "Modes d'exécution supportés (ex. `web`, `pwa`, `local-webview`). Requis si `supported` est `true`.",
+          "examples": [["web"], ["local-webview"]]
+        },
+        "os": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["windows", "macos", "linux", "android", "ios"]
+          },
+          "uniqueItems": true,
+          "title": "Systèmes d'exploitation",
+          "description": "Systèmes d'exploitation supportés (pertinent pour desktop/mobile).",
+          "examples": [["windows", "macos", "linux"]]
+        },
+        "iosSupported": {
+          "type": "boolean",
+          "title": "Support iOS",
+          "description": "Indique si iOS est supporté sur la plateforme mobile (obsolète si `os` inclut déjà `ios`)."
+        },
+        "minOsVersion": {
+          "type": "string",
+          "title": "Version OS minimale",
+          "description": "Version minimale du système d'exploitation requise (ex. `14.0`)."
+        }
+      },
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "supported": {"const": true}
+            }
+          },
+          "then": {
+            "properties": {
+              "modes": {
+                "minItems": 1
+              }
+            }
+          }
+        }
+      ],
+      "title": "Support de plateforme",
+      "description": "Définition du support d'un module sur une plateforme donnée."
+    },
+    "capabilities": {
+      "type": "object",
+      "properties": {
+        "needsNetwork": {
+          "type": "boolean",
+          "default": true,
+          "title": "Réseau requis",
+          "description": "Si `true`, le module requiert une connexion réseau pour fonctionner (appels API)."
+        },
+        "supportsOffline": {
+          "type": "boolean",
+          "default": false,
+          "title": "Mode hors-ligne",
+          "description": "Si `true`, le module conserve un fonctionnement dégradé hors connexion (cache local, file d'attente)."
+        },
+        "requiresOrganization": {
+          "type": "boolean",
+          "default": true,
+          "title": "Organisation requise",
+          "description": "Si `true`, le module exige une organisation active (le Module Guard bloque sans organisation)."
+        },
+        "requiresAuthenticatedUser": {
+          "type": "boolean",
+          "default": true,
+          "title": "Utilisateur authentifié requis",
+          "description": "Si `true`, le module exige une session utilisateur authentifiée."
+        },
+        "requiresAdmin": {
+          "type": "boolean",
+          "default": false,
+          "title": "Administrateur requis",
+          "description": "Si `true`, seules les sessions avec le rôle administrateur peuvent accéder au module."
+        },
+        "supportsRealtime": {
+          "type": "boolean",
+          "default": false,
+          "title": "Temps réel",
+          "description": "Si `true`, le module s'appuie sur des routines et/ou événements temps réel (push, websocket)."
+        },
+        "processesLocalData": {
+          "type": "boolean",
+          "default": false,
+          "title": "Traitement local des données",
+          "description": "Si `true`, le module traite des données sur l'appareil (chiffrement local, médias locaux)."
+        }
+      },
+      "additionalProperties": true,
+      "title": "Capacités techniques",
+      "description": "Déclaration des capacités techniques du module. Les drapeaux inconnus restent autorisés pour préserver l'extensibilité.",
+      "examples": [
+        {
+          "needsNetwork": true,
+          "supportsOffline": false,
+          "requiresOrganization": true,
+          "requiresAuthenticatedUser": true
+        }
+      ]
+    },
+    "permission-code": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+([-_][a-z0-9]+)*(\\.[a-z0-9]+([-_][a-z0-9]+)*)+$",
+      "minLength": 3,
+      "maxLength": 64,
+      "title": "Code de permission / scope",
+      "description": "Code hiérarchique au format `<module>.<action>` (ex. `accounting.write`, `project_management.manage`). L'action suit les conventions : `read`, `write`, `manage`, `delete`, `create`, `update`, `list`, `execute`.",
+      "examples": ["accounting.read", "project_management.manage", "hello-world.write"]
+    },
+    "icon-reference": {
+      "type": "string",
+      "pattern": "^[A-Z][A-Za-z0-9]*$",
+      "minLength": 1,
+      "maxLength": 64,
+      "title": "Référence d'icône",
+      "description": "Nom d'une clé `IconKey` du SDK (icônes lucide-react / remix / tabler). Utilisé par le rendu dynamique (`DynamicIcon`).",
+      "examples": ["CalculatorIcon", "PackageIcon", "CalendarDays"]
+    },
+    "menu": {
+      "type": "object",
+      "required": ["items"],
+      "properties": {
+        "items": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/menu-item"
+          },
+          "minItems": 1,
+          "title": "Éléments de menu",
+          "description": "Liste des éléments de premier niveau du menu du module."
+        },
+        "dropdown": {
+          "type": "string",
+          "enum": ["default", "mega", "mini"],
+          "default": "default",
+          "title": "Type de liste déroulante",
+          "description": "Style de menu déroulant appliqué au groupe (liste simple, méga-menu ou mini-menu)."
+        }
+      },
+      "additionalProperties": false,
+      "title": "Menu de navigation",
+      "description": "Déclaration sérialisable du menu de navigation du module (entrées à URL). Les actions programmatiques restent définies dans la déclaration React."
+    },
+    "menu-item": {
+      "type": "object",
+      "required": ["label"],
+      "properties": {
+        "label": {
+          "type": "string",
+          "minLength": 1,
+          "title": "Libellé",
+          "description": "Texte affiché de l'entrée de menu."
+        },
+        "description": {
+          "type": "string",
+          "title": "Description",
+          "description": "Description courte affichée sous le libellé (méga-menu)."
+        },
+        "icon": {
+          "$ref": "#/definitions/icon-reference",
+          "title": "Icône",
+          "description": "Icône de l'entrée de menu."
+        },
+        "url": {
+          "type": "string",
+          "pattern": "^/",
+          "title": "URL de destination",
+          "description": "Route interne ciblée par l'entrée de menu."
+        },
+        "target": {
+          "type": "string",
+          "enum": ["_self", "_blank", "_parent", "_top"],
+          "default": "_self",
+          "title": "Cible d'ouverture",
+          "description": "Cible d'ouverture du lien."
+        },
+        "separator": {
+          "type": "boolean",
+          "const": true,
+          "title": "Séparateur",
+          "description": "Si présent à `true`, l'entrée est un simple séparateur visuel (aucun autre champ requis)."
+        },
+        "keywords": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "uniqueItems": true,
+          "title": "Mots-clés de recherche",
+          "description": "Termes d'indexation pour la recherche dans le menu de démarrage."
+        },
+        "items": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/menu-item"
+          },
+          "title": "Sous-menu",
+          "description": "Sous-entrées de menu (hiérarchie imbriquée)."
+        }
+      },
+      "additionalProperties": false,
+      "anyOf": [
+        {"required": ["url"]},
+        {"required": ["items"]},
+        {"required": ["separator"]}
+      ],
+      "title": "Entrée de menu",
+      "description": "Élément de menu sérialisable : soit un lien (`url`), soit un sous-menu (`items`), soit un séparateur (`separator`)."
+    },
+    "config-settings-field": {
+      "type": "object",
+      "required": ["key", "label"],
+      "properties": {
+        "key": {
+          "type": "string",
+          "pattern": "^[a-z][a-zA-Z0-9_]*$",
+          "title": "Clé de configuration",
+          "description": "Clé technique du paramètre (persistée par organisation dans les préférences)."
+        },
+        "label": {
+          "type": "string",
+          "minLength": 1,
+          "title": "Libellé",
+          "description": "Libellé affiché du champ."
+        },
+        "description": {
+          "type": "string",
+          "title": "Description",
+          "description": "Texte d'aide affiché sous le champ."
+        },
+        "placeholder": {
+          "type": "string",
+          "title": "Placeholder",
+          "description": "Texte indicatif affiché dans le champ vide."
+        },
+        "type": {
+          "type": "string",
+          "enum": ["TEXT", "NUMBER", "EMAIL", "PASSWORD", "URL", "TEL", "SELECT", "TOGGLE"],
+          "default": "TEXT",
+          "title": "Type de champ",
+          "description": "Type de contrôle de saisie (aligné sur `ModuleConfigSettingsFieldType`)."
+        },
+        "required": {
+          "type": "boolean",
+          "default": false,
+          "title": "Obligatoire",
+          "description": "Si `true`, la valeur doit être fournie pour activer le module."
+        },
+        "defaultValue": {
+          "type": "string",
+          "title": "Valeur par défaut",
+          "description": "Valeur proposée par défaut avant toute saisie."
+        },
+        "options": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["label", "value"],
+            "properties": {
+              "label": {
+                "type": "string",
+                "title": "Libellé",
+                "description": "Texte affiché de l'option."
+              },
+              "value": {
+                "type": "string",
+                "title": "Valeur",
+                "description": "Valeur technique de l'option."
+              }
+            },
+            "additionalProperties": false
+          },
+          "uniqueItems": true,
+          "title": "Options",
+          "description": "Options de sélection (requis lorsque `type` vaut `SELECT`)."
+        }
+      },
+      "additionalProperties": false,
+      "title": "Champ de configuration",
+      "description": "Définition d'un paramètre configurable du module, affiché dans la fiche du Module Store et persisté par organisation.",
+      "examples": [
+        {
+          "key": "webhookUrl",
+          "label": "URL du webhook",
+          "type": "URL",
+          "required": false,
+          "placeholder": "https://example.com/hook"
+        }
+      ]
+    }
+  }
+}