Audit Context Engine DMV

Version provisoire — Ce document audite l'état actuel du code. L'architecture cible (Ranking Engine, trois surfaces, unification des moteurs) est définie dans 34-ranking-engine-synthesis.md.

1. Résumé exécutif

Périmètre audité :

• frontend dmv-public ;
• backend api/ pour le périmètre demandé comme dmv_api ;
• documentation dmv-docs.

Verdict

• Ce qui existe déjà
  • un squelette WallEngine / WallProvider exploitable dans dmv-public/app/components/wall/ ;
  • plusieurs hooks et sélecteurs déjà proches d’une logique de providers ou de scoring local ;
  • une première logique de résolution de contexte personnel dans Mon espace ;
  • des composants Card réutilisables déjà présents, surtout autour des publications ;
  • plusieurs briques API utiles comme sources métier, permissions, feature flags et listes filtrées.
• Ce qui manque
  • un NeedResolver explicite ;
  • un ContextResolver partagé ;
  • un Registry / ProviderRegistry transverse ;
  • un modèle standard de Card ;
  • un modèle standard d’Action ;
  • une couche de scoring/priorisation commune ;
  • un endpoint API dédié à la résolution de contexte ;
  • des tests ciblés sur ce moteur.
• Niveau d’alignement avec l’architecture cible
  • alignement partiel ;
  • le code contient déjà plusieurs briques compatibles avec un futur Context Engine ;
  • en revanche, la sélection métier reste encore largement dispersée dans l’UI, les hooks de page et des requêtes directes Supabase.
• Risques principaux
  • dérive entre documentation cible et code réel ;
  • logique métier encore embarquée dans des composants de page ;
  • doublons entre MurVille, Mon espace et anciens composants partagés ;
  • dépendance forte à des RPC Supabase dispersées côté frontend ;
  • risque de régression MurVille si la migration commence par la route publique.

Surfaces réellement trouvées

• MurVille : trouvé.
• Mon espace / Mon mur : trouvé.
• Agenda : blocs et vues secondaires trouvés ; page dédiée autonome non trouvée.
• Recherche : trouvé.
• Assistant : module API IA trouvé ; page frontend dédiée à un assistant utilisateur non trouvée.
• Notifications futures : surface dédiée non trouvée.

2. Architecture cible rappelée

Architecture cible rappelée :

Besoin utilisateur
  → Contexte
  → Context Engine
  → Registry / Providers
  → Cards
  → Actions
  → UI

Règle structurante :

• le moteur sélectionne et priorise ;
• l’UI présente ;
• le moteur ne décide jamais directement du layout ni du composant de page final.

Conséquence pratique :

• la page ne doit pas contenir la logique métier de sélection ;
• les providers exposent des données normalisées ;
• les cards et actions doivent être décrites par contrat ;
• les pages MurVille, Mon espace, Agenda, Recherche, Assistant et futures notifications doivent pouvoir consommer la même couche de pertinence avec des rendus différents.

3. Cartographie de l’existant

3.1 Frontend — noyau Wall / MurVille

