[Nom du Schéma]

Type de ressource : Schéma Sanity (Document / Object / Block)
Fichier source : sanity-studio/schemas/[filename].ts
Statut : [Actif / Déprécié / En développement]
Slice : [Numéro de la tranche verticale]
Version : 1.0

---

1. Vue d’ensemble (DOC)

1.1. Description

[Description concise du rôle de ce schéma dans l’architecture du site]

1.2. Objectif

• [Objectif principal : ce que le schéma permet de modéliser]
• [Bénéfice pour l’architecture ou les utilisateurs]

1.3. Cas d’usage

• [Cas d’usage principal]
• [Cas d’usage secondaire si applicable]

1.4. Relations avec d’autres schémas

Relation	Schéma	Type	Description
Dépend de	[Nom]	[Référence/Composition]	[Description]
Utilisé par	[Nom]	[Référence]	[Description]

---

2. Structure des données (DOC)

2.1. Champs principaux

Nom du champ	Type	Obligatoire	Description	Validation
fieldName	string	✅	[Description]	[Règles de validation]
slug	slug	✅	[Description]	source: 'title'
status	string	✅	[Description]	Options: draft, published, archived

2.2. Champs SEO (si applicable)

Nom du champ	Type	Obligatoire	Description	Fallback
seo.metaTitle	string	❌	Meta title pour SEO	title
seo.metaDescription	text	❌	Meta description	excerpt
seo.ogImage	image	❌	Image Open Graph	mainImage

2.3. Champs de contenu riche (si applicable)

Nom du champ	Type	Description
body	array	Contenu Portable Text (blocs + spans)
pageBuilder	array	Liste de blocs PageBuilder (hero, features, etc.)

---

3. Contrats d’Entrée/Sortie (SPEC)

3.1. Inputs (création/modification)

Champ	Type	Validation	Description
title	string	Rule.required()	Titre obligatoire
slug	slug	source: 'title'	Généré automatiquement depuis le titre

3.2. Outputs (structure du document)

Champ	Type	Description
_id	string	ID unique du document
_type	string	Type du document
_createdAt	string	Date de création
_updatedAt	string	Date de dernière modification

3.3. États du document

État	Description	Transition
draft	Document en brouillon	→ published
published	Document publié	→ archived
archived	Document archivé	→ published

---

4. Implémentation (CODE)

4.1. Code du schéma

sanity-studio/schemas/[filename].ts

import { defineField, defineType } from 'sanity';

export default defineType({
  name: '[schemaName]',
  title: '[Titre lisible]',
  type: 'document', // ou 'object', 'block'
  fields: [
    defineField({
      name: 'title',
      title: 'Titre',
      type: 'string',
      validation: (Rule) => Rule.required(),
    }),
    defineField({
      name: 'slug',
      title: 'Slug',
      type: 'slug',
      options: { source: 'title' },
      validation: (Rule) => Rule.required(),
    }),
    // ... autres champs
  ],
  preview: {
    select: {
      title: 'title',
      subtitle: 'publishedAt',
      media: 'mainImage',
    },
  },
});

4.2. Requêtes GROQ associées

Requête principale (listing)

*[_type == "[schemaName]" && status == "published"] {
  _id,
  title,
  slug,
  publishedAt,
  mainImage,
  excerpt
} | order(publishedAt desc)

Requête détaillée (page unitaire)

*[_type == "[schemaName]" && slug.current == $slug][0] {
  ...,
  author->{name, image},
  categories[]->{title, slug}
}

4.3. Types TypeScript (génération automatique)

// src/types/sanity.d.ts (généré via sanity-typegen)
export type [SchemaName] = {
  _id: string;
  _type: '[schemaName]';
  title: string;
  slug: { _type: 'slug'; current: string };
  publishedAt: string;
  status: 'draft' | 'published' | 'archived';
  mainImage?: ImageAsset;
  excerpt?: string;
  seo?: SeoObject;
};

---

5. Tests attendus (TEST)

5.1. Tests unitaires

