# Démarrage rapide — Walk The Line Management **Version : V16.11.16** Guide d'installation, exploitation, diagnostic et premiers réglages. ## 1. Prérequis ### Développement Docker recommandé - Docker Desktop récent ; - Docker Compose v2 ; - Git. ### Installation PHP native / production - PHP 8.2+ ; - Composer ; - MariaDB/MySQL compatible ; - extensions PDO, `zip`/`ZipArchive`, `ctype`, `iconv` ; - serveur web Apache ou Nginx. Le projet utilise notamment `symfony/mime`. Vérification : ```bash php -v composer --version php -m ``` --- ## 2. Démarrage local avec Docker Depuis la racine : ```bash docker compose up -d --build ``` Accès : - application : `http://127.0.0.1:8080` - phpMyAdmin : `http://127.0.0.1:8888` - MariaDB exposée localement : port `3310` Le compose utilise des volumes Docker natifs pour `vendor/` et `var/` afin d'améliorer les performances sous Windows. Après un changement important de l'image Docker : ```bash docker compose down docker compose build --no-cache web docker compose up -d ``` --- ## 3. Commandes Symfony dans Docker Exécuter une commande : ```bash docker compose exec web php bin/console ``` Exemples : ```bash docker compose exec web php bin/console cache:clear docker compose exec web php bin/console doctrine:migrations:migrate docker compose exec web php bin/console doctrine:schema:validate ``` --- ## 4. Installation Composer hors Docker ```bash composer install ``` En production : ```bash composer install --no-dev --optimize-autoloader ``` Ne pas utiliser `composer update` lors d'un déploiement normal. --- ## 5. Variables d'environnement Créer/configurer `.env.local` ou les variables du serveur. Minimum : ```dotenv APP_ENV=prod APP_DEBUG=0 APP_SECRET=VOTRE_SECRET_ALEATOIRE DATABASE_URL="mysql://..." ``` Générer un secret : ```bash php -r "echo bin2hex(random_bytes(32)).PHP_EOL;" ``` Ne jamais versionner les secrets réels. ### reCAPTCHA global de la connexion La protection reCAPTCHA du formulaire `/login` est globale à l'application et indépendante des projets. Configurez les deux variables dans `.env.local` ou dans l'environnement du serveur : ```dotenv LOGIN_RECAPTCHA_SITE_KEY=VOTRE_CLE_PUBLIQUE LOGIN_RECAPTCHA_SECRET_KEY=VOTRE_CLE_PRIVEE ``` Les mêmes clés Google peuvent être utilisées que pour un site public, mais elles doivent autoriser tous les domaines depuis lesquels le login est servi. Si l'une des deux variables est vide, le contrôle reCAPTCHA du login n'est pas activé ; les protections par limitation des tentatives et blocage IP restent applicables. Ce réglage ne remplace pas les configurations reCAPTCHA propres aux projets, utilisées uniquement par leurs formulaires publics. Le login ne choisit jamais les clés d'un projet en fonction du domaine, de la session ou de l'ordre en base. --- ## 6. Base de données Créer la base si nécessaire : ```bash php bin/console doctrine:database:create ``` Appliquer les migrations : ```bash php bin/console doctrine:migrations:migrate ``` En Docker : ```bash docker compose exec web php bin/console doctrine:migrations:migrate ``` --- ## 7. Contrôle Doctrine après mise à jour Toujours vérifier : ```bash php bin/console doctrine:schema:validate php bin/console doctrine:schema:update --dump-sql ``` Résultat attendu : ```text Mapping ------- [OK] Database -------- [OK] ``` puis : ```text [OK] Nothing to update ``` **Ne pas utiliser `doctrine:schema:update --force` en production.** Les évolutions du schéma doivent passer par les migrations. --- ## 8. Créer un utilisateur ```bash php bin/console app:create-user EMAIL MOT_DE_PASSE --role=ROLE_ADMIN --name="Nom" ``` Exemple : ```bash php bin/console app:create-user admin@example.com "MotDePasseSolide" --role=ROLE_ADMIN --name="Administrateur" ``` Créer directement un super administrateur : ```bash php bin/console app:create-user admin@example.com "MotDePasseSolide" --role=ROLE_ADMIN --name="Administrateur" --super-admin ``` Promouvoir : ```bash php bin/console app:user:super-admin admin@example.com ``` Retirer : ```bash php bin/console app:user:super-admin admin@example.com --disable ``` --- ## 9. Gérer les groupes, permissions et projets d'un utilisateur Dans le back-office : ```text Administration → Utilisateurs Administration → Groupes & permissions ``` Ces fonctions sont réservées au super administrateur. ### Matrice Dans `Groupes & permissions`, chaque colonne représente un groupe et chaque ligne une fonction. Cliquer sur une cellule fait évoluer le niveau : ```text Aucun → Lecture → Lecture / écriture → Lecture / écriture / suppression → Aucun ``` Le cycle s'arrête plus tôt pour les fonctions dont le niveau maximal est Lecture ou Écriture. Groupes système initiaux : - Administrateur projet ; - Prospecteur ; - Technique ; - Trésorier ; - Lecture seule. Vous pouvez créer des groupes personnalisés. Un groupe système peut être reconfiguré mais pas supprimé. ### Affectation d'un utilisateur Dans `Administration → Utilisateurs` : - activer/désactiver le compte ; - modifier identité/mot de passe ; - sélectionner un ou plusieurs groupes ; - sélectionner les projets accessibles ; - promouvoir/retirer le statut super administrateur. Les permissions de plusieurs groupes se cumulent : pour chaque fonction, le niveau le plus élevé est retenu. Pour le module **Bilans de représentation**, attribuez la permission dédiée : - **Lecture** permet de consulter les bilans, indicateurs et exports du ou des projets autorisés ; - **Lecture / écriture** permet aussi de créer et modifier un bilan ; - la suppression physique reste réservée au super administrateur. Le projet d'un bilan est toujours celui de sa date de représentation. Il n'existe aucun réglage permettant de rendre un bilan transversal à l'association. Le super administrateur a toujours : - tous les droits ; - tous les projets ; - accès aux utilisateurs, groupes, projets et maintenance. ### Test recommandé Créez un compte de test `Prospecteur`, affectez-le à un seul projet puis vérifiez : 1. que le sélecteur ne liste que ce projet ; 2. que le menu ne montre que les fonctions permises ; 3. que `Factures = Aucun` masque les factures et les factures à encaisser du dashboard ; 4. que `Paiements = Aucun` masque les actions d'encaissement ; 5. qu'une URL interdite renvoie un refus d'accès ; 6. qu'un compte sans aucune permission back-office revient au login avec un message explicite. --- ## 10. Première connexion Connexion : ```text http://127.0.0.1:8080/login ``` Après connexion : 1. vérifier le projet actif ; 2. vérifier l'identité de l'association ; 3. vérifier les lieux/contacts existants ; 4. vérifier les paramètres du projet ; 5. configurer la comptabilité avant usage réel. --- ## 11. Multi-projet : premier paramétrage Un super administrateur ouvre : ```text Administration → Projets artistiques ``` Puis : 1. `Nouveau projet` ; 2. lire le préambule ; 3. créer le projet en brouillon ; 4. compléter identité et couleurs ; 5. adapter tarifs et frais ; 6. adapter technique, profils, patch, matériel, accueil ; 7. sélectionner/ajouter les éléments scéniques ; 8. créer les plans utiles ; 9. compléter la préparation du site public ; 10. vérifier les trois états de complétude. Le wizard peut être quitté et repris. --- ## 12. Projet actif Utiliser : ```text Barre latérale → Changer de projet ``` Toujours vérifier le projet avant : - prospection ; - tarif ; - date ; - fiche technique ; - plan ; - paramétrage projet. Les lieux/contacts et la comptabilité restent communs à l'association. --- ## 13. Comptabilité : paramétrage initial Ouvrir : ```text Association · Finances → Comptabilité ``` Puis configurer les paramètres comptables. À renseigner en priorité : - date de début comptable de l'association ; - comptes financiers ; - date d'ouverture de chaque compte ; - obligation ou non d'un relevé mensuel ; - régime TVA et sa date d'effet si applicable. Le logiciel crée automatiquement les exercices et périodes nécessaires. --- ## 14. Comptes financiers Exemples : - compte bancaire principal ; - compte SumUp ; - caisse espèces. Pour chaque compte, vérifier : - type ; - date d'ouverture ; - date de fermeture éventuelle ; - suivi des relevés mensuels. Aucun relevé ne doit être considéré manquant avant la date d'ouverture du compte ou avant le début comptable de l'association. --- ## 15. Dépenses / prestations Menu : ```text Association · Finances → Dépenses ``` À la création : 1. date ; 2. libellé ; 3. fournisseur ; 4. catégorie ; 5. HT ou TTC ; 6. taux de TVA ; 7. TVA déductible si nécessaire ; 8. projet ou Association/commun ; 9. compte ; 10. moyen/date de paiement ; 11. justificatif obligatoire. Le justificatif est automatiquement classé dans la GED comptable. Une ancienne ligne `Manquant` peut être régularisée avec `Ajouter justificatif`. --- ## 16. Factures et paiements Les factures sont générées depuis un devis. Lors de la génération : - PDF immuable ; - classement automatique dans la GED comptable. Paiement possible depuis : - fiche facture ; - `Devis & factures` ; - prospection si facture réelle ; - dashboard projet ; - dashboard comptabilité. Statuts : - À encaisser ; - Partiellement payée ; - Payée. Les paiements sont modifiables/supprimables en cas d'erreur. --- ## 17. Vente merch. Menu : ```text Association · Finances → Vente merch. ``` Saisir : - date ; - projet ; - total TTC ; - TVA comprise ; - compte ; - moyen de paiement ; - frais prestataire éventuels. Exemple SumUp : - vente brute : +200 € ; - frais SumUp : -3,50 € ; - net : 196,50 €. --- ## 18. Recettes exceptionnelles Menu : ```text Association · Finances → Recettes exceptionnelles ``` Pour : - don ; - cotisation ; - subvention ; - remboursement ; - autre recette non issue d'une facture ou du merchandising. --- ## 19. Contrats / sous-traitance Menu : ```text Association · Finances → Contrats / sous-traitance ``` La création peut inclure : - contrat ; - devis prestataire ; - facture prestataire. Les documents sont automatiquement classés dans la GED comptable. Des pièces peuvent être ajoutées ultérieurement. --- ## 20. GED comptable Menu : ```text Association · Finances → GED comptable ``` Vue : ```text 2026 └── Août ├── Factures émises ├── Justificatifs dépenses ├── Relevés bancaires / SumUp ├── Factures fournisseurs ├── Devis prestataires ├── Contrats / sous-traitance ├── Assurances / échéanciers ├── TVA / déclarations └── Autres pièces ``` Les dossiers sont repliables et la recherche est instantanée. Ne réuploadez jamais une facture générée par l'application : elle est ajoutée automatiquement. --- ## 21. TVA Le régime TVA est daté afin de conserver l'historique. Exemple : ```text 01/01/2026 → 30/06/2028 : non applicable 01/07/2028 → ... : réel normal mensuel ``` L'assistant TVA présente une estimation des montants par période. Il sert à préparer les chiffres, pas à remplacer la vérification de la déclaration officielle. --- ## 22. Import / export des lieux et contacts Disponible au super administrateur : ```text Administration → Maintenance ``` Fonctions : - export XLSX ; - modèle vide ; - prévisualisation ; - import création + mise à jour ; - import création seule ; - historique. `ZipArchive` doit être actif. --- ## 23. Cache Docker : ```bash docker compose exec web php bin/console cache:clear ``` Installation native : ```bash php bin/console cache:clear ``` Production : ```bash php bin/console cache:clear --env=prod php bin/console cache:warmup --env=prod ``` --- ## 24. Déploiement production conseillé ```bash git pull composer install --no-dev --optimize-autoloader php bin/console doctrine:migrations:migrate --no-interaction --env=prod php bin/console cache:clear --env=prod php bin/console cache:warmup --env=prod php bin/console doctrine:schema:validate --env=prod php bin/console doctrine:schema:update --dump-sql --env=prod ``` Résultat final attendu : - mapping OK ; - base synchronisée ; - `Nothing to update`. La migration `Version20260920140000` crée la table des bilans avec une contrainte unique par date et une clé étrangère `ON DELETE RESTRICT`. La migration additive `Version20260920143000` aligne ensuite les trois noms d'index générés par les relations avec le mapping Doctrine. Elle précontrôle la totalité des index avant son unique `ALTER TABLE` et peut être rejouée sur un environnement où les noms seraient déjà alignés. La migration `Version20260921100000` rend toutes les réponses du questionnaire facultatives sans modifier les bilans existants ; elle vérifie la structure réelle de chaque colonne avant son unique `ALTER TABLE`. Après déploiement, attribuez explicitement la permission **Bilans de représentation** aux groupes concernés. Aucun import historique n'est requis. ### Installation mobile du back-office (PWA) Le back-office fournit `public/manifest.webmanifest` et un service worker réseau uniquement. Il peut être ajouté à l'écran d'accueil depuis Chrome sur Android ou depuis **Partager → Sur l'écran d'accueil** dans Safari sur iPhone. Conditions de déploiement : - servir l'application en HTTPS (hors exception navigateur pour `localhost`) ; - rendre accessibles `/manifest.webmanifest`, `/service-worker.js`, `/js/pwa.js` et `/images/logo-wtl-black.png` ; - ne pas réécrire ces fichiers statiques vers une page HTML ; - conserver la portée du service worker sur `/admin`. Cette installation ne fournit pas de mode hors ligne. Le service worker ne crée aucun cache et ne stocke ni page métier, ni réponse, ni donnée personnelle. En cas d'échec réseau, l'utilisateur doit retrouver la connexion puis réessayer depuis la page courante. Contrôle recommandé dans les outils de développement du navigateur : le manifeste doit être reconnu, le service worker actif avec la portée `/admin`, et les stockages **Cache Storage** rester vides après navigation dans le back-office. --- ## 25. Apache sans apache-pack Le projet peut utiliser un `.htaccess` manuel dans `public/`. Vérifier : - `mod_rewrite` ; - `mod_headers` si `X-Robots-Tag` est utilisé ; - `AllowOverride All` dans le VirtualHost. Pour empêcher temporairement l'indexation : `public/robots.txt` : ```text User-agent: * Disallow: / ``` et en `.htaccess` : ```apache Header set X-Robots-Tag "noindex, nofollow, noarchive, nosnippet" ``` --- ## 26. Diagnostic rapide ### Symfony ne démarre pas en prod / secret vide Vérifier : ```bash php bin/console debug:container --parameter=kernel.secret --env=prod ``` `APP_SECRET` doit être non vide. ### Mapping Doctrine ```bash php bin/console doctrine:schema:validate php bin/console doctrine:schema:update --dump-sql ``` ### Routes ```bash php bin/console debug:router ``` ### Services ```bash php bin/console debug:container ``` ### Import XLSX ```bash php -m | grep -i zip composer show symfony/mime ``` --- ## 27. Reset des données de démonstration Réservé au super administrateur : ```text Administration → Maintenance ``` La confirmation exige : ```text RESET ``` Ne jamais utiliser cette fonction sur une base réelle sans avoir validé précisément son périmètre. --- ## 28. Documents de référence - `SPECIFICATIONS_FONCTIONNELLES.md` : modèle métier et règles fonctionnelles détaillées ; - `demarrage_rapide.md` : installation, exploitation et procédures techniques ; - bouton **Manuel utilisateur** du dashboard : aide orientée utilisateur non technique. --- ## 18. Google Analytics 4 — suivi du site public et tableau de bord La configuration est propre à chaque projet artistique et se fait dans : ```text Projet → Site public & communications → Google Analytics 4 ``` ### 18.1 Créer la propriété Google Analytics 1. Ouvrir Google Analytics et aller dans **Administration**. 2. Cliquer sur **Créer → Propriété**. 3. Donner un nom explicite, par exemple `Walk The Line — Site public`. 4. Choisir le fuseau horaire adapté au projet (pour Walk The Line : `France / Europe-Paris`) et la devise souhaitée. 5. Créer ensuite un **flux de données Web** avec le domaine public, par exemple `https://walktheline.fr`. 6. Ouvrir ce flux et copier l'**ID de mesure** au format : ```text G-XXXXXXXXXX ``` Cet ID est utilisé par `gtag.js` pour envoyer les données de fréquentation. Le site ne charge la balise qu'après le consentement du visiteur. ### 18.2 Récupérer l'ID de propriété Dans Google Analytics, ouvrir la propriété puis **Administration → Détails de la propriété** et relever l'identifiant numérique, par exemple : ```text 123456789 ``` Dans le back-office, saisir uniquement le nombre, sans `properties/`. ### 18.3 Activer Google Analytics Data API Le tableau de bord du back-office lit les données via l'API Google Analytics Data. 1. Ouvrir Google Cloud Console. 2. Créer ou sélectionner un projet Google Cloud dédié. 3. Aller dans **API et services → Bibliothèque**. 4. Rechercher **Google Analytics Data API**. 5. Activer l'API. L'application utilise directement l'API REST ; aucun SDK Google supplémentaire n'est requis par Composer. ### 18.4 Créer le compte de service 1. Dans Google Cloud : **IAM et administration → Comptes de service**. 2. Créer un compte de service dédié, par exemple `wtl-analytics-reader`. 3. Ouvrir ce compte de service puis **Clés → Ajouter une clé → Créer une clé → JSON**. 4. Télécharger le fichier JSON une seule fois. 5. Y récupérer : - `client_email` ; - `private_key`. 6. Reporter ces deux valeurs dans le back-office. La clé privée est chiffrée en base par l'application. Ne jamais versionner ni transmettre le fichier JSON. ### 18.5 Donner au compte de service l'accès à la propriété GA4 Dans Google Analytics : 1. **Administration → Gestion des accès à la propriété**. 2. Cliquer sur **+ → Ajouter des utilisateurs**. 3. Saisir l'adresse `client_email` du compte de service. 4. Donner le rôle **Lecteur**. 5. Enregistrer. Le rôle Lecteur suffit pour les rapports affichés dans le tableau de bord. ### 18.6 Renseigner le back-office Dans **Projet → Site public & communications → Google Analytics 4** : - activer **Google Analytics** ; - renseigner l'ID de mesure `G-...` ; - renseigner l'ID numérique de propriété ; - renseigner l'e-mail du compte de service ; - coller la clé privée ; - enregistrer ; - cliquer sur **Tester la connexion Analytics**. Si la configuration de reporting est complète, le tableau de bord affiche les données des 7 derniers jours : - utilisateurs actifs ; - sessions ; - pages vues ; - taux d'engagement ; - cinq pages les plus consultées. ### 18.7 Consentement et confidentialité Lorsque Google Analytics est activé, le site public affiche un bandeau de consentement. Le Consent Mode commence à `denied` et la balise `gtag.js` n'est chargée qu'après acceptation. Le choix du visiteur est conservé dans son navigateur et peut être rouvert via le bouton **Cookies**. Un refus après acceptation prend effet sans rechargement : les nouveaux événements sont bloqués, le consentement Analytics repasse à `denied` et les cookies `_ga*` accessibles sont supprimés dans la mesure permise par le navigateur. Une réacceptation sur la même page ne doit ni charger deux fois la balise ni créer une seconde page vue. La politique de confidentialité publique adapte automatiquement son texte selon que Google Analytics est activé ou non. ### 18.8 Diagnostic Si **Tester la connexion Analytics** échoue, vérifier dans cet ordre : 1. ID de propriété correct ; 2. Google Analytics Data API activée dans le bon projet Google Cloud ; 3. adresse du compte de service correcte ; 4. clé privée complète, y compris `BEGIN PRIVATE KEY` / `END PRIVATE KEY` ; 5. compte de service ajouté à la propriété Analytics avec le rôle Lecteur ; 6. heure système du serveur correcte, car le jeton OAuth signé dépend de l'horloge.