Chemin	Rôle actuel observé	Alignement	Remarque
dmv-public/app/components/wall/WallEngine.tsx	Point d’entrée du mur ; instancie WallProvider puis délègue au layout	Partiel	Orchestrateur léger déjà utile, mais pas encore Context Engine transverse
dmv-public/app/components/wall/context/WallContext.tsx	Compose directement usePublications, useCollectes, useWallActorsData, useWallUserSignals, useWallTargetedPublications, useWallAgendaInterests, useFeaturedPublications	Partiel	Proche d’un provider agrégateur, mais sans registry explicite
dmv-public/app/components/wall/contexts/types.ts	Contrat actuel des contextes commune, personal, actor	Partiel	Contrat encore minimal ; pas de modèle standard de card/action/permissions
dmv-public/app/components/wall/components/WallLayout.tsx	Composition principale du mur et arbitrages de contenu	Faible	Contient encore de la logique de sélection et de priorisation qui devrait sortir de l’UI
dmv-public/app/components/wall/selectors/publicationFeedSelectors.ts	Sélecteurs de feed publications, déduplication, groupes timeline	Fort	Bonne base réutilisable de normalisation locale
dmv-public/app/components/wall/selectors/agendaSelectors.ts	Regroupement et filtrage agenda	Fort	Bonne base de provider agenda
dmv-public/app/components/wall/selectors/actorPanelSelectors.ts	Sélection et filtrage d’acteurs pour le panneau MurVille	Fort	Bonne base de transformation locale
dmv-public/app/components/wall/hooks/useWallUserSignals.ts	Résout signaux utilisateur : suivis, alertes, lastSeen	Partiel	Proto-provider de signaux utilisateur
dmv-public/app/components/wall/hooks/useWallTargetedPublications.ts	Produit des publications ciblées selon le filtre courant	Partiel	Logique utile, mais couplée aux filtres MurVille
dmv-public/app/components/wall/hooks/useWallAgendaInterests.ts	Gère l’état des intérêts agenda	Partiel	Bon candidat pour une action standardisée
dmv-public/app/components/wall/hooks/useWallMurVilleRuntime.ts	Runtime de MurVille : scroll, swipe, pagination infinie	Partiel	Couche d’interaction MurVille spécifique, pas moteur
dmv-public/app/components/wall/hooks/useWallMurVilleHostProps.ts	Assemble les props du host MurVille à partir des données du mur	Partiel	Adaptateur de présentation MurVille, encore très surface-spécifique
dmv-public/app/components/wall/components/mur-ville/WallMurVilleHostContainer.tsx	Container de rendu MurVille migré	Partiel	Bonne cible d’adaptation UI, pas de logique moteur
dmv-public/app/components/MurVille.tsx	Point d’entrée public MurVille	Partiel	Façade produit
dmv-public/app/components/MurVilleHost.tsx	Hôte MurVille minimal autour du mur	Partiel	Façade transitoire
dmv-public/app/components/MurVilleGate.tsx	Gate MurVille via RPC get_mur_ville_enabled	Faible	Logique d’éligibilité dispersée hors moteur

3.2 Frontend — Mon espace, recherche, cards, actions

Chemin	Rôle actuel observé	Alignement	Remarque
dmv-public/app/components/mon-espace/MonEspaceShell.tsx	Orchestration de Mon espace ; branche WallEngine pour personal/commune, flux séparé pour actor	Partiel	L’acteur bypass le moteur actuel
dmv-public/app/components/mon-espace/MonEspaceActorFeed.tsx	Feed acteur dédié via requête Supabase directe	Faible	Résolution métier encore spécifique à la page
dmv-public/app/components/mon-espace/hooks/useMonEspaceVillages.ts	Résout les villages par sources prioritaires (profile, contributor, managed, actor, favori, test, fallback)	Fort	Plus proche du futur ContextResolver côté frontend
dmv-public/app/components/mon-espace/hooks/usePersonalContext.ts	Construit le contexte personnel à partir des villages et favoris	Partiel	Très utile, mais encore local à Mon espace
dmv-public/app/components/wall/contexts/personal/createPersonalContext.ts	Fabrique de contexte personnel	Fort	Bonne brique de modélisation
dmv-public/app/components/wall/contexts/personal/sources/favoriteActorsSource.ts	Source personnelle “acteurs suivis”	Fort	Bon prototype de source/provider
dmv-public/app/components/wall/contexts/personal/sources/primaryCommuneSource.ts	Source personnelle “commune principale”	Fort	Bon prototype de source/provider
dmv-public/app/components/mon-espace/MonEspaceTodaySummary.tsx	Sélectionne et compte des signaux “ce qui compte aujourd’hui”	Faible	Logique de card/provider encore dans le composant
dmv-public/app/components/mon-espace/MonEspaceAgendaBlock.tsx	Bloc agenda personnel et village via Supabase + localStorage	Faible	Duplique une partie de la logique agenda déjà présente côté Wall
dmv-public/app/components/mon-espace/MonEspaceContexts.tsx	Switch de contexte + bloc “Infos importantes” + agenda + favoris	Faible	Plusieurs responsabilités métier et UI regroupées
dmv-public/app/recherche/RechercheClient.tsx	Recherche simple d’acteurs via Supabase	Faible	Pas de contexte ni scoring transverse
dmv-public/app/[commune]/AnnuaireClient.tsx	Recherche/annuaire commune avec scoring, pagination, enrichissement, carte	Partiel	Meilleure logique de scoring actuelle, mais limitée à l’annuaire
dmv-public/lib/searchUtils.ts	computeActorSearchScore et sortActorsBySearch	Fort	Brique de scoring locale réutilisable
dmv-public/app/[commune]/acteur/[slug]/ActorsClient.tsx	Détail acteur avec actions explicites (appeler, itinéraire, suivre, site web, revendication)	Partiel	Bon inventaire d’actions, mais non normalisées
dmv-public/app/components/wall/components/publications/WallPublicationCard.tsx	Card publication réutilisable avec suivi, signalement, agenda	Fort	Très bon candidat pour une Card standard
dmv-public/components/publications/PublicationCard.tsx	Doublon fonctionnel de WallPublicationCard	Faible	Quasi-identique au composant Wall
dmv-public/app/components/wall/components/actors/ActorMiniCard.tsx	Mini-card acteur	Fort	Réutilisable
dmv-public/app/components/wall/components/common/AgendaInterestButton.tsx	Primitive d’action agenda	Fort	Réutilisable pour un modèle d’action
dmv-public/app/components/VilleDrawer.tsx	Drawer commune historique	Faible	Doublon fonctionnel avec la version Wall
dmv-public/app/components/wall/components/drawer/WallVilleDrawer.tsx	Drawer commune côté Wall avec cache SWR local	Partiel	Bonne version cible, mais doublon maintenu
dmv-public/app/components/VisitorTipsBanner.tsx	Bannière historique	Faible	Doublon fonctionnel
dmv-public/app/components/wall/components/common/WallVisitorTipsBanner.tsx	Bannière côté Wall	Partiel	Doublon fonctionnel
dmv-public/app/components/wall/components/secondary/WallSecondaryPagesContainer.tsx	Gère les pages secondaires du mur (agenda, favoris, infos mairie…)	Partiel	Mélange encore présentation et règles métier

