Aller au contenu principal

Plan d'Amélioration Frontend - Aaperture

Dernière mise à jour : 2026-02-21
Source de vérité : Ce document est la référence principale pour les améliorations frontend.
Point d'entrée : ROADMAP.md | PRIORITES.md

📊 Vue d'ensemble​

Objectif principal : Maintenir tous les fichiers de composant/page sous 400 lignes pour améliorer la lisibilité, la maintenabilité et la testabilité.

Statut actuel :

  • ✅ Refactoring cible (fichiers > 400 lignes) : première vague terminée (32 fichiers refactorisés, voir FRONTEND_REFACTORING_RESTANTS.md).
  • Les éventuels fichiers encore au-dessus de 400 lignes relèvent d’une priorisation continue ; pas de liste figée dans ce document.

✅ Ajouts récents (février 2026)​

  • ✅ Dashboard simplifié (hub) : recentrage de l’accueil vers un hub modulaire et allégé, avec dispatch des vues détaillées vers les pages dédiées.

  • ✅ Quick Actions : suppression du pattern dropdown non essentiel, harmonisation des actions rapides.

  • ✅ Session Wizard (modal multi-étapes) :

    • création guidée session + documents (devis/facture) + moodboard
    • champs obligatoires visibles et validation de progression par étape
    • dépendances explicites entre type de session, workflow, prestation (rate) et plan de paiement
    • résumé final rendu lisible (labels métier, statuts humains, valeurs compréhensibles)
    • création automatique de ligne prestation dans devis/facture si sélectionnée
    • placeholders explicites pour noms optionnels devis/facture avec nom par défaut

  • ✅ UX Configuration Wizard :

    • workflow hérité du type de session par défaut (édition manuelle possible)
    • états disabled maîtrisés tant que les prérequis ne sont pas sélectionnés
    • correction du bouton Modifier workflow (plus d’écrasement automatique de l’état manuel)

  • ✅ Messagerie : unification des threads (app/portail/contacts) avec ClientThreadView, previews images via URL signées, modal plein écran et UX alignée.

  • ✅ Pièces jointes : upload résilient côté portail (presigned + fallback backend), rafraîchissement temps réel des fichiers via WebSocket.

  • ✅ Stabilité UI : loaders cohérents sur le chargement de conversation, scroll interne maîtrisé (pas de scroll global).

  • ✅ Chat agent : refonte UI/UX (input, tokens / et @, commandes, navigation clavier), formulaires guidés et statut visuel des actions.

  • ✅ Chat agent (form builder) : refactor en composants + hooks dédiés pour rester < 400 lignes par fichier, lint stabilisé.

  • ✅ Chat agent (usages) : /help direct sans formulaire, input actif même avec formulaire ouvert, badges @type lisibles.

  • ✅ Chat agent (stabilité runtime) :

    • suppression du streaming
    • message utilisateur optimiste immédiat
    • apparition formulaire sans refresh
    • rendu standardisé des retours actions (success/warning/error)
    • tests ciblés prefill formulaires

🎯 Nouvelle priorité frontend recommandée​

Priorité #1 - E2E Agent Chat (fiabilité produit)​

  • Ajouter une suite e2e navigateur pour couvrir :
    • commande / avec formulaire attendu
    • mention @ + préremplissage effectif
    • soumission formulaire -> statut DONE
    • réponse erreur -> statut WARNING/ERROR standardisé
  • Objectif : empêcher les régressions invisibles “ça marche au refresh mais pas à chaud”.
  • ✅ Base Playwright ajoutée (config + scénarios critiques)
  • ✅ Fixture d’auth + seed API minimal (contact/session) ajoutés
  • ✅ 2 scénarios critiques activés (slash token immédiat, @session -> chip)
  • 🔜 Prochaine étape : rendre 2 scénarios restants déterministes (DONE + bloc warning/error)
  • ✅ Intégration GitLab ajoutée : job test:e2e:frontend (auto si secrets e2e disponibles, manuel sinon)

📋 Refactoring (historique)​

Le refactoring des fichiers > 400 lignes a été mené à bien pour une première vague de 32 fichiers. Liste et statistiques : FRONTEND_REFACTORING_RESTANTS.md. Pour toute nouvelle cible (fichiers encore longs), prioriser via PRIORITES.md et ce plan.

📋 Checklist de Refactoring​

Pour chaque fichier à refactorer :

Analyse​

  • Identifier les sections distinctes
  • Identifier la logique métier réutilisable
  • Identifier les utilitaires à extraire
  • Identifier les types à extraire

Extraction​

  • Créer components/ directory avec composants scoped
  • Créer hooks/ directory avec hooks personnalisés
  • Créer helpers.ts pour utilitaires
  • Créer types.ts pour types spécifiques

Refactoring​

  • Utiliser FormPageLayout / ViewPageLayout / ListPageLayout
  • Utiliser composants molécules (PageHeader, DataField, StatusBadge)
  • Utiliser ListPageContent pour listes
  • Utiliser useListPage pour logique de liste
  • Vérifier responsive (mobile-first)
  • Vérifier accessibility

Validation​

  • npm run lint - Aucune erreur
  • npm run build - Build réussi
  • Tester toutes les fonctionnalités
  • Vérifier sur mobile
  • Vérifier sur desktop

🏗️ Structure Recommandée pour Pages Complexes​

