Category

Type de ressource : Schéma Sanity (Document)
Fichier source : apps/studio/schemaTypes/category.ts
Statut : Actif
Slice : 2 (Blog)
Version : 1.0

---

1. Vue d’ensemble (DOC)

1.1. Description

Schéma pour les catégories d’articles de blog. Contient le titre et une description de la catégorie.

1.2. Objectif

• Modéliser les catégories pour organiser les articles de blog
• Permettre la classification des articles par thématique
• Faciliter la navigation et le filtrage des articles
• Supporter une description pour chaque catégorie

1.3. Cas d’usage

• Classification des articles de blog par thématique
• Navigation par catégorie sur le blog
• Filtrage des articles par catégorie
• Organisation du contenu du blog

1.4. Relations avec d’autres schémas

Relation	Schéma	Type	Description
Utilisé par	post	Référence	Les articles référencent les catégories via le champ categories
Dépend de	Aucun	-	Schéma indépendant

---

2. Structure des données (DOC)

2.1. Champs principaux

Nom du champ	Type	Obligatoire	Description	Validation
title	string	✅	Titre de la catégorie	Aucune
description	text	❌	Description de la catégorie	Aucune

2.2. Champs SEO

Aucun champ SEO spécifique n’est implémenté dans ce schéma.

2.3. Champs de contenu riche

Aucun champ de contenu riche n’est implémenté dans ce schéma.

---

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

3.1. Inputs (création/modification)

Champ	Type	Validation	Description
title	string	Aucune	Titre de la catégorie
description	text	Aucune	Description de la catégorie (optionnel)

3.2. Outputs (structure du document)

Champ	Type	Description
_id	string	ID unique du document
_type	string	Type du document (category)
_createdAt	string	Date de création (généré par Sanity)
_updatedAt	string	Date de dernière modification (généré par Sanity)
title	string	Titre de la catégorie
description	string	Description de la catégorie (optionnel)

3.3. États du document

Non implémenté - ce schéma n’a pas de champ status. Les documents sont toujours considérés comme publiés.

---

4. Implémentation (CODE)

4.1. Code du schéma

apps/studio/schemaTypes/category.ts

import {defineField, defineType} from 'sanity'

export default defineType({
  name: 'category',
  title: 'Category',
  type: 'document',
  fields: [
    defineField({
      name: 'title',
      title: 'Title',
      type: 'string',
    }),
    defineField({
      name: 'description',
      title: 'Description',
      type: 'text',
    }),
  ],
})

4.2. Requêtes GROQ associées

Requête principale (listing)

*[_type == "category"] {
  _id,
  title,
  description
} | order(title asc)

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

*[_type == "category" && _id == $categoryId][0] {
  _id,
  title,
  description
}

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

Non implémenté - sanity-typegen n’est pas configuré dans le projet actuel.

// Types à implémenter manuellement si nécessaire
export type Category = {
  _id: string;
  _type: 'category';
  title: string;
  description?: string;
};

---

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
Description optionnelle	Créer un document sans description	Document créé avec succès

5.2. Tests d’intégration

Scénario	Dépendances	Description	Résultat attendu
Consommation Astro	Route Astro + Sanity API	Récupération des données via GROQ	Données récupérées et typées correctement
Référence depuis post	Schéma post + category	Créer un article avec cette catégorie	Référence fonctionnelle
Filtrage par catégorie	Route blog avec filtre	Filtrer les articles par catégorie	Articles filtrés correctement

5.3. Tests E2E

Scénario	Parcours utilisateur	Description	Résultat attendu
Création → Association	Sanity Studio → Article	Créer une catégorie et l’associer à un article	Catégorie visible sur l’article
Modification → Propagation	Studio → Build → Site	Modifier la description de la catégorie	Modification visible sur tous les articles

---

6. Intégration (INTÉG)

6.1. Intégration avec les composants

Composant	Type	Rôle	Méthode d’intégration
Schéma post	L1	Référence vers les catégories	Champ categories de type array de references
Route Astro (blog/index.astro)	L2	Affichage des catégories	Requête GROQ avec jointure vers category

6.2. Points d’attention

• Ce schéma n’a pas de slug (utilise l’_id pour les références)
• Ce schéma est référencé par le schéma post via un champ array
• Les catégories peuvent être associées à plusieurs articles
• Un article peut avoir plusieurs catégories
• Pas de preview configuré (structure simple)

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 (à implémenter)
• Les références depuis post fonctionnent correctement

---

7. Sécurité

7.1. Mécanismes de sécurité

• ✅ Les permissions Sanity sont configurées par rôle
• ✅ Les références depuis post sont validées par Sanity

7.2. Validation des entrées

• ✅ Le champ title est obligatoire
• ✅ Les références depuis post pointent vers des documents existants

---

8. Performance et limites

8.1. Limites Sanity

Limite	Valeur	Stratégie d’optimisation
Taille du document	16 MB	Éviter les champs description 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 (à implémenter)
Catégorie non affichée dans article	Référence cassée	Vérifier que la catégorie existe et n’est pas supprimée

9.2. Commandes de debug

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

# Générer les types TypeScript (à implémenter)
npx sanity typegen generate

---

10. Bonnes pratiques

10.1. Architecture

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

10.2. Code

• ✅ Utiliser defineField pour chaque champ
• ✅ 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 (à implémenter)
• ✅ Tester les requêtes GROQ après modification

---

11. Évolutions et roadmap

11.1. Améliorations planifiées

• Implémentation de sanity-typegen pour la génération de types
• Ajout d’un champ slug pour les URLs de catégories
• Ajout de champs SEO pour les catégories
• Centralisation des requêtes GROQ dans un fichier dédié

11.2. Limitations connues

• ❌ Pas de support pour les drafts (pas de champ status)
• ❌ Pas de slug pour les URLs
• ❌ Pas de champs SEO spécifiques
• ❌ Types TypeScript non générés automatiquement

---

12. Ressources liées

• Documentation Sanity : Schema Types
• DAT L1 : §4 - Modélisation et Schémas des Données
• Schémas dépendants : Aucun (schéma indépendant)
• Schémas référençant : post
• Pages Astro consommatrices : apps/web/src/pages/blog/index.astro

---

13. Historique des modifications

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