3.3 API — endpoints et services utiles au futur moteur

Chemin	Rôle actuel observé	Alignement	Remarque
api/app/Modules/Publication/Context/PublicationContext.php	Contexte d’exécution d’une requête publications (appSource, allowedScopes, communeId)	Partiel	Concept de contexte déjà présent, mais scope API/publication seulement
api/app/Modules/Publication/Routes/api.php	Endpoints publications (/publications, /acteurs/{acteurId}/publications, /communes/{communeId}/publications)	Partiel	Sources métier existantes, sans résolution de contexte
api/app/Modules/Publication/Services/PublicationReadService.php	Lecture publications avec filtres et tri publie_le desc	Partiel	Source métier utile, pas moteur de priorisation transverse
api/app/Modules/Territory/Routes/api.php	Endpoints communes, collectes, infos, élus, défibrillateurs	Fort	Expose des sources territoire déjà structurées
api/app/Modules/Territory/Services/TerritoryService.php	Lecture commune et fusion d’infos mairie/acteur	Partiel	Bonne logique métier réutilisable côté provider
api/app/Modules/Actor/Routes/api.php	Endpoints acteurs, tags, documents, modules, access-context	Partiel	Bonne base pour actions, droits et enrichissements
api/app/Modules/Actor/Services/ActeurReadService.php	Lecture acteurs avec priorisation featured_until puis nom	Partiel	Scoring existant mais limité à un listing acteurs
api/app/Modules/Actor/Services/ActorAccessService.php	Résout rôle, permissions, modules pour un acteur	Fort	Très bon candidat pour une future couche de permissions/actions
api/app/Modules/Settings/Routes/api.php	Endpoints feature-tabs et settings	Partiel	Peut alimenter des capacités et cards conditionnelles
api/app/Modules/Settings/Services/SettingsReadService.php	Résout les feature tabs effectifs avec override acteur	Fort	Logique de priorité déjà bien encadrée
api/app/Modules/Community/Routes/api.php	Endpoints contributeur, groupes, favoris	Partiel	Source métier utile
api/app/Modules/Community/Services/CommunityReadService.php	Retourne les favoris d’un contributeur en brut	Partiel	Ne compose pas encore les “favoris enrichis” consommés par le frontend
api/app/Modules/AI/Routes/api.php	Endpoints IA publication/service/onboarding	Faible	Pas de surface de Context Engine, mais un assistant métier backend existe

3.4 Documentation — vision déjà rédigée

