Aller au contenu

🚀 Documentation Teadle

📋 Vue d'ensemble

Teadle est une plateforme de mise en relation entre formateurs et organisations. Elle permet aux formateurs de gérer leur planning, candidater à des opportunités et facturer leurs interventions, tandis que les organisations peuvent publier des missions et gérer leurs formateurs.

🎯 Fonctionnalités principales

  • 🔐 Authentification sécurisée : Cookies httpOnly, JWT, OAuth (LinkedIn, Google, Microsoft), codes d'authentification
  • 👥 Profils distincts : Formateurs et Organisations avec interfaces dédiées
  • 📋 Onboarding intelligent : Parcours guidé avec reprise possible
  • 💼 Gestion des opportunités : Publication, candidature, matching
  • 📅 Planning avancé : Calendrier interactif, événements, interventions
  • 💰 Facturation : Génération automatique des factures
  • 📧 Notifications : Emails automatisés via Brevo
  • 📊 Bilan mensuel : Rapport automatique envoyé aux formateurs le 1er du mois (Symfony Scheduler + Messenger async)

🛠️ Technologies

Frontend

  • Vue.js 3 - Framework principal avec Composition API
  • Pinia - Gestion d'état centralisée
  • Vue Router 4 - Navigation et guards
  • Axios - Client HTTP
  • Tailwind CSS - Framework CSS utilitaire
  • Vite - Build tool et dev server

Backend

  • Symfony 7.3 - Framework PHP
  • API Platform 3.2 - API REST automatique
  • Doctrine ORM 3.3 - Mapping objet-relationnel
  • PostgreSQL - Base de données
  • Symfony Messenger - Traitement asynchrone (emails, bilan mensuel)
  • Symfony Scheduler - Planification des tâches récurrentes (bilan mensuel)
  • JWT + Cookies httpOnly - Authentification sécurisée
  • OAuth 2.0 - Authentification tierce

Monitoring & Observabilité

  • Sentry - Capture d'erreurs et performance monitoring (backend Symfony + frontend Vue.js, 2 projets séparés)
  • New Relic - APM et monitoring infra (agent PHP, région EU collector.eu01.nr-data.net)

Infrastructure

  • Docker & Docker Compose - Containerisation
  • Nginx - Serveur web
  • Redis - Cache et sessions
  • Brevo - Service d'envoi d'emails

🐳 Docker

Le projet utilise Docker pour l'environnement de développement et de production.

Services Docker

# compose.yaml
services:
  frontend:     # Vue.js dev server
  backend:      # Symfony + API Platform
  database:     # PostgreSQL
  redis:        # Cache et sessions
  nginx:        # Reverse proxy

Variables d'environnement

# Base de données
DATABASE_URL=postgresql://teadle:password@database:5432/teadle

# Sécurité
APP_SECRET=your-secret-key
JWT_SECRET_KEY=path/to/private.key
JWT_PUBLIC_KEY=path/to/public.key

# OAuth
LINKEDIN_CLIENT_ID=your-linkedin-client-id
GOOGLE_CLIENT_ID=your-google-client-id
MICROSOFT_CLIENT_ID=your-microsoft-client-id

# Email
BREVO_SECRET=your-brevo-api-key

# Monitoring
SENTRY_DSN=https://...@....ingest.de.sentry.io/...
NEW_RELIC_LICENSE_KEY=eu01x...NRAL
NEW_RELIC_APP_NAME=Teadle

🚀 Commandes Makefile

Le projet utilise un Makefile pour simplifier les commandes de développement.

🏃‍♂️ Démarrage rapide

# Installer et démarrer l'environnement complet
make install

# Démarrer les services
make up

# Arrêter les services
make down

🔧 Développement

# Installer les dépendances frontend
make frontend-install

# Installer les dépendances backend
make backend-install

# Démarrer le serveur de développement frontend
make frontend-dev

# Démarrer le serveur de développement backend
make backend-dev

# Vider le cache Symfony
make backend-cache-clear

🗄️ Base de données

# Créer la base de données
make database-create

# Exécuter les migrations
make database-migrate

# Charger les fixtures
make database-fixtures

# Réinitialiser la base (drop + create + migrate + fixtures)
make database-reset

🧪 Tests

# Lancer les tests frontend
make frontend-test

# Lancer les tests backend (Unit + Functional)
make test-backend
make test-backend-unit
make test-backend-functional
make test-frontend
make test-frontend-unit
make test-frontend-functional

# E2E Cypress smoke prod (secrets CYPRESS_E2E_* requis)
make test-e2e-smoke

Rapports de tests (CI)

Les rapports sont générés automatiquement par la CI (branche main, post-déploiement) et publiés sur Cloudflare Pages :

