Sanity Studio Configuration

Documentation technique

Type de ressource : Configuration Sanity Studio (Rôles / Permissions / Plugins)
Fichier source : apps/studio/sanity.config.ts
Statut : Actif

1. Vue d’ensemble

1.1. Description

Configuration principale du Sanity Studio pour le projet PP. Définit les plugins, les schémas enregistrés, et la configuration du mode preview pour les documents non publiés.

1.2. Objectif

Interface d’administration pour la gestion du contenu Sanity
Support du mode preview pour les documents en draft
Configuration des plugins structureTool et visionTool
Génération automatique des URLs de preview selon le type de document

1.3. Périmètre concerné

Environnements : Development, Preview, Production
Utilisateurs concernés : Administrators, Editors, Contributors (configuration Sanity Dashboard)
Types de documents impactés : post, author, category, amn, submission, blockContent

2. Architecture et flux

2.1. Diagramme de flux

[Utilisateur Sanity]
     │  (authentification OAuth)
     ▼
[Sanity Studio]
     │  • Vérification du rôle
     │  • Application des permissions
     │  • Affichage de l'interface adaptée
     ▼
[Actions autorisées / restreintes]

2.2. Composants impliqués

Composant	Rôle	Couche
Sanity Studio	Interface d’édition	L1 (CMS)
Configuration preview	Génération URLs preview	L1 (Configuration)
structureTool	Organisation du desk	L1 (Plugin)
visionTool	Éditeur GROQ	L1 (Plugin)

3. Configuration

3.1. Variables d’environnement requises

Variable	Description	Obligatoire	Valeur par défaut
`SANITY_STUDIO_PROJECT_ID`	ID du projet Sanity	✅	-
`SANITY_STUDIO_DATASET`	Nom du dataset (ex: `development`)	✅	`development`
`SANITY_STUDIO_PREVIEW_URL`	URL du site pour prévisualisation	❌	`http://localhost:4321` (local)
`SANITY_STUDIO_PREVIEW_SECRET`	Secret pour validation preview	✅	-

3.2. Configuration des rôles et permissions

3.2.1. Matrice des rôles

Rôle	Droits principaux	Public cible	Accès Studio
Administrator	Accès total (schémas, settings, tous les documents, gestion des utilisateurs)	Équipe Architecture / Tech Lead	✅ Complet
Editor	Création, modification et publication de tous les contenus	Équipe Marketing / Contenu	✅ Complet
Contributor	Création et modification de contenus, sans droit de publication	Rédacteurs externes ou juniors	✅ Complet
Viewer	Lecture seule	Stakeholders / relecture	✅ Lecture seule

3.2.2. Matrice des permissions par type de document

Type de document	Administrator	Editor	Contributor	Viewer
`post` (Article blog)	✅ CRUD + Publish	✅ CRUD + Publish	✅ Create + Update	✅ Read
`author`	✅ CRUD	✅ CRUD	❌	✅ Read
`category`	✅ CRUD	✅ CRUD	❌	✅ Read
`amn` (Message singleton)	✅ CRUD + Publish	✅ CRUD + Publish	✅ Create + Update	✅ Read
`submission` (Formulaire)	✅ CRUD	✅ CRUD	❌	✅ Read
`blockContent` (Utilitaire)	✅ CRUD	❌	❌	❌

3.2.3. Permissions granulaires

Non implémenté - permissions gérées via Sanity Dashboard uniquement.

3.3. Configuration de l’authentification

3.3.1. Providers OAuth activés

Provider	Configuration	Obligatoire
Sanity OAuth	Default Sanity OAuth	✅
Google OAuth	Non configuré	❌
GitHub OAuth	Non configuré	❌
Email/Password	Non configuré	❌

3.3.2. Règles d’accès

✅ Authentification obligatoire pour tous les utilisateurs
✅ Invitation des utilisateurs via Sanity Dashboard (Administrator uniquement)
✅ Révocation d’accès immédiate possible depuis le Dashboard

4. Structure du Desk

4.1. Organisation des documents

Non implémenté - utilisation de la structure par défaut de structureTool.

4.2. Vues personnalisées

Non implémenté - utilisation des vues par défaut.

5. Plugins et extensions

5.1. Plugins installés

Plugin	Rôle	Version	Obligatoire
`@sanity/structure`	Organisation du desk	Latest	✅
`@sanity/vision`	Éditeur GROQ pour tester les requêtes	Latest	❌

5.2. Configuration des plugins

import {structureTool} from 'sanity/structure'
import {visionTool} from '@sanity/vision'

export default defineConfig({
  plugins: [structureTool(), visionTool()],
})

6. Sécurité

6.1. Mécanismes de sécurité