Chemin	Rôle actuel observé	Alignement	Remarque
dmv-docs/docs/00-foundation/07-experience-engine.md	Vision fondatrice Besoin → Contexte → Scénario → Sources → Composer → Feed → Cards → Interactions	Fort	Plus avancé que le code actuel
dmv-docs/docs/06-architecture/wall-engine/02-context-engine.md	Vision d’architecture Context Engine	Fort	Cible claire
dmv-docs/docs/06-architecture/wall-engine/04-context-types.md	Typologie de contextes	Fort	Plus riche que les types réellement implémentés
dmv-docs/docs/06-architecture/wall-engine/05-wall-context-schema.md	Schéma cible du contexte	Fort	Le code n’implémente pas encore ce schéma complet
dmv-docs/docs/06-architecture/wall-engine/06-search-integration.md	Intégration cible avec la recherche	Fort	La page de recherche actuelle reste très en-dessous de cette cible
dmv-docs/docs/06-architecture/wall-engine/07-mon-espace-integration.md	Intégration cible avec Mon espace	Fort	Plusieurs briques existent mais ne sont pas encore unifiées
dmv-docs/docs/08-frontend/22-context-engine.md	Règles frontend Context Engine / WallEngine	Fort	La doc décrit une séparation plus avancée que le runtime réel
dmv-docs/docs/08-frontend/23-wallengine-v1-parity.md	Jalon de parité MurVille et contrainte de non-régression	Fort	Contrainte majeure pour toute migration
dmv-docs/docs/08-frontend/24-scenario-engine-cardfeed.md	Vision plus avancée Scenario Engine — CardFeed	Fort	Vision conceptuelle ; aucune implémentation applicative trouvée

4. Ce qui est déjà aligné

Wall / MurVille

• dmv-public/app/components/wall/WallEngine.tsx sépare déjà un point d’entrée de mur d’un layout de rendu.
• dmv-public/app/components/wall/context/WallContext.tsx centralise déjà plusieurs sources de données au lieu de les laisser dans chaque composant.
• dmv-public/app/components/wall/selectors/publicationFeedSelectors.ts factorise déjà une partie utile de la priorisation locale du feed.
• dmv-public/app/components/wall/selectors/agendaSelectors.ts et dmv-public/app/components/wall/selectors/actorPanelSelectors.ts sont déjà des briques de transformation réutilisables.

Mon espace

• dmv-public/app/components/mon-espace/hooks/useMonEspaceVillages.ts ressemble déjà à un vrai résolveur de contexte, avec priorités explicites par source.
• dmv-public/app/components/mon-espace/hooks/usePersonalContext.ts produit un contexte personnel structuré.
• dmv-public/app/components/wall/contexts/personal/createPersonalContext.ts et les sources personnelles associées modélisent déjà le contexte plutôt que le JSX.

Cards et actions

• dmv-public/app/components/wall/components/publications/WallPublicationCard.tsx constitue déjà une card métier concrète et réutilisable.
• dmv-public/app/components/wall/components/actors/ActorMiniCard.tsx est déjà une carte compacte réutilisable.
• dmv-public/app/components/wall/components/common/AgendaInterestButton.tsx fournit déjà une action réutilisable.

API

• api/app/Modules/Publication/Context/PublicationContext.php montre qu’un concept de “contexte d’exécution” existe déjà côté backend.
• api/app/Modules/Actor/Services/ActorAccessService.php fournit déjà un contexte de droits exploitable pour des actions conditionnelles.
• api/app/Modules/Settings/Services/SettingsReadService.php gère déjà une logique de priorité et d’override.

Documentation

• la documentation cible existe déjà et est cohérente dans son intention ;
• elle fournit un bon cadre de migration ;
• le problème principal n’est pas l’absence de vision, mais l’écart entre cette vision et le code réel.

5. Ce qui est partiellement aligné

• dmv-public/app/components/wall/context/WallContext.tsx
  • déjà proche d’un agrégateur de providers ;
  • encore trop câblé à une commune et à des hooks concrets ;
  • pas de registration explicite des providers.
• dmv-public/app/components/wall/contexts/types.ts
  • les contextes commune, personal, actor existent ;
  • le contrat reste trop léger pour porter besoin, scoring, actions, capacités, permissions ou cartes normalisées.
• dmv-public/app/components/mon-espace/MonEspaceShell.tsx
  • personal et commune passent par WallEngine ;
  • actor ne passe pas par le même flux.
• dmv-public/app/components/mon-espace/MonEspaceActorFeed.tsx
  • réutilise la card publication du mur ;
  • mais reconstruit encore son propre flux de chargement et de filtrage.
• dmv-public/app/recherche/RechercheClient.tsx
  • expose une surface Recherche ;
  • mais pas de contexte, pas de registry, pas de card feed, pas de scoring transverse.
