Océanie Pneus — Documentation POC Back-Office

1. Introduction

Ce POC (Proof of Concept) valide les fondations fonctionnelles, UX et architecturales du futur back-office centralisé Océanie Pneus. Il démontre comment piloter depuis une seule interface :

• un écosystème multi-marques et multi-entités (6 garages polynésiens) ;
• la création éditoriale de pages et de landings via un builder ;
• la configuration de funnels CRM et de formulaires dynamiques ;
• l'espace client pro (GED) avec documents synchronisés ;
• le monitoring d'activité (KPIs, intégrations, logs techniques).

L'objectif : valider le socle avant les intégrations réelles (Datacar, Tickee, paiement, planning). Pipedrive est déjà branché en conditions réelles : le flow complet Person + Lead + Note est opérationnel (il suffit d'ajouter le token). Les autres adaptateurs sont en place, prêts à recevoir les credentials.

2. Stack technique

3. Installation & démarrage

Le POC utilise l'environnement Docker existant du projet. Une fois cloné :

# Dépendances PHP
composer install

# Migrations (crée les 14 nouvelles tables POC)
php bin/console doctrine:migrations:migrate

# Données de démonstration
php bin/console app:poc:seed

# Build assets (dev)
yarn install
yarn encore dev --watch

# Build assets (prod)
yarn encore production

4. URLs du POC

Toutes les pages sont préfixées par la locale (fr, en, es).

5. Comptes de démonstration

Mot de passe unique : demo2025. Les 7 rôles métier du POC sont couverts.

6. Rôles métier

La hiérarchie est définie dans config/packages/security.yaml, la matrice d'accès aux modules dans App\Utilities\PocRoles::moduleAccess() et les règles fines dans App\Security\Voter\PocVoter.

Un rôle virtuel ROLE_POC_BACK_OFFICE est hérité par tous les rôles du back-office (SUPER_ADMIN, LOCAL_DIGITAL_ADMIN, MARKETING_GROUP, SALES_PRO, ENTITY_MANAGER, EDITOR, ADMIN). Il protège l'entrée /admin. Les accès fins par module sont gérés en deux couches :

• Menu : DashboardController::configureMenuItems() masque dynamiquement les sections non autorisées.
• CRUD : PocAdminAccessSubscriber intercepte BeforeCrudActionEvent et refuse l'accès direct par URL si le rôle n'est pas autorisé.
• Routes custom : chaque route du DashboardController appelle denyAccessForModule(...).

7. Les 17 modules du back-office

Accessibles depuis la sidebar EasyAdmin, groupés sous « POC Océanie Pneus ».

8. Guides rapides

A. Créer une landing en 5 minutes

1. Se connecter en digital.admin@oceaniepneus.com.
2. Ouvrir POC Océanie Pneus → Pages & Landings, cliquer sur « Créer ».
3. Renseigner titre, slug, marque, objectif, meta SEO ; enregistrer.
4. Cliquer sur le bouton « Ouvrir le Builder » (icône magic wand).
5. Dans la palette de gauche, ajouter un Hero, puis Texte+Image, puis Funnel, puis Promo. Configurer chaque bloc dans le panneau de droite.
6. Basculer entre Desktop / Mobile pour vérifier le rendu.
7. Revenir à la fiche et passer le statut à « Publié ».
8. Ouvrir le bouton « Prévisualiser » — la landing est en ligne sur /landing/{slug}.

B. Brancher un webhook réel (Zapier ou custom)

1. Créer un Zap (ou un endpoint custom) attendant un POST JSON.
2. Dans le back-office : POC Océanie Pneus → Funnels → Créer.
3. Choisir la cible CRM : Zapier ou Webhook générique.
4. Coller l'URL du hook dans le champ Webhook URL.
5. Renseigner tags, UTM par défaut, message de succès, landing associée.
6. Cliquer sur « Tester le funnel » : un payload de test est envoyé ; un FunnelEvent est créé (statut success / error / simulated).
7. Consulter Logs & Journal technique pour voir la requête, le code HTTP, la latence.
8. Associer ensuite ce funnel à un bloc Funnel dans une landing — les soumissions publiques remonteront automatiquement.

B-bis. Intégration réelle Pipedrive (5 min)

Cette intégration est production-ready : elle crée un Person + un Lead + une note structurée dans votre compte Pipedrive à chaque soumission.

