fatimaashar666-web/MCPpractice

Compétence Agent Campus Helpdesk

Cette compétence définit les normes techniques, les flux de travail et les bonnes pratiques pour développer, améliorer et maintenir l'application web Campus Helpdesk. Utilisez ce guide chaque fois que vous ajoutez des fonctionnalités, refactorisez des composants, mettez à jour les workflows de statut ou modifiez des modèles de données dans ce projet.

---

1. Écrire des Composants React Propres et Réutilisables

Maintenez une architecture de composants modulaire et découplée :

• Principe de Responsabilité Unique : Chaque composant doit faire une seule chose bien.
  • La logique de formulaire et les champs appartiennent à IssueForm.jsx.
  • La recherche publique, le filtrage et l'affichage des cartes de tickets appartiennent à TicketList.jsx.
  • Les métriques analytiques, les barres de progression visuelles et les tableaux administratifs appartiennent à AdminDashboard.jsx.
  • Les inspections modales et les chronologies d'historique appartiennent à TicketModal.jsx.
  • Les notifications appartiennent à Toast.jsx.
• Conception des Props et de l'État :
  • Gardez l'état aussi local que possible. Remontez l'état à App.jsx uniquement lorsqu'il est partagé entre des vues distinctes (par exemple, tickets, activeTab, toasts globaux).
  • Utilisez des composants enfants purement de présentation lorsque c'est possible, en passant des callbacks (onSelectTicket, onUpdateStatus, onDeleteTicket) de manière propre.
  • Évitez les états dupliqués ; calculez les valeurs dérivées (par exemple, tickets filtrés, statistiques KPI) à l'aide de useMemo.
• Conventions de Nommage et Code Propre :
  • Les fichiers de composants utilisent le PascalCase (AdminDashboard.jsx, IssueForm.jsx).
  • Les fichiers d'utilitaires et de constantes utilisent le camelCase (storage.js, constants.js).
  • Les gestionnaires d'événements doivent suivre le modèle handle[Action] (par exemple, handleSubmit, handleStatusChange).
  • Conservez les commentaires et les docstrings. Écrivez du code auto-explicatif avec des noms de variables clairs et descriptifs.
• Zéro Dépendances Externes Lourdes :
  • Maintenez une architecture légère : utilisez les hooks React natifs, des SVG en ligne purs pour les icônes et des classes CSS à portée limitée au lieu d'importer des bibliothèques de composants tierces volumineuses.

---

2. Créer une Interface Utilisateur Réactive et Accessible

Le portail Campus Helpdesk doit offrir une expérience utilisateur fluide sur tous les appareils (téléphones mobiles, tablettes, ordinateurs portables, grands écrans) :

• Mises en Page Fluides et Points de Rupture :
  • Concevoir d'abord pour le mobile ou pour le desktop avec des points de rupture cohérents :
    • Desktop : Largeur maximale du conteneur 1240px avec des grilles multi-colonnes (5 cartes de métriques, analytique 2 colonnes, formulaires 2 colonnes).
    • Tablette (<= 1024px) : Réduisez les grilles de métriques à 5 colonnes à 3 ou 2 colonnes ; empilez les graphiques analytiques en une seule colonne.
    • Mobile (<= 768px) : Empilez la navigation de l'en-tête, les champs de formulaire en 1 colonne ; activez le défilement horizontal sur les tableaux de données.
    • Petits Écrans (<= 480px) : Cartes de métriques en pleine largeur, boutons d'action empilés et notifications toast épinglées en bas.
• Accessibilité (a11y) :
  • Tous les éléments interactifs doivent avoir un HTML sémantique approprié (<button>, <input>, <select>, <textarea>).
  • Les contrôles de formulaire doivent avoir des éléments <label htmlFor="..."> associés avec des attributs id correspondants.
  • Les boîtes de dialogue modales doivent avoir role="dialog", aria-modal="true", et supporter la fermeture via des clics sur l'arrière-plan et les touches d'échappement.
  • Les icônes interactives ou les boutons uniquement iconiques doivent inclure des attributs aria-label ou title descriptifs.
  • Maintenez des rapports de contraste de couleurs accessibles pour le texte sur les badges de statut et les étiquettes de priorité.
