# Documentation technique

## Sommaire

- [1. Introduction](#1-introduction)
- [2. Contexte et objectifs](#2-contexte-et-objectifs)
- [3. Perimetre fonctionnel realise](#3-perimetre-fonctionnel-realise)
- [4. Stack technique et justification des choix](#4-stack-technique-et-justification-des-choix)
- [5. Architecture generale](#5-architecture-generale)
- [6. Architecture backend](#6-architecture-backend)
- [7. Architecture frontend](#7-architecture-frontend)
- [8. Architecture de la base de donnees](#8-architecture-de-la-base-de-donnees)
- [9. Conception de securite](#9-conception-de-securite)
- [10. API et contrats d'echange](#10-api-et-contrats-dechange)
- [11. Outils de vente et de reservation](#11-outils-de-vente-et-de-reservation)
- [12. CRM, fidelite et relation client](#12-crm-fidelite-et-relation-client)
- [13. Paiement, notifications et integrations externes](#13-paiement-notifications-et-integrations-externes)
- [14. Infrastructure et deploiement local](#14-infrastructure-et-deploiement-local)
- [15. Prise en main developpeur](#15-prise-en-main-developpeur)
- [16. Tests et strategie de validation](#16-tests-et-strategie-de-validation)
- [17. Difficultes connues et solutions](#17-difficultes-connues-et-solutions)
- [18. Limites et perspectives](#18-limites-et-perspectives)
- [19. Annexes techniques](#19-annexes-techniques)
- [20. Conclusion](#20-conclusion)

## 1. Introduction

### 1.1 Objet du document

Ce document presente les choix techniques, l'architecture et les principes d'implementation de Procuratio.
Il est destine aux professionnels du secteur informatique qui doivent comprendre, evaluer, maintenir ou faire evoluer le projet.

Il permet de :

- comprendre les choix de langage, framework et infrastructure
- expliquer l'organisation frontend, backend et base de donnees
- decrire les regles de securite et les contrats principaux
- documenter les modules de vente, reservation, CRM et e-commerce
- faciliter la reprise du projet par une equipe technique

### 1.2 Public vise

Cette documentation technique s'adresse principalement a :

- un jury technique
- un developpeur reprenant le projet
- un administrateur devant lancer la stack
- un evaluateur souhaitant comprendre les choix d'implementation

La documentation utilisateur doit rester separee : elle explique les fonctionnalites aux clients, employes et managers sans entrer dans les details de code.

### 1.3 Perimetre du document

Le document couvre :

- l'architecture applicative
- le modele de donnees
- la securite
- les flux metier critiques
- les integrations externes
- les commandes utiles
- les limites connues
- les pistes d'amelioration

## 2. Contexte et objectifs

### 2.1 Probleme traite

Un institut de beaute ou un salon de coiffure manipule plusieurs flux souvent disperses entre plusieurs outils :

- caisse et ventes physiques
- catalogue produits et prestations
- planning des rendez-vous
- fiches clients
- fidelite et cartes de visites
- campagnes CRM
- bons cadeaux
- commandes e-commerce
- preparation et suivi de stock

Procuratio centralise ces flux dans une meme application afin de reduire les doubles saisies et de fournir une vision coherente de l'activite.

### 2.2 Objectifs du projet

Les objectifs fonctionnels sont :

- proposer un back-office pour les operations magasin
- proposer un espace client autonome
- gerer la vente physique, la reservation et l'e-commerce
- lier les ventes, rendez-vous et actions CRM aux fiches clients
- fournir une base de demonstration stable et comprehensible

Les objectifs techniques sont :

- fournir une API claire et maintenable
- garder une separation stricte entre frontend, backend et base de donnees
- securiser les actions selon les roles
- rendre la stack reproductible avec Docker
- verrouiller les versions importantes pour limiter les ecarts de poste
- conserver des tests utiles sur les parcours critiques

### 2.3 Positionnement

Procuratio est pense comme un ERP/CRM metier pour salons et instituts.
Le projet ne cherche pas une architecture inutilement complexe : il privilegie des choix robustes, lisibles et adaptes a un logiciel de gestion.

## 3. Perimetre fonctionnel realise

### 3.1 Back-office

Le back-office regroupe les fonctionnalites operationnelles :

- dashboard d'activite
- gestion des produits
- gestion des prestations
- caisse / POS
- planning
- fiches clients
- gestion des employes
- gestion des managers
- gestion des boutiques
- CRM
- warehouse / preparation
- profil utilisateur

### 3.2 Espace client

L'espace client permet :

- consultation du catalogue
- gestion du panier
- passage de commande
- consultation des commandes
- annulation d'une commande non expediee
- consultation des rendez-vous
- consultation des bons cadeaux disponibles
- modification du mot de passe
- modification de certaines preferences personnelles

### 3.3 Roles applicatifs

Les roles principaux sont :

- `ROLE_CUSTOMER` : client final
- `ROLE_EMPLOYEE` : employe operationnel
- `ROLE_ADMIN` : manager ou administrateur

Un employe gere les operations quotidiennes.
Un manager dispose d'un perimetre plus large : boutiques, employes, managers, horaires, donnees de reference et administration.

### 3.4 Modules metier principaux

- catalogue produits
- catalogue services
- stock
- caisse
- rendez-vous
- disponibilites employes
- horaires boutique
- CRM
- fidelite
- bons cadeaux
- e-commerce
- notifications
- statistiques

### 3.5 Couverture des parcours utilisateur

Le guide utilisateur decrit les parcours complets par role.
La documentation technique couvre ces parcours par modules implementes :

- client : catalogue, panier, commande, rendez-vous, profil, bons cadeaux
- employe : POS, planning operationnel, clients, warehouse, profil
- manager : administration catalogue, planning, horaires, CRM, equipes, boutiques, statistiques

Cette correspondance est la base de verification technique des recettes fonctionnelles.

## 4. Stack technique et justification des choix

### 4.1 Tableau de la stack

| Couche | Technologie | Version de reference | Role dans le projet |
|---|---|---|---|
| Langage backend | PHP | 8.2 | Execution de l'API et services metier |
| Framework backend | Symfony | 6.4 | Routage, securite, injection de dependances, structure applicative |
| ORM | Doctrine ORM | version verrouillee dans `composer.lock` | Mapping entites, repositories et migrations |
| Base de donnees | MySQL | 8.0 | Persistance relationnelle des ventes, rendez-vous, stock et CRM |
| Langage frontend | TypeScript | version verrouillee dans `package-lock.json` | Typage des ecrans, payloads et reponses API |
| Framework frontend | React | 18 | Interfaces back-office, client, POS, planning et CRM |
| Build frontend | Vite | version verrouillee dans `package-lock.json` | Build rapide et bundling de l'application web |
| Authentification | JWT | configuration Symfony | Sessions stateless et controle d'acces API |
| Paiement | Stripe | API externe | Paiement e-commerce, webhooks et confirmation serveur |
| Notifications | Email, Brevo, webhook SMS | configuration `.env` | Envoi ou simulation de communications client |
| Tests backend | PHPUnit | configuration `api/` | Validation API et regles metier |
| Tests frontend | Playwright | configuration `frontend/` | Parcours utilisateur, roles et captures documentaires |
| Conteneurisation | Docker Compose | fichiers `infra/` | Lancement reproductible de la stack locale |

### 4.2 Backend : PHP 8.2 et Symfony 6.4

Symfony est adapte a ce projet car il fournit :

- un routage clair
- une securite configurable
- une injection de dependances mature
- une integration solide avec Doctrine
- une structure naturelle en controllers, services, repositories et entites

PHP 8.2 reste pertinent pour une application de gestion car il est stable, largement supporte et tres adapte aux architectures API classiques.

### 4.3 Frontend : React, TypeScript et Vite

React permet de construire des ecrans riches comme la caisse, le planning ou le CRM.

TypeScript est utilise pour :

- clarifier les payloads API
- limiter les erreurs de manipulation de donnees
- documenter les structures cote frontend

Vite a ete choisi pour :

- sa rapidite de build
- une configuration legere
- une integration simple avec React

### 4.4 Base de donnees : MySQL 8

MySQL est coherent avec les besoins du projet :

- donnees fortement relationnelles
- nombreuses jointures
- historique des ventes, paiements, rendez-vous et mouvements de stock
- execution simple dans Docker

### 4.5 Docker et verrouillage des versions

Docker Compose permet de reproduire le meme environnement sur differents postes.
Les versions sont verrouillees pour limiter les regressions liees a des outils trop recents.

Versions de reference :

- Node.js `20.20.2`
- npm `10.8.2`
- Symfony `6.4`
- PHP runtime Docker `8.2`
- MySQL `8.0`

Fichiers de verrouillage :

- `.nvmrc`
- `.node-version`
- `frontend/package-lock.json`
- `api/composer.lock`
- `frontend/.npmrc`

## 5. Architecture generale

### 5.1 Vue d'ensemble

Procuratio suit une architecture web en trois blocs :

1. frontend React
2. API Symfony
3. base MySQL

Des services externes completent l'application :

- Stripe pour le paiement
- Brevo ou mail natif pour les emails
- webhook SMS selon configuration

Schema d'architecture globale :

```text
+------------------+        HTTPS / JSON        +-----------------------+
| Navigateur web   | <------------------------> | Frontend React / Nginx |
| Client ou BO     |                            | Port 48200             |
+------------------+                            +-----------+-----------+
                                                            |
                                                            | API REST / JWT
                                                            v
                                                +-----------+-----------+
                                                | API Symfony           |
                                                | Port 48280            |
                                                +-----+-----------+-----+
                                                      |           |
                                             SQL      |           | Webhooks / API
                                                      v           v
                                                +-----+-----+  +--+----------------+
                                                | MySQL 8   |  | Stripe / Brevo    |
                                                | Port DB   |  | SMS provider      |
                                                +-----------+  +-------------------+
```

### 5.2 Organisation du depot

```text
app/
|-- api/
|-- frontend/
|-- docs/
|-- infra/
|-- scripts/
|-- .env
|-- .env.example
|-- .env.prod.example
|-- .nvmrc
|-- .node-version
`-- README.md
```

### 5.3 Separation des responsabilites

Le frontend gere :

- l'affichage
- l'experience utilisateur
- les appels API
- les guards de navigation
- les etats locaux de formulaire

Le backend gere :

- l'authentification
- les permissions
- les validations serveur
- les regles metier
- la persistance
- les integrations externes sensibles

La base de donnees conserve :

- les donnees transactionnelles
- les historiques
- les relations metier

Schema de circulation interne :

```text
Requete HTTP
    |
    v
Controller API
    |
    | validation du contexte, role, payload minimal
    v
Service metier
    |
    | regles de vente, reservation, stock, CRM
    v
Repository / Doctrine
    |
    v
Base MySQL
    |
    v
Reponse JSON normalisee
```

### 5.4 Diagramme de cas d'utilisation

```text
                         +----------------------+
                         |      Procuratio      |
                         +----------------------+
Client ----------------> Consulter catalogue
Client ----------------> Commander en ligne
Client ----------------> Reserver un rendez-vous
Client ----------------> Voir commandes, rendez-vous et bons cadeaux
Client ----------------> Modifier son mot de passe

Employe ---------------> Encaisser une vente
Employe ---------------> Gerer planning operationnel
Employe ---------------> Consulter fiches clients utiles
Employe ---------------> Preparer commandes et reservations

Manager ---------------> Administrer produits, services et stock
Manager ---------------> Gerer boutiques, employes et managers
Manager ---------------> Modifier horaires magasin
Manager ---------------> Piloter CRM, fidelite et statistiques
Manager ---------------> Regenerer un mot de passe utilisateur
```

## 6. Architecture backend

### 6.1 Structure principale

```text
api/
|-- config/
|-- public/
|-- src/
|   |-- Command/
|   |-- Controller/
|   |-- DataFixtures/
|   |-- Demo/
|   |-- Entity/
|   |-- EventSubscriber/
|   |-- Repository/
|   |-- Security/
|   `-- Service/
`-- tests/
```

### 6.2 Controllers principaux

L'API v1 est organisee par domaines :

- `ProductController`
- `ServiceController`
- `CatalogController`
- `PosController`
- `PlanningController`
- `CrmController`
- `BackofficeCustomerController`
- `EcommerceController`
- `WarehouseController`
- `StatsController`
- `EmployeeManagementController`
- `ManagerManagementController`
- `StoreController`
- `SystemController`

Chaque controller expose les routes d'un sous-domaine et delegue la logique importante a des services.

### 6.3 Services metier principaux

- `BookingService` : disponibilites, reservation et sessions de booking
- `PlanningValidator` : contraintes horaires, conflits et coherence planning
- `CrmService` : fidelite, campagnes, rappels et bons cadeaux
- `EcommerceService` : panier, commande, reservation produit et annulation
- `StockManager` : mouvements de stock et coherence metier
- `SaleCalculator` : calculs POS, taxes et remises
- `StripeService` : paiement Stripe et webhook
- `NotificationGatewayService` : abstraction email / SMS
- `GiftVoucherDocumentService` : document de bon cadeau
- `StatsService` : indicateurs de dashboard

### 6.4 Gestion des erreurs

Le projet tend vers des messages runtime sobres et coherents.
Les erreurs publiques doivent rester utiles sans exposer d'information sensible.

Principes :

- validation serveur avant traitement
- message utilisateur clair
- detail technique reserve aux logs
- pas d'exposition de secret, SQL ou stack trace

## 7. Architecture frontend

### 7.1 Structure principale

```text
frontend/
|-- public/
|-- src/
|   |-- api/
|   |-- app/
|   |-- auth/
|   |-- hooks/
|   |-- layouts/
|   |-- pages/
|   |-- types/
|   |-- ui/
|   `-- utils/
`-- tests/
```

### 7.2 Espaces applicatifs

Le routeur separe :

- `/backoffice` pour managers et employes
- `/client` pour les clients
- les pages publiques de catalogue et reservation

Le backend reste la reference de securite.
Les guards frontend servent a guider l'utilisateur et a eviter les acces incoherents.

### 7.3 Pages structurantes

- `ProductsPage`
- `ServicesPage`
- `PosPage`
- `PlanningPage`
- `CustomersPage`
- `CrmPage`
- `WarehousePage`
- `ProfilePage`
- `BackOfficeProfilePage`

### 7.4 Principes UI

L'interface est construite autour de composants reutilisables, de formulaires controles et de messages d'etat explicites.
Les ecrans denses ont ete progressivement decoupes pour reduire les composants monolithiques.

## 8. Architecture de la base de donnees

### 8.1 Vue d'ensemble

Le modele est relationnel et organise par domaines.

Modele conceptuel de donnees, vue simplifiee :

```text
USER
  |-- CUSTOMER
  |     |-- CART
  |     |-- ORDER
  |     |-- APPOINTMENT
  |     |-- LOYALTY_ACCOUNT
  |     `-- GIFT_VOUCHER
  |
  `-- EMPLOYEE
        |-- STORE
        |-- EMPLOYEE_AVAILABILITY
        `-- APPOINTMENT

STORE
  |-- BUSINESS_HOUR
  |-- EMPLOYEE
  |-- SALE
  `-- APPOINTMENT

PRODUCT
  |-- BRAND
  |-- CATEGORY
  |-- STOCK_MOVEMENT
  `-- PRODUCT_RESERVATION

SERVICE
  `-- CATEGORY

SALE
  |-- SALE_ITEM
  |-- PAYMENT
  `-- PAYMENT_EVENT

ORDER
  |-- ORDER_ITEM
  `-- PAYMENT
```

Schema relationnel simplifie :

```text
users(id, email, password, roles, temporary_password_flag, created_at)
customers(id, user_id, first_name, last_name, email, phone, birth_date)
employees(id, user_id, store_id, first_name, last_name, role_label, active)
stores(id, name, city, address, active)

products(id, brand_id, category_id, name, price, quantity, active)
services(id, category_id, name, price, duration_minutes, active)
stock_movements(id, product_id, store_id, type, quantity, reason, created_at)

sales(id, customer_id, employee_id, store_id, status, total, paid_at)
sale_items(id, sale_id, product_id, service_id, quantity, unit_price, discount)
payments(id, sale_id, order_id, provider, status, amount, reference)
payment_events(id, payment_id, type, payload, created_at)

appointments(id, customer_id, employee_id, store_id, status, starts_at, ends_at)
appointment_services(id, appointment_id, service_id, quantity, price)
business_hours(id, store_id, weekday, opens_at, closes_at, is_open)
employee_availabilities(id, employee_id, weekday, starts_at, ends_at, is_available)

loyalty_accounts(id, customer_id, points_balance, membership_name, visit_goal, visits_used)
loyalty_events(id, loyalty_account_id, operation, points, reason, created_at)
gift_vouchers(id, customer_id, recipient_email, code, amount, expires_at, status)
orders(id, customer_id, status, total, payment_status, created_at)
order_items(id, order_id, product_id, quantity, unit_price)
```

### 8.2 Utilisateurs et profils

- `User`
- `Customer`
- `Employee`
- `Store`
- `RefreshToken`

Un `User` porte l'authentification.
Un client ou un employe est relie a cet utilisateur.
Un employe est rattache a une boutique.

### 8.3 Catalogue et stock

- `Product`
- `Service`
- `Brand`
- `Category`
- `StockMovement`
- `ProductReservation`
- `ProductReview`

Les marques et categories structurent le catalogue.
Les mouvements de stock assurent la tracabilite.

### 8.4 Vente et paiement

- `Sale`
- `SaleItem`
- `SuspendedTicket`
- `Payment`
- `PaymentEvent`

Une vente contient plusieurs lignes.
Les paiements et evenements permettent de tracer l'encaissement, l'annulation et les integrations externes.

### 8.5 Rendez-vous et planning

- `Appointment`
- `AppointmentService`
- `AppointmentStatusHistory`
- `BusinessHour`
- `EmployeeAvailability`
- `BookingSession`

Les rendez-vous relient client, employe, boutique et prestations.
Les disponibilites employes doivent rester compatibles avec les horaires boutique.

### 8.6 CRM et fidelite

- `LoyaltyAccount`
- `LoyaltyEvent`
- `Campaign`
- `ReminderRule`
- `NotificationLog`
- `GiftVoucher`

Le CRM conserve l'historique des actions relationnelles et des avantages client.

### 8.7 E-commerce

- `Cart`
- `Order`
- `OrderItem`
- `StoreReview`

Les commandes conservent leurs lignes et leur statut.
Une commande client peut etre annulee tant qu'elle n'est pas expediee.

## 9. Conception de securite

### 9.1 Authentification

L'API utilise une authentification JWT stateless.

Routes principales :

- `POST /api/v1/auth/login`
- `POST /api/v1/auth/refresh`
- `POST /api/v1/auth/logout`
- `GET /api/v1/me`

Sequence d'authentification JWT :

```text
Utilisateur       Frontend React          API Symfony            Base MySQL
    |                  |                      |                      |
    | email/password   |                      |                      |
    |----------------->| POST /auth/login     |                      |
    |                  |--------------------->| verification user    |
    |                  |                      |--------------------->|
    |                  |                      | user + hash password |
    |                  |                      |<---------------------|
    |                  | token JWT + profil   |                      |
    |                  |<---------------------|                      |
    | session locale   |                      |                      |
    |<-----------------|                      |                      |
```

### 9.2 Autorisation

La hierarchie de roles est definie dans `security.yaml` :

- `ROLE_CUSTOMER`
- `ROLE_EMPLOYEE`
- `ROLE_ADMIN`

Les routes publiques sont limitees aux besoins explicites :

- healthcheck
- login
- catalogue public
- disponibilites publiques
- documentation OpenAPI
- webhook Stripe

Le reste de l'API exige un utilisateur authentifie.

Synthese des roles et permissions :

```text
+---------------------+----------+----------+---------+
| Fonctionnalite      | Client   | Employe  | Manager |
+---------------------+----------+----------+---------+
| Catalogue public    | Oui      | Oui      | Oui     |
| Espace client       | Oui      | Herite   | Herite  |
| Caisse / POS        | Non      | Oui      | Oui     |
| Planning operation  | Non      | Oui      | Oui     |
| Horaires magasin    | Non      | Lecture  | Ecriture|
| Produits / services | Non      | Limite   | Oui     |
| CRM                 | Non      | Non      | Oui     |
| Employes/managers   | Non      | Non      | Oui     |
| Profil personnel    | Oui      | Oui      | Oui     |
+---------------------+----------+----------+---------+
```

### 9.3 Gestion des mots de passe

Chaque utilisateur peut modifier son mot de passe depuis son profil.
Lorsqu'un mot de passe temporaire est genere par un manager, l'utilisateur est incite a le remplacer.

### 9.4 Secrets et variables sensibles

Les secrets ne doivent pas etre versionnes.

Variables sensibles principales :

- `APP_SECRET`
- `JWT_PASSPHRASE`
- `STRIPE_SECRET_KEY`
- `STRIPE_WEBHOOK_SECRET`
- `BREVO_API_KEY`
- `SMS_WEBHOOK_TOKEN`

### 9.5 Paiement et webhooks

Le webhook Stripe est public cote JWT mais protege par verification de signature.
Cette separation est volontaire : Stripe ne peut pas fournir un JWT applicatif, la confiance repose donc sur le secret webhook.

### 9.6 Donnees exposees

Les reponses API doivent exposer seulement les donnees utiles a l'ecran.
Les messages d'erreur doivent eviter les details techniques exploitables.

## 10. API et contrats d'echange

### 10.1 Conventions generales

L'API est exposee sous `/api/v1`.
Les echanges utilisent JSON.
Les routes de lecture utilisent principalement `GET`, les creations `POST`, les modifications `PUT` ou `PATCH`, les suppressions `DELETE`.

### 10.2 Routes de base

- `GET /api/v1/health`
- `POST /api/v1/auth/login`
- `GET /api/v1/me`
- `GET /api/v1/admin/ping`

### 10.3 Catalogue et stock

- `GET /api/v1/products`
- `POST /api/v1/products`
- `PUT /api/v1/products/{id}`
- `DELETE /api/v1/products/{id}`
- `POST /api/v1/products/{id}/stock-adjustments`
- `GET /api/v1/services`
- `POST /api/v1/services`
- `PUT /api/v1/services/{id}`
- `DELETE /api/v1/services/{id}`
- `GET /api/v1/catalog/brands`
- `GET /api/v1/catalog/categories`

### 10.4 E-commerce

- `GET /api/v1/catalog/products`
- `GET /api/v1/catalog/products/{id}`
- `GET /api/v1/cart`
- `POST /api/v1/cart/items`
- `PUT /api/v1/cart/items/{productId}`
- `DELETE /api/v1/cart/items/{productId}`
- `POST /api/v1/checkout`
- `GET /api/v1/orders/me`
- `GET /api/v1/orders/{orderNumber}`
- `POST /api/v1/payments/stripe/webhook`

### 10.5 Fidelite et bons cadeaux

- `GET /api/v1/loyalty/me`
- `GET /api/v1/crm/gift-vouchers/{id}/print`
- `POST /api/v1/crm/gift-vouchers/{id}/send`

### 10.6 Reservation produit

- `POST /api/v1/catalog/products/{id}/reservations`
- `GET /api/v1/reservations/me`
- `POST /api/v1/reservations/{id}/cancel`
- `POST /api/v1/reservations/{id}/picked-up`

### 10.7 Documentation OpenAPI

La documentation API est disponible localement :

- dev : `http://localhost:48180/api/doc`
- prod locale : `http://localhost:48280/api/doc`

## 11. Outils de vente et de reservation

### 11.1 Caisse / POS

Le module POS permet :

- creation de ticket
- ajout de produits et services
- remises de ligne
- remise globale
- suspension et reprise
- encaissement
- impression du recu
- annulation d'une vente encaissee

Une vente annulee ne peut pas etre suspendue ni reprise.
Elle reste consultable pour l'historique et l'impression du recu.

Sequence de vente en caisse :

```text
Employe        Frontend POS        API POS             Services metier        MySQL
  |                |                  |                      |                  |
  | nouveau ticket |                  |                      |                  |
  |--------------->| POST ticket      |                      |                  |
  |                |----------------->| creer Sale draft     |----------------->|
  | ajoute lignes  |                  | calcul taxes/remises |                  |
  |--------------->| PUT lignes       |--------------------->| StockManager     |
  | encaisse       |                  |                      |                  |
  |--------------->| POST charge      | SaleCalculator       |----------------->|
  |                |                  | Payment + Sale paid  |----------------->|
  | recu           |<-----------------|                      |                  |
```

### 11.2 Planning

Le planning permet :

- vues jour, semaine, mois et annee
- creation manuelle de rendez-vous
- recherche de creneaux disponibles
- gestion des horaires salon
- resume des horaires pour les employes
- completion ou annulation d'un rendez-vous

Les employes visibles sont filtres par boutique.
Les dates et horaires disponibles respectent les horaires d'ouverture et les disponibilites employes.

Sequence de reservation :

```text
Client/BO       Frontend Planning      API Planning       BookingService       MySQL
   |                  |                    |                   |                |
   | choisit boutique |                    |                   |                |
   | service/employe  |                    |                   |                |
   |----------------->| recherche slots    |                   |                |
   |                  |------------------->| disponibilites    |--------------->|
   |                  |                    | horaires + conflits                |
   |                  | slots valides      |<------------------|                |
   |<-----------------|                    |                   |                |
   | confirme slot    | POST appointment   |                   |                |
   |----------------->|------------------->| validation finale |--------------->|
   | confirmation     |<-------------------| appointment cree  |                |
```

### 11.3 E-commerce

Le parcours e-commerce permet :

- consultation du catalogue
- panier
- checkout
- paiement Stripe
- consultation des commandes
- annulation tant que la commande n'est pas expediee

Flux de paiement securise :

```text
Client       Frontend        API Symfony        Stripe             MySQL
  | panier      |                |                 |                 |
  |------------>| checkout       |                 |                 |
  |             |--------------->| creer commande  |---------------->|
  |             |                | creer payment   |---------------->|
  |             | paiement       |---------------->|                 |
  |             |<---------------| client secret   |                 |
  | valide CB   |--------------->|                 |                 |
  |             |                | webhook signe   |<----------------|
  |             |                | verifier secret |                 |
  |             |                | confirmer paye  |---------------->|
  | confirmation|<---------------|                 |                 |
```

## 12. CRM, fidelite et relation client

### 12.1 Points de fidelite

Le CRM permet d'ajouter ou consommer des points de fidelite.
Les actions peuvent etre appliquees individuellement ou en masse sur des clients selectionnes.

### 12.2 Membership et cartes de visites

Le membership represente le programme ou abonnement de fidelite du client.
La carte de visites suit une progression de type `visites utilisees / objectif`.

Une carte s'incremente lorsqu'un rendez-vous eligible passe en statut `completed`.

### 12.3 Campagnes

Les campagnes permettent de preparer des communications email ou SMS.
Les logs de notification permettent de tracer les envois ou tentatives.

### 12.4 Bons cadeaux

Les bons cadeaux peuvent etre crees depuis le CRM.
Ils peuvent etre associes a un client ou a une adresse email.
Les bons non expires associes a l'adresse du client sont visibles depuis son profil.

## 13. Paiement, notifications et integrations externes

### 13.1 Stripe

Stripe est utilise pour le paiement e-commerce.
Le backend cree ou valide les paiements et traite les webhooks.

Variables importantes :

- `STRIPE_SECRET_KEY`
- `STRIPE_WEBHOOK_SECRET`
- `STRIPE_MOCK_MODE`

Cartes de test de reference :

- paiement accepte : `4242 4242 4242 4242`
- paiement avec authentification 3D Secure : `4000 0025 0000 3155`
- paiement refuse : `4000 0000 0000 9995`
- carte expiree : `4000 0000 0000 0069`
- CVC incorrect : `4000 0000 0000 0127`

Parametres de test usuels :

- date : n'importe quelle date future (exemple `12/34`)
- CVC : n'importe quelle valeur (exemple `123`)
- code postal : n'importe quelle valeur si demande

### 13.2 Emails

Le projet peut utiliser un mode mail local ou Brevo selon configuration.

Variables importantes :

- `NOTIFICATIONS_EMAIL_MODE`
- `NOTIFICATIONS_MAIL_FROM`
- `NOTIFICATIONS_MAIL_REPLY_TO`
- `BREVO_API_KEY`

### 13.3 SMS

Les SMS peuvent etre delegues a un webhook externe.

Variables importantes :

- `NOTIFICATIONS_SMS_MODE`
- `SMS_SENDER`
- `SMS_WEBHOOK_URL`
- `SMS_WEBHOOK_TOKEN`

## 14. Infrastructure et deploiement local

### 14.1 Stack Docker

La stack locale comprend :

- MySQL
- API Symfony
- frontend Nginx
- Adminer
- Stripe CLI listener selon configuration

Diagramme de deploiement local :

```text
Machine evaluateur
|
|-- Docker Compose
    |
    |-- procuratio-frontend-prod
    |     |-- image Nginx
    |     |-- sert le build React
    |     `-- port 48200
    |
    |-- procuratio-api-prod
    |     |-- image PHP 8.2 CLI
    |     |-- application Symfony
    |     `-- port 48280
    |
    |-- procuratio-db-prod
    |     |-- image MySQL 8
    |     |-- volume persistant
    |     `-- port interne MySQL
    |
    |-- procuratio-adminer-prod
    |     `-- port 48281
    |
    `-- stripe-cli listener
          `-- transmet les webhooks Stripe vers l'API
```

### 14.2 Ports utiles

Environnement developpement :

- frontend : `http://localhost:43100`
- API : `http://localhost:48180`
- OpenAPI : `http://localhost:48180/api/doc`
- Adminer : `http://localhost:48181`
- MySQL : `localhost:43306`

Environnement prod locale :

- frontend : `http://localhost:48200`
- API : `http://localhost:48280`
- OpenAPI : `http://localhost:48280/api/doc`
- Adminer : `http://localhost:48281`

### 14.3 Demarrage

Developpement :

```bash
docker compose --env-file .env -f infra/docker-compose.yml up -d --build
```

Prod locale :

```bash
docker compose --env-file .env -f infra/docker-compose.prod.yml up -d --build
```

Arret :

```bash
docker compose --env-file .env -f infra/docker-compose.yml down
docker compose --env-file .env -f infra/docker-compose.prod.yml down
```

## 15. Prise en main developpeur

### 15.1 Installation pas a pas

Deux modes de recuperation du projet sont possibles.

Cas 1 : le projet est recupere avec Git.

1. Cloner le depot.
2. Se placer dans le dossier racine de l'application.
3. Copier `.env.example` vers `.env`.
4. Renseigner les variables sensibles.
5. Lancer la stack Docker.
6. Verifier l'API doc.
7. Se connecter avec un compte de test local.

Cas 2 : le projet est fourni sous forme d'archive ZIP ou de dossier source.

1. Extraire l'archive dans un dossier local sans espace ni caractere special dans le chemin si possible.
2. Verifier que les dossiers `api/`, `frontend/`, `infra/`, `docs/` et `scripts/` sont presents.
3. Verifier que les fichiers de verrouillage sont inclus : `api/composer.lock` et `frontend/package-lock.json`.
4. Copier `.env.example` vers `.env` si le fichier `.env` n'est pas fourni.
5. Ajuster les variables locales : ports, secrets, Stripe, notifications.
6. Lancer Docker Desktop.
7. Executer la commande de demarrage Docker Compose adaptee.
8. Ouvrir le frontend et la documentation API pour valider l'installation.

Cette approche ne suppose pas que l'examinateur ait acces a l'historique Git.
Le code source, les lockfiles et les fichiers d'environnement exemple suffisent pour lancer le projet.

### 15.2 Comptes de test locaux

- `admin@procuratio.local` / `Admin123!`
- `employee@procuratio.local` / `Employee123!`
- `customer@procuratio.local` / `Customer123!`

Ces comptes sont destines a la demonstration locale.
Ils ne doivent pas etre utilises en production reelle.

### 15.3 Jeu de donnees de demonstration

La base locale est pre-remplie via l'outillage de seed pour faciliter la recette :

- produits, prestations, marques, types
- clients, employes, managers, boutiques
- donnees CRM (fidelite, memberships, cartes de visites, bons cadeaux)
- ventes POS, commandes e-commerce et rendez-vous de demonstration

Ce jeu de donnees est reserve a la demonstration et a l'evaluation.
Il ne doit pas etre reutilise tel quel en production.

### 15.4 Commandes de maintenance

```bash
docker compose --env-file .env -f infra/docker-compose.prod.yml ps
docker compose --env-file .env -f infra/docker-compose.prod.yml logs -f api
docker compose --env-file .env -f infra/docker-compose.prod.yml logs -f frontend
docker exec procuratio-api-prod php bin/console doctrine:migrations:migrate --no-interaction
docker exec procuratio-api-prod php bin/console cache:clear
docker exec procuratio-api-prod php bin/console app:cleanup-e2e-data --no-interaction
```

### 15.5 Variables d'environnement critiques

- `DATABASE_URL`
- `APP_SECRET`
- `JWT_PASSPHRASE`
- `CORS_ALLOW_ORIGIN`
- `STRIPE_SECRET_KEY`
- `STRIPE_WEBHOOK_SECRET`
- `NOTIFICATIONS_MAIL_FROM`
- `BREVO_API_KEY`

## 16. Tests et strategie de validation

### 16.1 Strategie globale

La strategie de test combine :

- tests backend pour les regles API et metier
- tests Playwright pour les parcours utilisateur
- captures Playwright pour la documentation visuelle
- verification manuelle des parcours critiques avant livraison

### 16.2 Backend

```bash
cd api
php bin/phpunit
```

Zones critiques :

- authentification
- planning
- booking
- POS
- e-commerce
- permissions

### 16.3 Frontend

```bash
cd frontend
npm run build
npx playwright test
```

Parcours couverts :

- login
- annuaire admin
- planning manager
- POS
- e-commerce
- warehouse
- profile
- CRM

### 16.4 Captures documentaires

Un scenario Playwright genere des captures completes des pages et modales par role.
Les captures sont destinees a la documentation utilisateur et a la recette visuelle.

## 17. Difficultes connues et solutions

### 17.1 Versions locales plus recentes

Si une machine utilise une version plus recente de Node ou npm, le build peut diverger.
La solution recommandee est d'utiliser les versions verrouillees ou le build Docker.

Commandes de verification :

```bash
node -v
npm -v
docker --version
docker compose version
```

### 17.2 Ports deja utilises

Si un port est deja pris, Docker peut refuser de lancer un conteneur.
Il faut arreter le service concurrent ou modifier le port dans `.env`.

### 17.3 Emails non recus

Un email peut etre prepare cote application sans etre delivre par le provider.
Il faut verifier :

- mode de notification
- cle Brevo
- domaine expediteur
- logs transactionnels Brevo
- quotas et blocages provider

### 17.4 Donnees E2E visibles en prod locale

Les tests doivent nettoyer leurs donnees.
Si d'anciens reliquats persistent, une commande de nettoyage dediee peut etre lancee.

### 17.5 Taille des chunks frontend

Un warning Vite sur la taille des chunks n'est pas bloquant.
C'est une piste d'optimisation, pas une erreur de build.

## 18. Limites et perspectives

### 18.1 Limites actuelles

- certains ecrans frontend restent denses
- la delivrabilite email depend d'un provider externe
- la documentation utilisateur doit etre finalisee separement
- certains messages applicatifs peuvent encore etre harmonises

### 18.2 Perspectives fonctionnelles

- enrichir les scenarios CRM avances
- renforcer les statistiques magasin
- ajouter des exports plus complets
- ameliorer les outils de suivi de livraison email

### 18.3 Perspectives techniques

- continuer la modularisation des gros ecrans
- renforcer les tests negatifs
- completer l'OpenAPI avec davantage d'exemples de payloads

## 19. Annexes techniques

### 19.1 Documentation disponible

- `README.md` : lancement, commandes utiles et depannage
- `docs/ARCHITECTURE.md` : synthese d'architecture
- `docs/TECHNICAL_DOCUMENTATION.docx` : version Word de cette documentation
- `docs/captures/playwright/` : captures documentaires generees

### 19.2 Scripts utiles

Les scripts fournis ne sont pas obligatoires : ils encapsulent les commandes Docker les plus frequentes afin d'eviter les erreurs de saisie.
Ils existent en version shell pour Linux/macOS et en version PowerShell pour Windows.

`bootstrap-env` prepare les fichiers d'environnement locaux a partir des modeles.
Il est utile lors d'une premiere installation ou lorsqu'un examinateur recoit uniquement le code source.

```bash
sh scripts/bootstrap-env.sh
powershell -ExecutionPolicy Bypass -File scripts/bootstrap-env.ps1
```

`stack-prod-up` lance la stack de demonstration locale avec les fichiers de configuration production locale.
Il reconstruit les images si necessaire et demarre les services attendus.

```bash
sh scripts/stack-prod-up.sh
powershell -ExecutionPolicy Bypass -File scripts/stack-prod-up.ps1
```

`stack-prod-down` arrete proprement les services de la stack locale.
Il est utile avant de liberer les ports ou de fermer l'environnement de demonstration.

```bash
sh scripts/stack-prod-down.sh
powershell -ExecutionPolicy Bypass -File scripts/stack-prod-down.ps1
```

Les commandes Docker equivalentes restent documentees dans les sections d'installation et de maintenance.

## 20. Conclusion

Procuratio repose sur une architecture volontairement classique et maintenable :

- API Symfony modulaire
- frontend React type
- base relationnelle MySQL
- infrastructure Docker reproductible
- integration Stripe pour les paiements
- notifications configurables
- tests backend et frontend sur les parcours essentiels

Le projet est structure pour couvrir un besoin metier concret : faire cohabiter vente, reservation, CRM, fidelite, e-commerce et suivi client dans un meme outil.
Les choix techniques privilegient la stabilite, la comprehension par une equipe et la possibilite d'evoluer sans refonte majeure.