Développement local

En bref

Ce guide explique comment faire tourner la plateforme sur un poste de développeur en quelques minutes, et comment éviter les pièges qui coûtent une journée. Il concerne surtout les développeurs ; un PO y trouve ce qu’on peut tester en local et ce qui ne marche pas. À retenir : en local, les emails ne partent pas, ils s’écrivent dans un fichier journal, et un paiement n’aboutit que lorsque Stripe prévient la plateforme.

Fonctionnement

En local, la plateforme tourne dans des conteneurs Docker : l’application, la base de données, deux services de mémoire rapide (Redis et Memcached, installés avec l’environnement local). On a besoin de Docker, de Node 24 et de Composer 2 sur la machine.

Par rapport à la production, trois choses changent :

• Emails. Aucun email réel n’est envoyé. Chaque message est écrit dans le fichier journal de l’application. Les liens de connexion (courtiers et clients) y sont lisibles, signés, à usage unique et valables 30 minutes (24 heures pour un lien de bienvenue).
• Services externes. On ne renseigne que ce qu’on touche : Stripe en clés de test pour les paiements, les registres d’entreprises pour la recherche, le monitoring pour le scan. Une intégration non configurée échoue au moment où on l’utilise, pas au démarrage. Liste complète : Secrets et clés. Les notifications Slack restent désactivées. Sans clé anti-robot, la vérification est simplement coupée.
• Données de démonstration. Le remplissage initial crée la liste des pays (obligatoire), trois comptes admin avec un mot de passe de développement, puis, hors production, un dossier complet : demande, offre acceptée, police et paiement réglé. Les admins se connectent sur une page volontairement cachée, hors de l’espace admin. Courtiers et clients passent par les liens du journal.

Simuler un paiement

Cliquer sur « payer » ouvre seulement une session de paiement chez Stripe. L’offre passe à acceptée quand Stripe prévient la plateforme, jamais au clic (voir offre acceptée au paiement). Deux options :

• Stripe en mode test envoie ses notifications à ta machine, ce qui oblige à l’exposer ou à relayer le trafic.
• Tu envoies toi-même un faux message : hors production, l’absence de clé de vérification est tolérée ; en production elle fait refuser la notification.

La chaîne complète est : session de paiement terminée, abonnement créé, facture payée, puis émission automatique de la police. Voir Paiements.

Pour les développeurs : démarrage

cp .env.example .env && composer install && vendor/bin/sail up -d
vendor/bin/sail artisan key:generate && vendor/bin/sail artisan migrate --seed
yarn install && yarn dev
vendor/bin/sail artisan test --compact --filter=Something
vendor/bin/sail bin pint --dirty --format agent

• Toute commande PHP, Artisan, Composer et Node passe par vendor/bin/sail.
• Le fichier modèle .env.example est calé sur la production : à adapter pour la base (DB_CONNECTION=pgsql, DB_HOST=pgsql, nom, utilisateur, mot de passe, APP_URL) et pour les emails (MAIL_MAILER=log, à suivre avec vendor/bin/sail artisan pail).
• Clés par fonctionnalité : STRIPE_KEY, STRIPE_SECRET, STRIPE_WEBHOOK_SECRET (paiements) ; PAPPERS_API_KEY, CBEAPI_API_KEY, CBEAPI_SECRET_KEY (registres) ; MONITORING_API_URL, MONITORING_API_TOKEN (scan) ; PASSPORT_PRIVATE_KEY, PASSPORT_PUBLIC_KEY, MCP_ALLOW_LOOPBACK_REDIRECTS (connexion de l’assistant IA).
• Connexion admin : /ops-k7q/login. Un seed à part existe pour le bordereau (BordereauTestSeeder, avec --class).
• Formes des faux messages Stripe : tests/Support/StripeWebhookPayloadFactory.php.

Règles et pièges

• Les tâches planifiées et les files d’attente ne tournent pas seules en local : lance-les à la main (voir les commandes plus bas).
• Les dépendances du front existent en deux versions : Yarn pour la production, npm pour l’intégration continue (la vérification lancée à chaque modification). Garde-les synchronisées.
• Ne lance jamais l’installation npm dans le conteneur : les dossiers sont partagés avec ta machine et les programmes natifs seraient remplacés.
• L’outil de debug Telescope n’existe qu’en environnement local.
• Les tests navigateur ne tournent qu’en local, jamais dans l’intégration continue. Oublier de compiler le front donne des pages blanches ; Stripe y est simulé ; ils utilisent une base temporaire, jamais ta base de développement.

Pour les développeurs : tâches planifiées et files d’attente

vendor/bin/sail artisan schedule:work
vendor/bin/sail artisan horizon   # ou queue:work si QUEUE_CONNECTION n'est pas redis

Pour les développeurs : tests navigateur

1. Installer le navigateur de test une fois, et après toute réinstallation npm ou reconstruction du conteneur : vendor/bin/sail root-shell -c 'cd /var/www/html && node node_modules/playwright/cli.js install --with-deps chromium'.
2. Compiler le front sur ta machine : npm run build.
3. Lancer : vendor/bin/sail artisan test --compact tests/Browser.

Où dans le code

• compose.yaml, .env.example
• database/seeders/DatabaseSeeder.php
• tests/Pest.php (configuration des tests navigateur)

Questions ouvertes

• L’usage de l’outil Stripe en ligne de commande (stripe listen) n’apparaît que dans des guides génériques de l’agent, pas dans le README ni dans la documentation du projet.