• Retour Visuel et Transitions :
  • Les éléments interactifs doivent montrer des états clairs :hover, :focus et :active.
  • Les champs de formulaire en focus doivent afficher un anneau de focus à contraste élevé (var(--primary-ring)).
  • Utilisez des micro-animations (glissement de toast, agrandissement modal, spinners de bouton) pour informer l'utilisateur des actions en arrière-plan sans provoquer de changement de mise en page.

---

3. Valider le Formulaire d'Incident Étudiant

Toutes les soumissions d'incidents via IssueForm.jsx doivent suivre des règles de validation côté client strictes avant toute mutation ou stockage d'état :

Matrice des Règles de Validation

Champ	Règle	Message d'Erreur
Nom Complet	Obligatoire, sans espaces superflus, non vide	"Veuillez fournir votre nom complet."
Email du Campus	Obligatoire, expression régulière valide /^[^\s@]+@[^\s@]+\.[^\s@]+$/	"Veuillez entrer une adresse email valide."
Lieu / Salle	Obligatoire, sans espaces superflus, non vide	"Spécifiez le bâtiment, le hall ou l'emplacement du campus."
Catégorie	Obligatoire, doit correspondre à la liste CATEGORIES	Sélectionnée automatiquement par défaut
Priorité	Obligatoire, doit correspondre à PRIORITIES (Faible, Moyenne, Haute, Urgente)	Par défaut : 'Moyenne'
Sujet / Titre de l'Incident	Obligatoire, sans espaces superflus, longueur minimale $≥ 5$ caractères	"Le titre doit comporter au moins 5 caractères."
Description Détaillée	Obligatoire, sans espaces superflus, longueur minimale $≥ 15$ caractères	"La description doit comporter au moins 15 caractères."

Étapes de Mise en Œuvre de la Validation

1. Maintenez un objet d'état errors mappant les noms de champs aux chaînes d'erreur.
2. Effacez l'erreur du champ spécifique lorsque l'utilisateur modifie sa saisie (handleChange).
3. Vérifiez toutes les règles lors de handleSubmit. Empêchez la soumission et mettez en évidence les champs invalides avec .input-error et .field-error si des erreurs existent.
4. En cas de succès :
   • Générez un ID unique (par exemple TCK-XXXX).
   • Attribuez le statut initial En Attente.
   • Enregistrez l'horodatage de soumission initial et le nœud d'historique.
   • Réinitialisez les champs du formulaire et l'état d'erreur.
   • Déclenchez un toast de succès et naviguez vers la vue de suivi des tickets.

---

4. Gérer les Statuts En Attente, En Cours et Résolu

Le Campus Helpdesk suit un cycle de vie strictement défini en 3 étapes :

[ En Attente ]  ───►  [ En Cours ]  ───►  [ Résolu ]
    ▲                      ▲                     │
    └──────────────────────┴─────────────────────┘ (Peut être rouvert si nécessaire)

Définitions des Statuts et Système de Conception Visuelle

