Architecture

Ce document décrit l'organisation technique de BCard : modèle de données, rôles, découpage du code et principaux parcours métier.

---

Vue d'ensemble

BCard est une application Symfony 7 monolithique qui expose trois surfaces :

Surface	Préfixe	Authentification
Site public et espace connecté (Twig)	/	Session, formulaire de connexion, OAuth Google/Facebook
Back-office	/admin	Session + rôles applicatifs
API REST JSON	/api	JWT (stateless pour login_check)

Les trois partagent le même modèle de données, les mêmes entités Doctrine et les mêmes services métier. Le pare-feu main gère les deux premières, le pare-feu api protège la troisième.

---

Rôles applicatifs

Rôle	Porté par	Périmètre
ROLE_USER	Tout compte particulier	Ses cartes, ses contacts, ses commandes
ROLE_EMPLOYEE	Employé rattaché à une entreprise	La carte qui lui est affectée
ROLE_MANAGER	Responsable d'une entreprise	Employés, cartes et commandes de son entreprise
ROLE_SUPPORT	Équipe support	Consultation des clients, assistance
ROLE_OPERATOR	Équipe opérations	Traitement des commandes et des cartes
ROLE_ADMIN	Administrateur	Back-office complet
ROLE_SUPER_ADMIN	Administrateur principal	Idem, avec les opérations les plus sensibles
ROLE_USER_DELETED	Compte supprimé	Marqueur d'anonymisation, exclu des listes

La suppression de compte n'efface pas la ligne en base : l'utilisateur est marqué ROLE_USER_DELETED et exclu des requêtes de listing, afin de préserver l'intégrité référentielle des commandes et des paiements.

---

Modèle de données

Utilisateurs et entreprises

• User — compte applicatif. Implémente UserInterface. Porte les rôles, l'état de vérification (isVerified) et d'activation (isActivated), le jeton de réinitialisation de mot de passe, et le rattachement éventuel à une Company.
• Company — entreprise cliente. Rattachée à un utilisateur manager, elle regroupe des employés et une configuration de carte partagée.
• Employee — employé d'une entreprise. Peut se voir attribuer une carte de visite et un compte utilisateur activable par lien e-mail.
• Activity / CompanyActivity — secteurs d'activité de référence.
• RefreshToken — jetons de rafraîchissement de l'API.

Cartes