Les tests Allure sont regroupés par suite dans le rapport :

  • Backend : Unit, Functional, et Lint (PHPStan, PHP_CodeSniffer)
  • Frontend : Unit, Functional, et Lint (Prettier)
  • E2E (smoke Cypress post-déploiement sur main) : Trainer, Staff, et le reste à la racine

🔄 CI/CD et sécurité

Workflow : .github/workflows/ci.yml.

Déclenchement : push (toute branche) → qualité + Trivy (un run par commit ; les checks apparaissent sur la PR sans second workflow). push sur main ou workflow_dispatch → en plus deploy, smoke, rapports MkDocs/Allure/Pages.

Bloc Jobs (nom affiché GitHub) Rôle
A — Lint + Tests Lint — *, Tests — * (4 jobs) PHPStan, PHPCS, Prettier, PHPUnit, Vitest — Lint backend non bloquant
B — Doctrine Doctrine — schema:validate Migrations + schema:validate (Postgres CI)
C — Sécurité Security — Composer, npm, Trivy (OS) Audits CVE — non bloquants (info)
Deploy Deploy — Clever Cloud main — après lint/tests/Doctrine verts ; sécurité et lint backend en échec n’empêchent pas le deploy. Image clevercloud/clever-tools:latest ; étape Disable system-git avant les deploy (l’image n’embarque pas git, on revient à l’implémentation JS via le volume /github/home)

Les blocs A, B et C démarrent en parallèle (aucun needs entre eux).

Étape Jobs Rôle
6 — Smoke prod Smoke prod — curl, smoke-e2e, smoke-lighthouse (parallèle) curl + Summary ; Cypress + Allure ; Lighthouse + Summary (continue-on-error)
7 — Rapports CI — Résumé (Summary), Allure — Rapport complet, Deploy — Cloudflare Pages Méga résumé dans l’onglet Summary GitHub ; Allure + Lighthouse + MkDocs sur Cloudflare Pages

En local (linters alignés CI — voir .cursor/rules/linters-keeper.mdc) :

make lint-frontend          # Prettier check
make lint-frontend-fix      # Prettier --write
make lint-backend           # PHPStan + PHPCS (Docker)
make lint                   # les deux

cd backend && ./vendor/bin/phpstan analyse --configuration=phpstan.dist.neon --memory-limit=512M --no-progress
cd backend && ./vendor/bin/phpcs --standard=phpcs.xml.dist
cd frontend && npx prettier --check "src/**/*.{js,vue,css,json}"

Sécurité :

cd backend && composer audit
cd frontend && npm audit
docker build -t teadle:local -f .infra/dev/Dockerfile .
trivy image --vuln-type os teadle:local   # OS seulement (deps PHP → composer audit)
make db-migrate && docker compose exec backend php bin/console doctrine:schema:validate

🏗️ Build et déploiement

# Build de production frontend
make frontend-build

# Build de production backend
make backend-build

# Build complet
make build

Image Docker (Clever Cloud, CI) : le contexte de build est en général la racine du dépôt. Docker n’applique alors que le fichier /.dockerignore à cette racine (pas celui sous .infra/prod/). Sans lui, tout le dépôt (dont .git, dépendances locales) peut être envoyé au daemon : les étapes finales du build (exporting layers) deviennent très longues et semblent « bloquées » car elles n’affichent souvent aucun log pendant plusieurs minutes.

🧹 Maintenance

# Nettoyer les containers et volumes
make clean

# Nettoyer complètement (containers, volumes, images)
make clean-all

# Voir les logs
make logs

📚 Documentation

📁 Structure des documentations

.doc/
├── README.md                    # ← Ce fichier (point d'entrée)
├── MIGRATION_BOUNDED_CONTEXTS.md # Plan de migration vers les Bounded Contexts
├── frontend/                    # Documentation frontend
│   ├── README.md               # Vue d'ensemble frontend
│   ├── ARCHITECTURE.md         # Architecture Vue.js
│   ├── WORKFLOWS.md            # Flux utilisateur
│   ├── ONBOARDING_GUARD.md     # Système de protection des routes
│   └── ...
└── backend/                     # Documentation backend
    ├── README.md               # Vue d'ensemble backend
    ├── ARCHITECTURE.md         # Architecture DDD
    ├── API_PLATFORM.md         # API Platform custom
    ├── DATABASE.md             # Base de données
    ├── SECURITY.md             # Sécurité et authentification
    └── ...

🧭 Plan d'architecture

MIGRATION_BOUNDED_CONTEXTS.md - Migration vers les Bounded Contexts

  • Phase 1 : correction des violations DDD (invariants dans les agrégats, snapshots facturation, conventions)
  • Phase 2 : découpage backend par contexte métier (13 modules, graphe de dépendances, règles de traversée)
  • Phase 3 : découpage frontend (modules/ par contexte, views/ par acteur)
  • Décision structurante : découpage par métier, pas par acteur

