curiositech/windags-skills

Développement de la Suite Admin & Développeur

Cette compétence vous aide à étendre le tableau de bord d'administration et à créer des outils internes en suivant les schémas établis.

POINTS DE DÉCISION

Quand ajouter un onglet vs Modifier un point d'accès vs Créer un nouvel outil

Ajout d'une nouvelle fonctionnalité d'administration :
├─ L'utilisateur a besoin d'une vue en lecture seule des données ?
│  ├─ Les données existent dans l'API actuelle ? → Modifier l'onglet existant
│  ├─ Nouveau type de données nécessaire ? → Ajouter un nouvel onglet + nouveau point d'accès
│  └─ Analyses complexes requises ? → Créer un onglet d'analyse dédié
│
├─ L'utilisateur doit modifier les données système ?
│  ├─ Opérations CRUD simples ? → Ajouter un onglet de gestion
│  ├─ Opérations par lots nécessaires ? → Créer un onglet de console d'exploitation
│  └─ Workflow en plusieurs étapes ? → Construire un composant assistant
│
├─ Outils internes pour développeurs ?
│  ├─ Inspection de code / documentation ? → Ajouter au portail /dev
│  ├─ Surveillance système ? → Ajouter à la console /ops
│  └─ Outils de support utilisateur ? → Ajouter au tableau de bord d'administration
│
└─ Fonctionnalité pour utilisateur externe ?
   → STOP : Utiliser plutôt la compétence `frontend-development`

Stratégie d'implémentation du contenu des onglets

Évaluation de la complexité de l'onglet :
├─ Affichage simple de statistiques (< 5 métriques) ?
│  → Utiliser le motif de grille StatCard
│
├─ Tableau de données avec filtrage ?
│  ├─ < 1000 lignes ? → Filtrage côté client
│  └─ > 1000 lignes ? → Pagination côté serveur + recherche
│
├─ Surveillance en temps réel ?
│  ├─ Mises à jour toutes les 30 secondes ou plus ? → Utiliser SWR avec intervalle de rafraîchissement
│  └─ Mises à jour toutes les 5 secondes ou moins ? → Utiliser une connexion WebSocket
│
└─ Contrôles interactifs ?
   ├─ Bascules / boutons simples ? → Actions en ligne
   └─ Formulaires complexes ? → Boîtes de dialogue modales + flux de confirmation

MODES DE DÉFAILLANCE

1. Spirale de mort des performances des requêtes de base de données

Symptôme : Le tableau de bord d'administration expire ou se charge lentement (>5 secondes) Détection : Surveiller les temps de réponse de /api/admin/* > 3s Correctif : Ajouter des index de base de données, implémenter la pagination, mettre en cache les statistiques agrégées

-- MAUVAIS : Parcours complet de la table
SELECT COUNT(*) FROM pageViews WHERE userId = ?

-- BON : Utiliser des plages de temps indexées
SELECT COUNT(*) FROM pageViews WHERE createdAt > NOW() - INTERVAL 24 HOUR

2. Cache obsolète montrant des données erronées

Symptôme : L'administrateur voit des métriques obsolètes qui ne correspondent pas à l'activité récente Détection : L'utilisateur signale que les statistiques ne changent pas après des actions connues Correctif : Implémenter l'invalidation du cache lors des mutations de données, ajouter des horodatages « Dernière mise à jour »

// Ajouter une rupture de cache aux mutations
await updateUserData(userId);
await revalidateTag('admin-stats'); // Vider le cache

3. Journalisation d'audit manquante

Symptôme : Les actions d'administration ne sont pas enregistrées dans la table auditLog Détection : Vérifier les entrées auditLog pour les actions d'administration au cours des 24 dernières heures Correctif : Ajouter des appels logAdminAction() à TOUS les points d'accès d'administration

// Requis dans chaque point d'accès d'administration
await logAdminAction(admin.id, AuditAction.USER_DATA_VIEW, 'users', userId);

4. Exposition de données en violation HIPAA

Symptôme : PHI visible dans les messages d'erreur, les journaux ou les vues agrégées Détection : L'erreur contient l'email/téléphone/données médicales de l'utilisateur Correctif : Nettoyer toutes les réponses d'erreur, utiliser des identifiants hachés dans les vues d'administration

// MAUVAIS : Expose l'email de l'utilisateur
{ error: "Utilisateur [email protected] introuvable" }

// BON : Utilise des identifiants anonymes
{ error: "ID utilisateur hash_123abc introuvable" }

5. Escalade de privilèges d'administration