• dmv-public/app/[commune]/AnnuaireClient.tsx et dmv-public/lib/searchUtils.ts
  • contiennent une logique de scoring réelle et exploitable ;
  • mais spécialisée sur la recherche acteur, sans généralisation au reste des surfaces.
• api/app/Modules/Community/Services/CommunityReadService.php
  • expose les favoris ;
  • mais ne compose pas encore le niveau de contexte attendu par le frontend.
• api/app/Modules/Territory/Services/TerritoryService.php
  • contient une logique de fusion utile ;
  • mais pas encore présentée comme provider ou source transversale de contexte.
• dmv-docs/docs/08-frontend/22-context-engine.md et dmv-docs/docs/08-frontend/24-scenario-engine-cardfeed.md
  • décrivent une cible plus avancée ;
  • l’implémentation applicative correspond seulement partiellement à cette cible.

6. Ce qui manque

Élément attendu	Statut observé	Impact
NeedResolver	non trouvé	Aucun point d’entrée partagé pour transformer un besoin utilisateur en stratégie de sélection
ContextResolver transverse	non trouvé	Les contextes sont résolus par surface ou par hook local
Registry / ProviderRegistry	non trouvé	Les providers ne sont pas branchables ou composables proprement
Providers page-neutral explicites	non trouvé	Les hooks actuels sont surtout MurVille/Mon espace centric
Scoring/priorisation transverse	non trouvé	Le tri existe localement, sans cadre commun
Modèle standard de Card	non trouvé	Les cards sont des composants React directs, pas des descripteurs métier normalisés
Modèle standard d’Action	non trouvé	Les actions restent implicites dans les composants
Endpoint API de résolution de contexte	non trouvé	Le frontend doit encore composer localement beaucoup de logique
Surface Assistant frontend alimentée par contexte	non trouvé	Le module IA API existe, la surface utilisateur contextuelle n’a pas été trouvée
Surface Notifications futures	non trouvé	Pas de feed contextualisé de notifications observé
Tests frontend autour du moteur	non trouvé	Aucun filet de sécurité local sur cette future couche
Tests API autour d’un Context Engine	non trouvé	Les tests API existants portent les modules métier actuels, pas une résolution de contexte transverse

7. Couplages et doublons

7.1 Logique dupliquée entre MurVille et Mon espace

• agenda :
  • dmv-public/app/components/wall/hooks/useWallAgendaInterests.ts ;
  • dmv-public/app/components/mon-espace/MonEspaceAgendaBlock.tsx.
• publications d’acteurs suivis :
  • dmv-public/app/components/wall/hooks/useWallTargetedPublications.ts ;
  • dmv-public/app/components/mon-espace/MonEspaceActorFeed.tsx.
• signaux personnels :
  • dmv-public/app/components/wall/hooks/useWallUserSignals.ts ;
  • dmv-public/app/components/mon-espace/hooks/usePersonalContext.ts ;
  • dmv-public/app/components/mon-espace/MonEspaceTodaySummary.tsx.

7.2 Logique métier encore dans l’UI

Chemin	Logique métier observée
dmv-public/app/components/wall/components/WallLayout.tsx	sélection de contenus, arbitrage des panneaux, mapping des publications vers la card UI
dmv-public/app/components/wall/components/secondary/WallSecondaryPagesContainer.tsx	tri et composition de vues secondaires comme agenda, favoris, infos mairie
dmv-public/app/components/mon-espace/MonEspaceTodaySummary.tsx	comptage et sélection des signaux “ce qui compte aujourd’hui”
dmv-public/app/components/mon-espace/MonEspaceAgendaBlock.tsx	requêtes agenda, filtrage, regroupement et formatage métier
dmv-public/app/components/mon-espace/MonEspaceContexts.tsx	sélection “infos importantes” et règles de rendu liées au contexte
dmv-public/app/[commune]/acteur/[slug]/ActorsClient.tsx	assemblage d’actions métier et de comportements de contact/suivi

7.3 Requêtes Supabase et RPC dispersées

Constat :

• plusieurs résolutions de contexte ou d’action ne passent pas encore par api/ ;
• elles sont réparties entre hooks, pages et cards ;
• cela complique la mutualisation du futur moteur.

RPC et accès directs observés :