1. Récupérer le token API : dans Pipedrive → Paramètres → Personnel → API → copier le token (32 car.).
2. Récupérer le sous-domaine : par ex. pour https://oceaniepneus.pipedrive.com c'est oceaniepneus.
3. Option A — Configuration globale (recommandée) : éditer .env.local :

   PIPEDRIVE_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   PIPEDRIVE_COMPANY_DOMAIN=oceaniepneus

   Puis php bin/console cache:clear.
4. Option B — Configuration par funnel : Funnels → éditer un funnel cible Pipedrive → renseigner Token API Pipedrive et Sous-domaine.
5. Valider la connexion : dans la liste des funnels, cliquer sur « Tester la connexion Pipedrive » → un message vert affiche "Connecté en tant que Jean Dupont — Océanie Pneus".
6. Tester un envoi complet : cliquer sur « Tester le tunnel » → un lead Démo POC apparaît dans Pipedrive, accessible depuis Logs & Journal → voir le détail → « Voir dans Pipedrive ».
7. Tester depuis le front : soumettre le formulaire d'une landing publique associée au funnel Pipedrive → lead créé instantanément.
8. Tester le ping : Pilotage → Intégrations → Pipedrive → Ping → statut connecté, latence réelle en millisecondes.

C. Onboarder un client pro

1. Créer l'utilisateur cible dans Utilisateurs avec le rôle ROLE_CLIENT_PRO.
2. Clients Pro → Créer l'entreprise (nom, SIRET, contact, représentant commercial).
3. Une fois sauvegardé, un dossier GED privé est automatiquement provisionné avec les permissions adéquates.
4. Ouvrir l'onglet Accès et ajouter l'utilisateur créé ; cocher « Notifier des nouveaux documents ».
5. Ajouter les documents initiaux via Documents Pro → Créer (type : facture, intervention, devis…). Un email est envoyé automatiquement aux destinataires opt-in.
6. L'utilisateur se connecte sur /espace-client, visualise, filtre et télécharge ses documents.

9. Matrice de permissions

La matrice est implémentée dans PocRoles::moduleAccess() et appliquée automatiquement au menu, aux CRUD EasyAdmin et aux routes custom. Les rôles héritent en cascade selon role_hierarchy.

Légende : ✓ module visible dans le menu et accessible — — aucun accès (menu masqué + 403 sur URL directe via PocAdminAccessSubscriber).

10. Architecture technique

10.1 Organisation du code

src/
├── Controller/
│   ├── Admin/
│   │   ├── DashboardController.php         # Menu POC + routes custom
│   │   └── Poc/                            # 13 CrudController EasyAdmin
│   ├── Api/Poc/
│   │   └── LandingBuilderApiController.php # API Vue Builder
│   └── Poc/
│       ├── LandingPublicController.php     # /landing/{slug}
│       └── EspaceClientController.php      # /espace-client
├── Entity/Poc/                             # 14 entités POC isolées
├── Repository/Poc/
├── Service/Poc/
│   ├── AnalyticsService.php
│   ├── BlockSchemaRegistry.php
│   ├── ClientProProvisioner.php
│   └── Crm/
│       ├── CrmAdapterInterface.php
│       ├── FunnelRouter.php
│       ├── MockAdapter.php
│       ├── WebhookAdapter.php
│       ├── ZapierAdapter.php
│       └── PipedriveAdapter.php
├── EventSubscriber/Poc/
│   ├── ClientProDocumentSubscriber.php     # Notif email auto
│   └── PocAdminAccessSubscriber.php        # Filtre l'accès aux CRUD
├── Security/
│   ├── AppAuthenticator.php                # Redirect post-login par rôle
│   └── Voter/PocVoter.php
├── Utilities/PocRoles.php                  # Rôles + moduleAccess()
└── Command/PocSeedCommand.php

