Category

Documentation technique

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

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