Appel	Emplacements observés
toggle_favori	dmv-public/app/components/wall/components/publications/WallPublicationCard.tsx, dmv-public/components/publications/PublicationCard.tsx, dmv-public/app/[commune]/acteur/[slug]/ActorsClient.tsx
report_publication	dmv-public/app/components/wall/components/publications/WallPublicationCard.tsx, dmv-public/components/publications/PublicationCard.tsx
list_favoris_with_latest	dmv-public/app/components/mon-espace/hooks/usePersonalContext.ts, dmv-public/app/components/mon-espace/hooks/useMonEspaceVillages.ts
search_acteurs_public	dmv-public/app/[commune]/AnnuaireClient.tsx
get_visible_tabs	dmv-public/app/[commune]/acteur/[slug]/ActorsClient.tsx
get_mur_ville_enabled	dmv-public/app/components/MurVilleGate.tsx

7.4 Doublons de composants

Doublon	Constat
dmv-public/components/publications/PublicationCard.tsx / dmv-public/app/components/wall/components/publications/WallPublicationCard.tsx	doublon fonctionnel quasi identique
dmv-public/app/components/VisitorTipsBanner.tsx / dmv-public/app/components/wall/components/common/WallVisitorTipsBanner.tsx	doublon fonctionnel
dmv-public/app/components/VilleDrawer.tsx / dmv-public/app/components/wall/components/drawer/WallVilleDrawer.tsx	doublon fonctionnel avec variation locale de cache

7.5 Actions existantes ou implicites

Action cible	Statut observé	Emplacements
ouvrir	implicite, non normalisée	liens dans cards et pages, ex. WallPublicationCard, ActorsClient, RechercheClient
ajouter agenda	trouvée, non normalisée	AgendaInterestButton, WallPublicationCard, MonEspaceAgendaBlock
appeler	trouvée, non normalisée	dmv-public/app/[commune]/acteur/[slug]/ActorsClient.tsx
itinéraire	trouvée, non normalisée	dmv-public/app/[commune]/acteur/[slug]/ActorsClient.tsx
partager	non trouvé	non trouvé
suivre	trouvée, non normalisée	WallPublicationCard, PublicationCard, ActorsClient
participer	non trouvé	non trouvé

8. Proposition d’architecture technique V1

Principe :

• ne pas réécrire le mur ;
• ne pas déplacer l’UI existante ;
• introduire une couche de contrat et d’orchestration entre les hooks métier et les pages ;
• réutiliser les sélecteurs, cards et hooks déjà présents ;
• brancher Mon espace avant MurVille.

8.1 Schéma V1 proposé

Need
  ↓
resolveContext()
  ↓
providerRegistry.run(context, surface)
  ↓
ProviderResult[]
  ↓
scoreAndSelect()
  ↓
CardDescriptor[]
  ↓
page adapter
  ↓
UI existante

8.2 Dossier frontend cible

Proposition réaliste :

dmv-public/app/core/context-engine/
  types/
    need.ts
    context.ts
    card.ts
    action.ts
  registry/
    providerRegistry.ts
  resolvers/
    resolveNeed.ts
    resolveContext.ts
    scoreAndSelect.ts
  providers/
    agendaProvider.ts
    publicationsProvider.ts
    userSignalsProvider.ts
  adapters/
    wall/
      toWallProps.ts
    mon-espace/
      toMonEspaceBlocks.ts

8.3 Rôle des couches proposées

• types/
  • définit les contrats communs ;
  • ne dépend pas des pages ;
  • permet d’aligner MurVille, Mon espace et Recherche.
• registry/
  • enregistre les providers activables selon un contexte ou une surface ;
  • remplace l’empilement manuel actuel de hooks.
• resolvers/
  • transforme un besoin et des signaux en contexte exploitable ;
  • applique scoring et priorisation sans JSX.
• providers/
  • encapsulent les hooks existants ou des accès API ;
  • ne décident pas du rendu final ;
  • retournent des données normalisées.
• adapters/
  • convertissent les CardDescriptor vers les composants actuels ;
  • conservent l’UX et la parité existantes.

8.4 Réutilisations directes recommandées

• conserver dmv-public/app/components/wall/selectors/publicationFeedSelectors.ts ;
• conserver dmv-public/app/components/wall/selectors/agendaSelectors.ts ;
• conserver dmv-public/app/components/wall/selectors/actorPanelSelectors.ts ;
• conserver dmv-public/app/components/wall/components/publications/WallPublicationCard.tsx ;
• conserver dmv-public/app/components/wall/components/actors/ActorMiniCard.tsx ;
• réutiliser dmv-public/app/components/mon-espace/hooks/useMonEspaceVillages.ts comme matière première du futur ContextResolver ;
• réutiliser api/app/Modules/Actor/Services/ActorAccessService.php et api/app/Modules/Settings/Services/SettingsReadService.php comme sources de permissions/capacités.