assets/
├── poc-builder/                            # SPA Vue.js builder
│   ├── poc-builder.js
│   ├── poc-builder.scss
│   └── components/
│       ├── BuilderApp.vue
│       ├── BlockPalette.vue
│       ├── Canvas.vue
│       ├── ConfigPanel.vue
│       ├── DeviceToggle.vue
│       └── blocks/*.vue                    # 9 composants d'aperçu
├── poc-landing/                            # Styles page publique
└── poc/                                    # Theming admin

templates/
├── admin/poc/                              # Dashboard, analytics, logs, planning, settings, integrations…
├── security/
│   ├── _auth_layout.html.twig              # Layout brandé login/mdp
│   └── login.html.twig
├── home_page/poc_landing.html.twig         # Landing publique /
└── poc/
    ├── landing_public.html.twig
    ├── blocks/_*.html.twig                 # 9 partials de rendu
    └── espace_client/home.html.twig

10.2 Adapter pattern CRM

Chaque cible CRM implémente CrmAdapterInterface::send(Funnel $f, array $payload): AdapterResult. Le service FunnelRouter résout l'adapter à partir de funnel.crmTarget et journalise systématiquement un FunnelEvent.

// src/Service/Poc/Crm/FunnelRouter.php
public function route(Funnel $funnel, array $payload, ?Landing $landing = null): AdapterResult
{
    $adapter = $this->adapters[$funnel->getCrmTarget()] ?? $this->mockAdapter;
    $start   = microtime(true);
    $result  = $adapter->send($funnel, $payload);

    $this->logEvent($funnel, $landing, $adapter, $result, $payload, $start);

    return $result;
}

10.3 Builder & schémas

Les blocs sont décrits de façon déclarative dans BlockSchemaRegistry. Le front Vue récupère ces schémas via l'API et génère dynamiquement les formulaires de configuration — aucun code front à modifier pour ajouter un champ. Le drag & drop utilise vuedraggable (groupe partagé poc-blocks) pour ajouter depuis la palette (clone) et réordonner dans le canvas.

10.4 Sécurité — 3 couches

1. Firewall & access_control dans security.yaml : /admin exige ROLE_POC_BACK_OFFICE (virtuel, hérité par tous les rôles BO), /espace-client exige ROLE_CLIENT_PRO.
2. Menu dynamique : DashboardController::configureMenuItems() masque les sections non autorisées via userCan() + PocRoles::moduleAccess().
3. CRUD & routes : PocAdminAccessSubscriber bloque les 13 CRUD POC sur BeforeCrudActionEvent ; chaque route custom du Dashboard appelle denyAccessForModule().

PocVoter reste disponible pour des décisions fines (POC_VIEW, POC_EDIT, POC_PUBLISH, POC_MANAGE_USERS, POC_MANAGE_INTEGRATIONS, POC_VIEW_ANALYTICS) — à activer ponctuellement dans les contrôleurs qui en auront besoin en V1.

10.5 Authentification & redirection

AppAuthenticator::resolveDefaultRedirect() oriente chaque utilisateur au bon endroit après login :

• Back-office (SUPER_ADMIN, LOCAL_DIGITAL, MARKETING, SALES, ENTITY_MGR, EDITOR, ADMIN) → poc_dashboard
• CLIENT_PRO → poc_espace_client_home
• TECHNICIEN → app_survey_access
• Autre → File Manager utilisateur

La page de login /login utilise un layout _auth_layout.html.twig partagé (split-screen, hero brandé orange/bleu, formulaire carte).

11. Recommandations pour la V1

1. Migration DB & environnements. Isoler chaque marque sur son schéma de settings (déjà ébauché avec Brand). Ajouter environnements staging + preview par branche.
2. Intégrations réelles. Remplacer les adapters mock par des implémentations authentifiées. Mettre en place un queue / retry (Symfony Messenger) pour les envois CRM et les imports Datacar/Tickee.
3. Builder V2. Passer le builder en Vue 3 + Composition API ; ajouter drag & drop réel (Sortable.js), historique undo/redo, brouillons auto-sauvegardés, bibliothèque de templates par marque.
4. Moteur de permissions. Persister une matrice rôles × modules × actions configurable en BO (plutôt que hard-codée dans le Voter). Ajouter un scope entity-based (un manager ne voit que son garage).
5. Moteur de booking. Remplacer AppointmentMock par un vrai provider (Cal.com, Tickee ou custom) avec synchronisation bidirectionnelle.
6. Paiement. Choisir le provider (Stripe / OSB). Prévoir webhooks, tokenisation, export comptable.
7. Observabilité. Remplacer les Logs custom par Monolog + Sentry + Grafana. Exposer des métriques Prometheus pour latence CRM et erreurs webhooks.
8. Perf & SEO. Ajouter un cache HTTP (Varnish) sur les landings publiées, générer les sitemap.xml par marque, implémenter JSON-LD LocalBusiness via SeoLocal.schemaOrg.
9. Tests. Couverture prioritaire : Voter, FunnelRouter, adapters, API Builder, sécurisation /espace-client. Ajouter tests E2E Playwright sur parcours critiques.
10. Devops. CI/CD sur GitHub Actions (lint PHPStan, Rector, ESLint, tests). Environnements Docker reproductibles, secrets via Vault.

12. Périmètre du POC

Dans le POC

• Socle multi-marques / multi-entités avec données réelles en base.
• Builder de landings fonctionnel de bout en bout (admin → publication → consultation publique).
• Moteur de funnels avec 4 adapters (mock, webhook, Zapier, Pipedrive).
• Espace client pro (back + front) avec GED et notifications.
• Dashboard, logs, planning, SEO, intégrations, theming.

Hors POC (roadmap V1)

• Connexions réelles Datacar, Tickee, Pipedrive (credentials requis).
• E-commerce complet (panier, paiement, gestion stock live).
• Moteur de booking de rendez-vous en production.
• Durcissement sécurité (2FA, audit log complet, IAM fin).
• DevOps de production (CI/CD, monitoring, HA, backups).

13. Changelog du POC

Version 1.2 — intégration Pipedrive réelle + UX builder

• Catalogue de champs du bloc Tunnel CRM : UI claire avec cases à cocher groupées (Contact / Qualification / Message), badge « Obligatoire », badge type (Email / Tél / Texte / Zone de texte), mapping visible vers le CRM (Person.name, Person.email, Lead.note…) et réordonnancement par flèches.
• Preview enrichie du bloc Tunnel CRM dans le canvas : rendu WYSIWYG des champs sélectionnés avec libellés et placeholders, badge ✱ pour les champs obligatoires.
• Mention légale configurable depuis le builder (champ legalNotice).
• Intégration Pipedrive production-ready : flow complet findOrCreatePerson (dédup par email) → createLead (avec value, person_id) → createNote (HTML structurée avec UTM, source landing, timestamp).
• Nouveau service PipedriveClient (wrapper API v1) : ping(), findPersonByEmail(), createPerson(), createLead(), createNote(), buildLeadUrl().
• Variables d'environnement PIPEDRIVE_TOKEN & PIPEDRIVE_COMPANY_DOMAIN (fallback global, override par funnel possible).
• Nouveau champ pipedriveCompanyDomain sur Funnel pour générer des URLs cliquables vers les leads.
• Action « Tester la connexion Pipedrive » sur les funnels Pipedrive (ping réel /users/me, affiche nom + société).
• Ping réel dans Pilotage → Intégrations → Pipedrive (latence réelle, statut, message).
• Lien cliquable « Voir dans Pipedrive » depuis chaque FunnelEvent réussi.
• Mode simulated préservé si aucun token (ne casse jamais la démo).

Version 1.1 — itérations UX & sécurité

• Landing publique brandée sur / (hero, 3 marques, 8 services, contact, footer) — remplace la page vide.
• Page de login stylisée (split-screen Océanie Pneus, logo, couleurs orange/bleu marine) — layout partagé pour login, mot de passe oublié, initialisation.
• Logo Océanie Pneus dans le header EasyAdmin + favicon.
• Redirection post-login automatique selon le rôle (back-office → dashboard POC, client pro → espace client, etc.).
• Rôle virtuel ROLE_POC_BACK_OFFICE hérité par tous les rôles BO pour unifier l'accès à /admin.
• Menu back-office dynamique selon le rôle connecté (via PocRoles::moduleAccess()).
• PocAdminAccessSubscriber : protection des 13 CRUD POC par rôle même en accès URL direct.
• Page Analytics dédiée (taux de succès, latence moyenne, répartition adapter/statut, top funnels, top landings).
• Drag & drop dans le builder (palette → canvas, réordonnancement).
• Panneaux sticky dans le builder (palette, config).
• Nouveau compte démo garage@oceaniepneus.com (ROLE_ENTITY_MANAGER).
• Accès builder/médiathèque élargi aux rôles BO (plus uniquement ROLE_ADMIN).
• Corrections : chart dashboard (hauteur infinie), array_flip sur Documents Clients, utilisateurs BO null, bouton Retour builder.

Version 1.0 — livraison initiale

• 14 entités Doctrine POC, repositories & fixtures.
• 17 modules back-office EasyAdmin.
• Builder Vue.js 2.6 SPA avec 9 blocs, schémas dynamiques, aperçu multi-device.
• 4 adapters CRM (mock, webhook, Zapier, Pipedrive) + FunnelRouter.
• Espace client pro (front + back) avec GED et notifications email.
• Dashboard, logs, planning kanban, SEO local (SERP preview), intégrations (7 connecteurs).
• Theming admin Océanie Pneus (SCSS dédié).
• Documentation HTML & README.