1. En Attente :
   • Signification : Nouvel incident soumis par un étudiant/employé, en attente de triage ou d'attribution.
   • Thème de Couleur : Ambre (#d97706), arrière-plan #fef3c7, bordure #fde68a.
   • Étape de Progression : Étape 1 active.
2. En Cours :
   • Signification : Un technicien ou un service du campus a pris en charge le ticket et enquête ou répare activement.
   • Thème de Couleur : Bleu Royal (#2563eb), arrière-plan #dbeafe, bordure #bfdbfe.
   • Étape de Progression : Étapes 1 et 2 actives.
3. Résolu :
   • Signification : La réparation est terminée, l'équipement remplacé ou le service rétabli.
   • Thème de Couleur : Vert Émeraude (#059669), arrière-plan #d1fae5, bordure #a7f3d0.
   • Étape de Progression : Étapes 1, 2 et 3 actives.

Règles du Cycle de Vie et Historique d'Audit

• Chaque transition de statut doit ajouter un événement au tableau history du ticket :

  {
    status: nouveauStatut,
    timestamp: new Date().toISOString(),
    note: `Statut mis à jour vers ${nouveauStatut}`
  }
  

• La mise à jour des notes internes du personnel doit mettre à jour adminNote et updatedAt sans réinitialiser createdAt original du ticket.
• Les mises à jour doivent immédiatement se synchroniser avec localStorage (campus_helpdesk_tickets_v1).

---

5. Maintenir des Statistiques Précises du Tableau de Bord

Le tableau de bord d'administration fournit une visibilité opérationnelle en temps réel. Tous les calculs de métriques KPI et de graphiques doivent être dérivés dynamiquement du tableau source de vérité tickets :

Calculs des Métriques

1. Total des Tickets : $$\text{Total} = \text{tickets.length}$$
2. Nombre En Attente : $$\text{En Attente} = \text{tickets.filter}(t \Rightarrow t.\text{status} === \text{STATUSES.PENDING}).\text{length}$$
3. Nombre En Cours : $$\text{En Cours} = \text{tickets.filter}(t \Rightarrow t.\text{status} === \text{STATUSES.IN_PROGRESS}).\text{length}$$
4. Nombre Résolu : $$\text{Résolu} = \text{tickets.filter}(t \Rightarrow t.\text{status} === \text{STATUSES.RESOLVED}).\text{length}$$
5. Taux de Résolution (%) : $$\text{Taux de Résolution} = \begin{cases} \text{Math.round}\left(\frac{\text{Résolu}}{\text{Total}} \times 100\right), & \text{si Total} > 0 \ 0, & \text{sinon} \end{cases}$$
6. File d'Attente Haute et Urgente : $$\text{Urgent/Haute} = \text{tickets.filter}(t \Rightarrow t.\text{priority} === 'Urgent' \lor t.\text{priority} === 'High').\text{length}$$
7. Distributions des Catégories et des Priorités :
   • Calculez les comptes pour toutes les catégories et priorités prédéfinies, même si le compte est 0, pour éviter le scintillement de l'interface utilisateur ou la division par zéro.
   • Assurez-vous que les pourcentages de largeur des barres de progression totalisent toujours $\le 100%$.

Enveloppez tous les calculs statistiques dans le hook useMemo de React avec [tickets] comme dépendance pour maintenir les performances.

---

6. Tester les Modifications et Exécuter la Build

Avant de soumettre toute modification de code ou de marquer une tâche comme terminée, vérifiez l'application via l'analyse statique et les étapes de build de production :

Protocole de Vérification

1. Naviguez vers le Répertoire du Projet :

   cd "campus-helpdesk"
   

2. Exécutez le Linting Statique du Code :

   npm run lint
   

   • Doit se terminer avec le code 0.
   • Assurez-vous qu'il n'y a pas d'importations inutilisées, de variables inutilisées ou d'entités JSX non échappées.

3. Exécutez la Build de Production :

   npm run build
   

   • Vérifiez que Vite termine le regroupement des ressources de production sans erreurs ni avertissements.
   • Vérifiez que dist/index.html, dist/assets/*.css et dist/assets/*.js sont créés avec succès.

4. Vérifiez la Persistance du localStorage :

   • Testez que la soumission d'un ticket met à jour localStorage.getItem('campus_helpdesk_tickets_v1').
   • Testez que la mise à jour du statut du ticket persiste après le rafraîchissement de la page.
   • Testez les fonctionnalités "Réinitialiser les Données d'Exemple" et "Tout Effacer".

---

7. Signaler les Erreurs Honnêtement

L'intégrité et l'honnêteté sont essentielles lors du signalement de l'état du système ou des erreurs :

• Ne Masquez Pas les Échecs : Si une erreur de build, une erreur de syntaxe ou un échec de linting se produit, signalez le message d'erreur exact, le nom du fichier et le numéro de ligne.
• Explication de la Cause Racine : Expliquez pourquoi l'erreur s'est produite (par exemple, importation manquante, cas null non géré dans l'analyseur de stockage, contrat de props rompu).
• Correctifs Vérifiés Uniquement : Ne prétendez pas qu'un problème est résolu sans réexécuter la commande de vérification (npm run lint / npm run build) et confirmer le code de sortie 0.
• Transparence avec l'Utilisateur : Si une limitation inattendue du navigateur ou un problème de quota localStorage se produit, expliquez proactivement la limitation à l'utilisateur et présentez des options techniques claires.