8.5 API plus tard, seulement si nécessaire

Proposition différée :

• ne pas commencer par un endpoint backend dédié ;
• stabiliser d’abord le contrat frontend Context / Card / Action ;
• créer ensuite un module Context côté api/ seulement si la composition locale reste trop dupliquée ou trop coûteuse.

Exemple de cible plus tard :

api/app/Modules/Context/
  Controllers/ContextReadController.php
  Services/ContextReadService.php
  DTOs/ContextCardDTO.php
  Routes/api.php

9. Plan de migration incrémental

Étape 1 — Types communs

• Objectif
  • introduire les types Need, ResolvedContext, CardDescriptor, ActionDescriptor sans toucher au rendu.
• Fichiers à créer/modifier
  • créer dmv-public/app/core/context-engine/types/need.ts
  • créer dmv-public/app/core/context-engine/types/context.ts
  • créer dmv-public/app/core/context-engine/types/card.ts
  • créer dmv-public/app/core/context-engine/types/action.ts
  • prévoir un adaptateur depuis dmv-public/app/components/wall/contexts/types.ts
• Risque
  • dérive entre contrats existants Wall et nouveaux types.
• Critères d’acceptation
  • les types communs existent ;
  • aucun changement visuel ;
  • WallContextDefinition peut être mappé vers ResolvedContext.

Étape 2 — Registry minimal

• Objectif
  • introduire un ProviderRegistry sans modifier encore les cards.
• Fichiers à créer/modifier
  • créer dmv-public/app/core/context-engine/registry/providerRegistry.ts
  • créer dmv-public/app/core/context-engine/resolvers/resolveContext.ts
  • modifier plus tard dmv-public/app/components/wall/context/WallContext.tsx pour déléguer progressivement au registry
• Risque
  • sur-abstraction trop tôt.
• Critères d’acceptation
  • le registry peut enregistrer des providers nommés ;
  • l’activation d’un provider dépend du contexte, pas de la page.

Étape 3 — Premier provider agenda

• Objectif
  • unifier la logique agenda actuellement partagée entre Wall et Mon espace.
• Fichiers à créer/modifier
  • créer dmv-public/app/core/context-engine/providers/agendaProvider.ts
  • réutiliser dmv-public/app/components/wall/selectors/agendaSelectors.ts
  • réutiliser dmv-public/app/components/wall/hooks/useWallAgendaInterests.ts
  • modifier plus tard dmv-public/app/components/mon-espace/MonEspaceAgendaBlock.tsx
  • modifier plus tard dmv-public/app/components/wall/components/secondary/WallSecondaryPagesContainer.tsx
• Risque
  • divergence entre agenda village et agenda personnel.
• Critères d’acceptation
  • même contrat agenda pour Mon espace et Wall ;
  • aucune régression UI ;
  • les intérêts agenda restent compatibles avec l’état actuel.

Étape 4 — Provider publications

• Objectif
  • normaliser la production des publications, alertes, événements et suivis.
• Fichiers à créer/modifier
  • créer dmv-public/app/core/context-engine/providers/publicationsProvider.ts
  • créer dmv-public/app/core/context-engine/resolvers/scoreAndSelect.ts
  • réutiliser dmv-public/app/components/wall/hooks/usePublications.ts
  • réutiliser dmv-public/app/components/wall/hooks/useFeaturedPublications.ts
  • réutiliser dmv-public/app/components/wall/hooks/useWallTargetedPublications.ts
  • réutiliser dmv-public/app/components/wall/selectors/publicationFeedSelectors.ts
• Risque
  • mélanger des règles MurVille avec un provider supposé neutre.
• Critères d’acceptation
  • les publications sortent sous forme de descripteurs homogènes ;
  • le provider ne contient pas de JSX ;
  • les priorités restent explicables.

Étape 5 — Branchement Mon espace

• Objectif
  • faire de Mon espace la première surface cliente du nouveau contrat.
• Fichiers à créer/modifier
  • modifier dmv-public/app/components/mon-espace/MonEspaceShell.tsx
  • modifier dmv-public/app/components/mon-espace/hooks/useMonEspaceVillages.ts
  • modifier dmv-public/app/components/mon-espace/hooks/usePersonalContext.ts
  • modifier dmv-public/app/components/mon-espace/MonEspaceTodaySummary.tsx
  • modifier dmv-public/app/components/mon-espace/MonEspaceAgendaBlock.tsx
  • modifier dmv-public/app/components/mon-espace/MonEspaceContexts.tsx
