Studio - Référence développeur

Studio est un module de Dodock qui construit et publie des applications Vue de façon visuelle. Cette page documente les commandes, hooks et procédures d'intégration pour les développeurs d'applications. Pour l'utilisation de l'éditeur, voir Studio.

Commandes bench

bench build-studio-app <app>

Compile une application Studio spécifique pour la production.

bench --site mon_site build-studio-app mon_app_studio

L'argument est le nom du document Studio App, pas celui de l'application Python. L'option --site est facultative si un site par défaut est défini. En cas d'échec, la commande affiche la référence du journal d'erreurs (Error Log) et se termine avec le code 1.

bench --site <site> watch-studio

Surveille les dossiers d'applications Studio exportées (<app>/studio/) et importe automatiquement les définitions JSON dans le site lorsque les fichiers changent sur le disque.

bench --site mon_site watch-studio

Cette commande est un processus dédié : elle n'est pas démarrée automatiquement par bench start.

Build de l'éditeur

L'éditeur Studio est une application Vite (studio/frontend/ dans le dépôt du framework). bench build le construit avec les assets de frappe. Un échec de ce build fait échouer bench build.

Hooks d'intégration

Studio s'intègre au framework via frappe/hooks.py :

Hook personnalisé : studio_app_boot

Les applications peuvent définir un hook studio_app_boot pour fournir des données au démarrage d'une application Studio publiée :

# hooks.py de votre application
studio_app_boot = {
    "mon_app_studio": "mon_app.studio.boot.get_boot_data"
}

La clé est le nom du document Studio App. La méthode est appelée sans argument. Elle retourne un dictionnaire, disponible sous boot dans l'application publiée. Si plusieurs applications déclarent la même clé, la dernière méthode déclarée est utilisée. Si la méthode lève une exception, l'erreur est enregistrée dans le journal des erreurs et boot est vide.

def get_boot_data():
    return {
        "api_base": frappe.utils.get_url(),
        "feature_flags": get_feature_flags(),
    }

Structure des applications exportées

Une application Studio exportée se trouve dans le dossier studio/ de votre application :

mon_app/
└── studio/
    └── mon_app_studio/
        ├── mon_app_studio.json      # Définition de l'application
        ├── studio_page/             # Un dossier par page
        │   └── accueil/
        │       ├── accueil.json     # Définition de la page
        │       └── accueil.ts       # Script de la page
        └── studio_components/       # Composants réutilisables
            └── mon_composant.json

Un dossier est reconnu comme application Studio lorsqu'il contient un fichier <nom_du_dossier>.json à sa racine. Le nom du dossier est le nom de l'application normalisé (mon-app devient mon_app). Pour une page exportée, le script est lu dans le fichier .ts : le champ script de la base reste vide.

Migration depuis l'application Studio autonome

Si votre site utilisait l'application Studio autonome (avant son intégration au framework), la migration est automatique lors de la mise à jour :

1. Mettez à jour Dokos et exécutez bench migrate
2. Le patch frappe.patches.v16_0.merge_studio_into_frappe effectue les opérations suivantes :
   • Transfère les enregistrements de patch de l'ancien module studio.studio.doctype.* vers frappe.studio.doctype.*
   • Réassigne le module « Studio » à l'application frappe
   • Retire studio de la liste des applications installées
   • Efface le cache et reconstruit la carte des modules
3. Une fois tous les sites du bench migrés, exécutez bench remove-app studio pour supprimer définitivement l'ancienne application

Les applications, pages et composants existants sont conservés ; seules les appartenances de module changent.

DocTypes Studio

Architecture

• Backend : frappe/studio/ contient les DocTypes, l'API Python, la synchronisation des fichiers JSON, le build et les fonctionnalités IA.
• Frontend éditeur : studio/frontend/ (à la racine du dépôt du framework) contient l'éditeur Vue (Vite), le renderer et le build par application. Il possède son propre lockfile.
• Rendu des applications publiées : les pages sont rendues côté serveur via StudioAppRenderer et servies comme des pages web.

Dépendances IA

Les fonctionnalités d'assistant IA nécessitent les dépendances Python suivantes dans l'environnement :

• litellm (appel aux modèles de langage)
• json_repair (réparation des réponses JSON des modèles)

Sécurité

• Sessions IA : chaque utilisateur ne peut accéder qu'à ses propres sessions et messages. Les sessions et messages ne sont pas créés depuis l'interface desk.
• Exécution IA : une session IA (une par page) traite une seule demande à la fois. La demande est exécutée en tâche de fond. Une deuxième demande sur la même session reçoit une réponse HTTP 429 (« Another AI request is still processing »).
• Clé API : la clé du fournisseur (OpenRouter) se saisit dans Studio Settings. Sans clé, l'assistant affiche une erreur.
• Fichiers : l'explorateur de fichiers de Studio (list_studio_files, read_studio_file, write_studio_file, delete_studio_file) ne fonctionne qu'en mode développeur. Il demande la permission de lecture (ou d'écriture) sur Studio App. Le chemin demandé est résolu, liens symboliques compris, et doit rester dans le dossier de l'application exportée. Seules les extensions .ts, .js, .vue, .json et .css sont acceptées : aucun fichier .py ne peut être lu ni écrit.
• Applications standard : une application marquée Is Standard ne peut être modifiée dans l'éditeur qu'en mode développeur.

Permissions

L'accès à Studio est contrôlé par les permissions sur les DocTypes Studio. Par défaut, les rôles System Manager et Studio User ont accès aux applications, pages et sessions IA. Seul System Manager a accès à Studio Settings.

Pour restreindre l'accès à Studio :

1. Allez dans Gestion des rôles
2. Modifiez les permissions du rôle concerné pour les DocTypes Studio App, Studio Page, Studio Component
3. Cochez ou décochez les droits de lecture, écriture, création et suppression selon les besoins