🎯 Documentation Frontend

README.md - Vue d'ensemble

  • Architecture Vue.js 3 avec Composition API
  • Structure du projet et organisation des composants
  • Gestion d'état avec Pinia
  • Routing et navigation

ARCHITECTURE.md - Architecture détaillée

  • Patterns de composants Vue.js
  • Gestion d'état centralisée
  • Communication entre composants
  • Optimisations de performance

WORKFLOWS.md - Flux utilisateur

  • Parcours d'inscription et onboarding
  • Workflows métier (formateurs/organisations)
  • Gestion des états et transitions
  • Validation des formulaires

ONBOARDING_GUARD.md - Protection des routes

  • Système de guards pour l'onboarding
  • Gestion des états d'authentification
  • Redirections intelligentes
  • Persistance des données

🔧 Documentation Backend

README.md - Vue d'ensemble

  • Architecture hexagonale (DDD)
  • Technologies Symfony et API Platform
  • Structure du projet
  • Configuration et déploiement

ARCHITECTURE.md - Architecture DDD

  • Principes Domain-Driven Design
  • Couches (Domain, Application, Infrastructure)
  • Patterns utilisés (Repository, Command, Value Object)
  • Bounded Contexts

API_PLATFORM.md - API Platform custom

  • Resources, Processors et Providers personnalisés
  • Configuration des endpoints REST
  • Gestion de la sécurité
  • Validation et gestion d'erreurs

DATABASE.md - Base de données

  • Schéma ER complet
  • Entités et relations
  • Migrations Doctrine
  • Optimisations et index

SECURITY.md - Sécurité

  • Authentification sécurisée (Cookies httpOnly, JWT, OAuth, codes)
  • Autorisation et permissions
  • Protection contre les attaques XSS et CSRF
  • Monitoring et audit

🚀 Démarrage rapide

1. Prérequis

# Vérifier que Docker est installé
docker --version
docker-compose --version

# Vérifier que Make est disponible
make --version

2. Installation

# Cloner le projet
git clone <repository-url>
cd teadle

# Installer et démarrer l'environnement
make install

3. Accès aux services

  • Frontend : http://localhost:3000
  • Backend API : http://localhost:8000
  • API Documentation : http://localhost:8000/api
  • Base de données : localhost:5432

4. Première utilisation

# Charger les données de test
make database-fixtures

# Créer un compte de test
# Utiliser l'interface d'inscription sur http://localhost:3000

🔧 Développement

Workflow recommandé

  1. Démarrer l'environnement : make up
  2. Développer : Modifier le code dans frontend/ ou backend/
  3. Tester : make frontend-test ou make backend-test
  4. Valider : make e2e-test
  5. Déployer : make build

Commandes utiles

# Voir les logs en temps réel
make logs

# Redémarrer un service spécifique
docker-compose restart backend

# Accéder au shell d'un service
docker-compose exec backend bash
docker-compose exec frontend sh

🔒 Sécurité

Authentification sécurisée

Teadle utilise une architecture d'authentification moderne et sécurisée :

🍪 Cookies httpOnly

  • Protection XSS : Les tokens JWT ne sont pas accessibles en JavaScript
  • Gestion automatique : Le navigateur envoie automatiquement les cookies
  • Expiration automatique : Gérée par le navigateur selon les paramètres
  • Secure flag : Restriction aux connexions HTTPS en production
  • SameSite : Protection contre les attaques CSRF

🔐 Méthodes d'authentification

  • Email/Mot de passe : Authentification classique avec cookies httpOnly
  • OAuth 2.0 : LinkedIn, Google, Microsoft
  • Codes d'authentification : Validation par email
  • Réinitialisation de mot de passe : Processus sécurisé

🛡️ Protection contre les attaques

  • XSS : Cookies httpOnly, validation des entrées
  • CSRF : SameSite cookies, validation des origines
  • Injection : Validation et échappement des données
  • Brute force : Rate limiting, verrouillage de compte

Configuration recommandée

# Production
cookies:
  secure: true      # HTTPS uniquement
  httpOnly: true    # Pas d'accès JavaScript
  sameSite: Strict  # Protection CSRF
  domain: .teadle.com
  path: /

📞 Support

Équipe de développement

  • Lead Developer - Architecture et développement
  • Frontend Developer - Interface utilisateur Vue.js
  • Backend Developer - API Symfony et logique métier
  • DevOps Engineer - Infrastructure et déploiement

Communication

  • GitHub Issues - Suivi des bugs et features
  • Slack - Communication quotidienne
  • Notion - Documentation et planning

Dernière mise à jour : ${new Date().toLocaleDateString('fr-FR')}

Teadle - Plateforme de mise en relation formateurs/organisations