• BusinessCardAize — carte de visite numérique. Identifiée publiquement par un publicHash non devinable (les anciens QR codes utilisaient l'identifiant numérique, encore accepté en repli). Statuts :

Constante	Valeur	Signification
STATUS_DRAFT	draft	Brouillon, non accessible publiquement
STATUS_PUBLISHED	published	Publiée et partageable
STATUS_DISABLED	disabled	Désactivée

• Card — produit « carte physique » du catalogue.
• CardModel — modèle graphique proposé.
• CardColorOption / CardPrintOption — options de personnalisation.
• PhysicalCard — exemplaire commandé, avec son cycle de fabrication :

Constante	Valeur
STATUS_PENDING	PENDING
STATUS_PENDING_PAYMENT	PENDING_PAYMENT
STATUS_CONFIRMED	CONFIRMED
STATUS_PROCESSING	PROCESSING
STATUS_SHIPPED	SHIPPED
STATUS_DELIVERED	DELIVERED

Contacts

• Contact — entrée du carnet d'adresses, rattachée à un User. Le drapeau isBCard distingue un contact importé depuis une carte BCard d'un contact issu d'un scan papier ou d'une saisie manuelle.

Commerce

• Order — commande. Statuts : En Attente, En attente de paiement, En traitement, Terminée, Remboursée, Annulée, plus les marqueurs PRO_SUBSCRIPTION et DRAFT.
• OrderItem — ligne de commande.
• Payment — paiement rattaché à une commande.

Statuts	PENDING, ACCEPTED, COMPLETED, REJECTED
Moyens	CREDIT_CARD, ORANGE_MONEY, DELIVERY_CASH, PRO_SUBSCRIPTION, COMPANY_FREE, MANUAL

• Plan — offre d'abonnement : prix mensuel et annuel, liste de fonctionnalités, nombre de cartes incluses, prix de la carte supplémentaire, badge, ordre d'affichage et drapeau « populaire ».
• Subscription — abonnement souscrit. Statuts ACTIVE, PENDING, CANCELLED, EXPIRED ; périodicité MONTHLY ou YEARLY.

Exploitation

• Settings — paramètres généraux modifiables depuis le back-office.
• AuditLog — journal des actions sensibles : création, modification, activation, désactivation et suppression d'utilisateur, création et activation d'abonnement, changement de statut de commande, création/modification/suppression de carte virtuelle.

---

Organisation du code

src/
├── Command/          Commandes console
├── Controller/       Contrôleurs web (site public + espace connecté)
│   ├── admin/        Back-office
│   └── api/          API REST JSON
├── DataFixtures/     Données de référence (dev et test uniquement)
├── Entity/           Entités Doctrine
├── EventListener/    PasswordChangeListener
├── EventSubscriber/  ApiExceptionSubscriber, BusinessCardCreationSubscriber,
│                     JWTAuthenticatedSuccessListener
├── Form/             Types de formulaires
├── Repository/       Requêtes Doctrine
├── Security/         UserAuthenticator, GoogleAuthenticator, FacebookAuthenticator,
│                     EmailVerifier
├── Service/          Logique métier
└── Twig/             PlanExtension, FeaturesExtension

Services métier

Service	Responsabilité
AIAnalysisService	Analyse par IA des photos de cartes papier et extraction des coordonnées
QRCodeService	Génération des QR codes des cartes
StripeService	Sessions de paiement et intentions de paiement Stripe
PaymentService	Orchestration des paiements applicatifs
SubscriptionService	Cycle de vie des abonnements, création de l'abonnement gratuit
PlanService / PredefinedFeaturesService	Offres et fonctionnalités associées
BusinessCardGenerationService	Création des cartes de visite
BusinessCardEmailService	Envoi des cartes par e-mail
BusinessCardSerializerService / CardSerializerService	Sérialisation pour l'API
BCardContactSyncService	Synchronisation des contacts depuis les cartes
CompanyRegistrationService	Parcours d'inscription entreprise
EmployeeUserCreationService	Création et activation des comptes employés
DefaultProCardService	Carte par défaut des comptes professionnels
LogoManagementService	Gestion des logos d'entreprise
UploaderService	Upload et stockage des fichiers
DomPdfService	Génération des PDF (factures)
MailerService	Envoi des e-mails transactionnels
EmailVerificationService	Codes et liens de vérification d'adresse
AccountDeletionService	Suppression et anonymisation des comptes
RefreshTokenService	Émission et révocation des refresh tokens
RecaptchaService	Vérification reCAPTCHA v3
AuditLogger	Écriture du journal d'audit
SettingsService	Accès aux paramètres applicatifs
SeoService	Métadonnées SEO

---

Parcours métier

Création et partage d'une carte numérique

1. L'utilisateur crée une carte depuis /business-card/create.
2. Un publicHash lui est attribué et un QR code est généré.
3. La carte passe en published pour devenir accessible sur /bcard/{hash}.
4. Elle peut être envoyée par e-mail, ou son QR code téléchargé.

Scan d'une carte de visite

• Carte papier : la photo est transmise à AIAnalysisService, qui renvoie les coordonnées extraites. Un contact est créé après contrôle d'unicité sur l'e-mail ; les éléments d'adresse sont consignés dans la note du contact.
• QR code BCard : l'identifiant est résolu par publicHash, puis en repli par identifiant numérique s'il fait moins de 20 caractères. Le contact est importé avec isBCard = true.

Inscription d'une entreprise

/company/register → vérification de l'e-mail → détails de l'entreprise → choix de l'abonnement → paiement → confirmation. Le compte reste inactif tant qu'un administrateur ne l'a pas activé : toute tentative d'accès au tableau de bord redirige alors vers l'accueil avec un message d'erreur.

Commande d'une carte physique

Sélection du produit et des options → panier → commande → paiement Stripe → confirmation par webhook → passage des cartes en CONFIRMED, puis suivi jusqu'à DELIVERED.

Voir paiements.md pour le détail des flux de paiement.