Scénario	Description	Résultat attendu
Validation du titre	Créer un document sans titre	Erreur de validation
Génération du slug	Créer un document avec titre	Slug généré automatiquement
Publication	Changer le statut de draft à published	Document passe en published

5.2. Tests d’intégration

Scénario	Dépendances	Description	Résultat attendu
Consommation Astro	Route Astro	Récupération des données via GROQ	Données typées correctement
Indexation Pagefind	Build Astro	Indexation du contenu généré	Contenu indexé et searchable

5.3. Tests E2E

Scénario	Parcours utilisateur	Description	Résultat attendu
Création → Publication	Sanity Studio → Build → Site	Créer et publier un document	Document visible sur le site

---

6. Intégration (INTÉG)

6.1. Intégration avec les composants

Composant	Type	Rôle	Méthode d’intégration
Route Astro	L2	Rendu du contenu	Requête GROQ via getSanityClient()
Pagefind	L2	Indexation	Indexation du HTML généré
Webhook	L3	Déclenchement rebuild	Événement publish

6.2. Points d’attention

• Le schéma doit être compatible avec sanity-typegen
• Les requêtes GROQ doivent utiliser les projections explicites
• Le statut published doit être filtré en production

6.3. Vérification de cohérence

• Le schéma ne casse aucun schéma existant
• Les requêtes GROQ retournent les données attendues
• Les types TypeScript sont générés correctement
• Les tests E2E passent

---

7. Sécurité

7.1. Mécanismes de sécurité

• ✅ Les documents draft ne sont accessibles qu’en mode preview
• ✅ Les permissions Sanity sont configurées par rôle
• ✅ Les tokens API ont les permissions minimales nécessaires

7.2. Validation des entrées

• ✅ Les champs obligatoires sont validés côté Sanity
• ✅ Les slugs sont uniques et valides
• ✅ Les statuts suivent le cycle draft → published → archived

---

8. Performance et limites

8.1. Limites Sanity

Limite	Valeur	Stratégie d’optimisation
Taille du document	16 MB	Éviter les champs trop volumineux
Profondeur des références	10 niveaux	Limiter les références imbriquées

8.2. Optimisations appliquées

• ✅ Utilisation de projections GROQ pour réduire la taille des réponses
• ✅ Mise en cache CDN pour les requêtes en production

---

9. Débogage et troubleshooting

9.1. Problèmes courants

Symptôme	Cause probable	Solution
Schéma non visible dans Studio	Cache du navigateur	Vider le cache et rafraîchir
Types TypeScript incorrects	Schéma modifié sans régénération	Exécuter sanity typegen generate
Requête GROQ vide	Filtre incorrect	Vérifier la syntaxe GROQ

9.2. Commandes de debug

# Extraire le schéma depuis Sanity
npx sanity schema extract

# Générer les types TypeScript
npx sanity typegen generate

---

10. Bonnes pratiques

10.1. Architecture

• ✅ Toujours utiliser des types générés par sanity-typegen
• ✅ Centraliser les requêtes GROQ dans src/lib/queries.ts
• ✅ Documenter les champs et leurs validations

10.2. Code

• ✅ Utiliser defineField pour chaque champ
• ✅ Configurer le preview pour une meilleure UX dans Studio
• ✅ Utiliser des validations appropriées

10.3. Maintenance

• ✅ Mettre à jour ce fichier lors de toute modification du schéma
• ✅ Régénérer les types après modification
• ✅ Tester les requêtes GROQ après modification

---

11. Évolutions et roadmap

11.1. Améliorations planifiées

• [Évolution 1]
• [Évolution 2]

11.2. Limitations connues

• ❌ [Limitation 1]
• ❌ [Limitation 2]

---

12. Ressources liées

• Documentation Sanity : [Lien vers docs officielles]
• DAT L1 : §4 - Modélisation et Schémas des Données
• Schémas dépendants : [Liste]
• Pages Astro consommatrices : [Liste des fichiers .astro]

---

13. Historique des modifications

Date	Version	Description	Auteur
YYYY-MM-DD	1.0	Création initiale	[Nom]