Mécanisme	Implémentation	Rationale
Preview Secret	Validation côté Astro via `SANITY_PREVIEW_SECRET`	Empêche l’accès non autorisé aux drafts
Variables scoped	Préfixe `SANITY_STUDIO_` pour exposition contrôlée	Limite l’exposition des secrets côté client
Dataset separation	`development` vs `production`	Isolement des environnements

6.2. Règles de sécurité

✅ Les Administrators sont les seuls à pouvoir modifier les schémas
✅ Les tokens d’API ne sont JAMAIS exposés dans le Studio
✅ Le preview secret est partagé entre Studio et Astro
✅ Les variables sans préfixe SANITY_STUDIO_ restent côté serveur/CLI uniquement

6.3. Gestion des tokens API

Token	Permissions	Généré par	Stockage
`SANITY_API_READ_TOKEN`	Lecture des drafts	Administrator	.env (non versionné)
`SANITY_API_WRITE_TOKEN`	Écriture (mutations)	Administrator	.env (non versionné)

7. Workflow éditorial

7.1. Cycle de vie d’un document

[Création] → [Draft] → [Relecture] → [Publication] → [Archivé]
     │           │           │              │            │
     ▼           ▼           ▼              ▼            ▼
 Contributor  Contributor  Editor/Viewer   Public     Administrator

7.2. Bonnes pratiques éditoriales

✅ Utiliser le mode Preview avant publication
✅ Vérifier le rendu responsive (mobile, tablet, desktop)
✅ Archiver les contenus obsolètes plutôt que les supprimer

7.3. Processus de validation

Étape	Responsable	Action
1. Rédaction	Contributor	Création du contenu en draft
2. Relecture	Editor / Viewer	Validation du contenu
3. Publication	Editor / Administrator	Publication finale
4. Vérification	Editor	Vérification post-publication (preview + live)

8. Débogage et troubleshooting

8.1. Problèmes courants

Symptôme	Cause probable	Solution
Preview ne fonctionne pas	Secret non configuré	Vérifier `SANITY_STUDIO_PREVIEW_SECRET`
Build échoue	Variables manquantes	Vérifier `.env` à la racine
Schémas non visibles	Import incorrect dans `schemaTypes/index.ts`	Vérifier les exports
Déploiement échoue	Configuration Wrangler incorrecte	Vérifier `wrangler.toml`

8.2. Logs et monitoring

Côté Sanity :

Sanity Dashboard → Settings → Activity → Audit logs
Vérifier les actions des utilisateurs (création, modification, publication)

Côté application :

Logs des erreurs de build (CI/CD)
Logs de preview (console du navigateur)

8.3. Tests manuels

# Test local
task dev:studio
# Ouvrir http://localhost:3333

# Test preview
# 1. Créer/éditer un document dans le Studio
# 2. Cliquer sur "Open Preview"
# 3. Vérifier que la page Astro s'ouvre avec le contenu en draft

# Test build
task build:studio

9. Bonnes pratiques

9.1. Pour les Administrators

✅ Configurer les rôles et permissions avant d’inviter des utilisateurs
✅ Documenter les changements de configuration dans ce fichier
✅ Révoquer les accès des utilisateurs partis
✅ Rotation régulière des tokens API (tous les 90 jours)

9.2. Pour les Editors

✅ Valider les contenus avant publication
✅ Utiliser le mode Preview systématiquement
✅ Archiver les contenus obsolètes

9.3. Pour les Contributors

✅ Créer des drafts complets (tous les champs obligatoires remplis)
✅ Ne pas publier (demander à un Editor)
✅ Utiliser le mode Preview pour vérifier le rendu

9.4. Considérations de performance

⚠️ Le Studio peut être lent avec beaucoup de documents (> 10 000)
⚠️ Les images lourdes peuvent ralentir l’édition
✅ Optimiser les images avant upload (max 2 MB recommandé)

10. Évolutions et roadmap

10.1. Améliorations planifiées

Intégration de plugins supplémentaires (ex: media assets)
Customisation de la structure du Studio
Configuration des rôles et permissions granulaires
Intégration avec le workflow de publication

10.2. Limitations connues

❌ Le preview nécessite une configuration manuelle des URLs
❌ Les tokens d’API ne peuvent pas être utilisés directement dans le Studio
❌ La customisation visuelle est limitée sans plugins spécifiques

11. Ressources liées

Documentation Sanity : Studio Configuration
Documentation Sanity : Studio Environment Variables
Schémas associés : Tous les schémas dans apps/studio/schemaTypes/
Frontend associé : apps/web/src/pages/api/preview.ts
Configuration Cloudflare : apps/studio/wrangler.toml

12. Historique des modifications

Date	Version	Description	Auteur
2026-09-15	1.0	Création initiale de la documentation	Devin