{PageName}/
  {PageName}.tsx          # Composant principal (< 400 lignes)
  types.ts                # Types TypeScript
  helpers.ts              # Fonctions utilitaires
  hooks/                   # Hooks personnalisés
    use{Feature}.ts
  components/              # Composants scoped
    {SectionComponent}.tsx
    index.ts

📚 Patterns de Refactoring​

Pattern 1 : Formulaires Complexes​

// InvoiceFormPage.tsx (< 400 lignes)
import { InvoiceDetailsForm, InvoiceItemsForm, InvoiceRecipientForm } from "./components";
import { useInvoiceForm } from "./hooks/useInvoiceForm";

export const InvoiceFormPage = () => {
  const form = useInvoiceForm();

  return (
    <FormPageLayout backTo="/invoices" title="...">
      <InvoiceDetailsForm form={form} />
      <InvoiceItemsForm form={form} />
      <InvoiceRecipientForm form={form} />
      <FormActions ... />
    </FormPageLayout>
  );
};

Pattern 2 : Pages avec Onglets​

// AdminPanelPage.tsx (< 400 lignes)
import { AdminUsersTab, AdminSettingsTab, AdminSystemTab } from "./components";

export const AdminPanelPage = () => {
  const [activeTab, setActiveTab] = useState("users");

  return (
    <Tabs value={activeTab} onValueChange={setActiveTab}>
      <TabsList>...</TabsList>
      <TabsContent value="users">
        <AdminUsersTab />
      </TabsContent>
      <TabsContent value="settings">
        <AdminSettingsTab />
      </TabsContent>
      <TabsContent value="system">
        <AdminSystemTab />
      </TabsContent>
    </Tabs>
  );
};

Pattern 3 : Pages de Visualisation​

// SessionViewPage.tsx (< 400 lignes)
import {
  SessionInfoSection,
  SessionTimelineSection,
  SessionDocumentsSection,
} from "./components";

export const SessionViewPage = () => {
  const { data: session } = useSession(id);

  return (
    <ViewPageLayout>
      <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
        <div className="md:col-span-2">
          <SessionInfoSection session={session} />
          <SessionTimelineSection session={session} />
        </div>
        <div className="sticky top-20">
          <SessionDocumentsSection session={session} />
        </div>
      </div>
    </ViewPageLayout>
  );
};

Pattern 4 : Router Configuration​

// router.tsx (< 400 lignes)
import { authRoutes } from "./routes/auth.routes";
import { adminRoutes } from "./routes/admin.routes";
import { sessionsRoutes } from "./routes/sessions.routes";
// ... autres routes

export const routeTree = rootRoute.addChildren([
  ...authRoutes,
  ...adminRoutes,
  ...sessionsRoutes,
  // ...
]);

📈 Métriques de Succès​

Objectifs Quantitatifs​

  • 0 fichiers > 1000 lignes
  • 0 fichiers > 400 lignes
  • 100% des pages utilisent les layouts standardisés
  • 100% des listes utilisent ListPageContent
  • 100% des formulaires utilisent FormPageLayout

Objectifs Qualitatifs​

  • Code plus maintenable et testable
  • Composants réutilisables maximisés
  • Performance améliorée (First Contentful Paint, Time to Interactive)
  • Meilleure expérience utilisateur (mobile et desktop)

✅ Améliorations Complétées Récemment​

Settings Contextuels avec Sidebar (2026-01-29)​

Objectif : Intégrer les panneaux de settings directement dans les vues pour réduire la navigation et améliorer l'expérience utilisateur.

Implémentation :

  • ✅ UserViewPage : Panneau de settings contextuel avec tabs Profile, Subscription, Permissions
  • ❌ AdminPanelPage : Panneau de settings retiré (2026-01-29) - Les tabs sont restés inline car la page Admin est déjà une page de configuration
  • ✅ Pattern cohérent avec InsightSettingsSidebarContent existant
  • ✅ Bouton Settings (icône roue crantée) dans les headers des vues
    • Bouton icon-only (size="icon") avec variant outline
    • Icône Settings de lucide-react (h-4 w-4)
    • Texte sr-only pour l'accessibilité
    • Positionné dans le header à droite, à côté des autres actions
  • ✅ Footer fixe avec actions (Cancel/Save) dans les panneaux

Pattern du bouton Settings :

<Button
  size="icon"
  variant="outline"
  onClick={() => setSettingsSidebarOpen(true)}
>
  <Settings className="h-4 w-4" />
  <span className="sr-only">{t("common.settings", "Paramètres")}</span>
</Button>

Fichiers créés/modifiés :

  • frontend/src/pages/users/UserViewPage/components/UserSettingsSidebarContent.tsx (CREATED)
  • frontend/src/pages/users/UserViewPage/UserViewPage.tsx (MODIFIED - intégration sidebar + bouton Settings)
  • frontend/src/pages/admin/AdminPanelPage/AdminPanelPage.tsx (MODIFIED - tabs inline restaurés, sidebar retirée)

Bénéfices :

  • Accès contextuel aux settings depuis les vues
  • Réduction de la navigation vers des pages séparées
  • Pattern uniforme avec les autres vues (Insights)
  • Meilleure découverte des options de configuration
  • Bouton Settings visible et accessible dans le header de chaque vue

Prochaines étapes :

  • ✅ COMPLÉTÉ (2026-01-29) - Toutes les vues principales ont maintenant des sidebars de settings :
    • ✅ SessionViewPage (type de session, notifications)
    • ✅ OrganizationViewPage (membres, ressources)
    • ✅ DashboardPage (widgets, rafraîchissement)

🔗 Références​