• Risque
  • casser l’équilibre actuel entre contexte personnel, village et acteur.
• Critères d’acceptation
  • Mon espace consomme des descripteurs ou blocs normalisés ;
  • le flux actor n’est plus un contournement isolé ;
  • aucun changement UX.

Étape 6 — Branchement MurVille

• Objectif
  • brancher MurVille sur les mêmes contrats après stabilisation de Mon espace.
• Fichiers à créer/modifier
  • modifier dmv-public/app/components/wall/WallEngine.tsx
  • modifier dmv-public/app/components/wall/context/WallContext.tsx
  • modifier dmv-public/app/components/wall/components/WallLayout.tsx
  • modifier dmv-public/app/components/wall/hooks/useWallMurVilleHostProps.ts
  • modifier dmv-public/app/components/wall/hooks/useWallMurVilleRuntime.ts
  • modifier dmv-public/app/components/wall/components/mur-ville/WallMurVilleHostContainer.tsx
• Risque
  • régression MurVille sur un périmètre déjà considéré comme sensible.
• Critères d’acceptation
  • parité MurVille préservée ;
  • aucune logique de sélection nouvelle directement dans le layout ;
  • le bridge MurVille peut commencer à s’alléger sans être supprimé trop tôt.

Étape 7 — Actions standardisées

• Objectif
  • normaliser ouvrir, suivre, ajouter agenda, appeler, itinéraire, puis compléter plus tard si partager et participer apparaissent réellement.
• Fichiers à créer/modifier
  • créer dmv-public/app/core/context-engine/types/action.ts
  • créer dmv-public/app/core/context-engine/adapters/wall/executeAction.ts
  • modifier dmv-public/app/components/wall/components/publications/WallPublicationCard.tsx
  • modifier dmv-public/app/[commune]/acteur/[slug]/ActorsClient.tsx
  • modifier dmv-public/app/components/mon-espace/MonEspaceActorFeed.tsx
• Risque
  • trop généraliser des actions encore incomplètes.
• Critères d’acceptation
  • un même type d’action a un contrat unique ;
  • les composants ne connaissent plus les RPC directement quand ce n’est pas nécessaire ;
  • partager et participer restent explicitement “non implémentés” si absents.

Étape 8 — API si nécessaire

• Objectif
  • déplacer seulement les morceaux dont la composition locale reste trop dupliquée.
• Fichiers à créer/modifier
  • créer plus tard api/app/Modules/Context/Controllers/ContextReadController.php
  • créer plus tard api/app/Modules/Context/Services/ContextReadService.php
  • créer plus tard api/app/Modules/Context/Routes/api.php
  • réévaluer les dépendances avec api/app/Modules/Publication/Services/PublicationReadService.php
  • réévaluer les dépendances avec api/app/Modules/Community/Services/CommunityReadService.php
• Risque
  • déplacer trop tôt au backend une logique encore instable.
• Critères d’acceptation
  • le contrat frontend est déjà stabilisé ;
  • l’API ne duplique pas une logique encore mouvante ;
  • le gain de mutualisation est démontré.

10. Recommandation finale

• Peut-on commencer à coder ?
  • oui ;
  • mais pas en construisant directement un “moteur complet”.
• Par quelle étape commencer ?
  • commencer par l’Étape 1 — Types communs ;
  • enchaîner avec l’Étape 2 — Registry minimal ;
  • puis brancher Mon espace avant MurVille.
• Ce qu’il ne faut surtout pas faire
  • ne pas commencer par refondre MurVille public ;
  • ne pas lancer un big bang Context Engine ;
  • ne pas réécrire les cards existantes avant d’avoir un contrat commun ;
  • ne pas déplacer toute la logique vers l’API avant d’avoir stabilisé le modèle frontend ;
  • ne pas confondre “sélection/priorisation” et “présentation UI”.

Synthèse finale

Le code existant n’est pas vide ni à refaire.

Il contient déjà :

• un noyau Wall exploitable ;
• des hooks proches de providers ;
• une vraie résolution de contexte dans Mon espace ;
• des cards réutilisables ;
• des sources API solides.

La bonne stratégie est donc :

• capitaliser sur l’existant ;
• extraire les contrats avant les refactors ;
• migrer par surface ;
• préserver MurVille jusqu’à la fin.