Symptôme : Les utilisateurs réguliers peuvent accéder aux points d'accès d'administration Détection : Un utilisateur non administrateur reçoit des données d'administration au lieu d'une erreur 403 Correctif : Ajouter un contrôle requireAdmin() comme première ligne de chaque point d'accès d'administration

export async function GET(request: Request) {
  const admin = await requireAdmin(); // Doit être la PREMIÈRE ligne
  if (!admin) return Response.json({ error: 'Accès interdit' }, { status: 403 });
  // ... reste du gestionnaire
}

EXEMPLES CONCRETS

Ajout d'un onglet de surveillance de la santé de la production

Scénario : Ajouter une surveillance en temps réel de la santé de l'API avec des métriques de latence, des taux d'erreur et l'état des services.

1. Navigation des points de décision :

• L'utilisateur a besoin d'une surveillance en temps réel → Utiliser SWR avec un rafraîchissement de 30s
• Données système, pas données utilisateur → Ajouter au tableau de bord d'administration
• Nouveau type de données (métriques API) → Créer un nouvel onglet + point d'accès

2. Étapes d'implémentation :

Créer le point d'accès avec les schémas requis :

// src/app/api/admin/health/route.ts
export async function GET(request: Request) {
  const admin = await requireAdmin(); // Sécurité d'abord
  if (!admin) return Response.json({ error: 'Accès interdit' }, { status: 403 });
  
  const rateLimitResult = await rateLimiter.check(admin.id); // Limitation de débit
  if (!rateLimitResult.allowed) return Response.json({}, { status: 429 });
  
  await logAdminAction(admin.id, 'HEALTH_VIEW', 'metrics', null); // Audit
  
  const metrics = await getHealthMetrics(); // Récupération des données
  return Response.json(metrics);
}

Créer le composant d'onglet :

function ProductionHealthTab() {
  const { data: health, error } = useSWR('/api/admin/health', fetcher, {
    refreshInterval: 30000 // Mises à jour en temps réel
  });
  
  return (
    <div className="space-y-6">
      <div className="grid grid-cols-4 gap-4">
        <StatCard label="Disponibilité API" value="99.9%" status="good" />
        <StatCard label="Latence moyenne" value="45ms" trend="down" />
        <StatCard label="Taux d'erreur" value="0.1%" status="warning" />
        <StatCard label="Services actifs" value="12/12" status="good" />
      </div>
    </div>
  );
}

3. Différences entre expert et novice :

• Ce que le novice rate : Journalisation d'audit, limitation de débit, gestion des erreurs conforme HIPAA
• Ce que l'expert détecte : Stratégie d'invalidation du cache, configuration de la surveillance des performances, limites d'erreur appropriées

BARRIÈRES DE QUALITÉ

• Contrôle d'accès administrateur : le contrôle requireAdmin() réussit avec un administrateur, échoue avec un utilisateur régulier
• Limitation de débit : le point d'accès renvoie 429 lorsque la limite de débit est dépassée (60 req/min par défaut)
• Journalisation d'audit : l'action d'administration est enregistrée dans la table auditLog avec le type d'action correct
• Performance de référence : l'onglet se charge en <2 secondes avec un volume de données réaliste
• Conformité HIPAA : aucune PHI exposée dans les messages d'erreur ou les sorties de débogage
• Validation des données : les requêtes invalides renvoient des erreurs 400 appropriées avec des messages sécurisés
• Comportement du cache : les données sont mises à jour dans les 30 secondes suivant les modifications du backend
• Limites d'erreur : l'interface utilisateur gère correctement les échecs d'API sans planter
• Responsive mobile : la disposition de l'onglet fonctionne sur les écrans de taille tablette (768px+)
• Mises à jour en temps réel : l'actualisation automatique fonctionne sans fuite de mémoire pendant plus de 10 minutes

LIMITES D'UTILISATION

N'utilisez PAS cette compétence pour :

• Fonctionnalités destinées aux utilisateurs externes → Utiliser frontend-development à la place
• Flux d'authentification / de connexion → Utiliser auth-security à la place
• Modifications de schéma de base de données → Utiliser database-operations à la place
• Systèmes d'email / notification → Utiliser communications à la place
• Configuration de la limitation de débit de l'API → Utiliser backend-api à la place
• Configuration de la conformité HIPAA → Utiliser security-compliance à la place
• Optimisation des performances → Utiliser optimization à la place

Déléguer à d'autres compétences lorsque :

• Ajout de fonctionnalités publiques pour les utilisateurs → frontend-development
• Modification de l'authentification des utilisateurs → auth-security
• Création de nouveaux points d'accès API pour usage externe → backend-api
• Mise en place d'infrastructure de surveillance → devops-infrastructure