Documentation Complète du CRM Aaperture

Document de référence pour comprendre Aaperture comme CRM pour photographes, ses fonctionnalités, son architecture et ses cas d'usage. Ce document est destiné à permettre à un Agent IA de comprendre le système et proposer des améliorations cohérentes.

📋 Table des Matières

Introduction et Contexte
Vue d'Ensemble du Produit
Modules et Fonctionnalités Détaillés
Entités et Relations
Intégrations Externes
Fonctionnalités Transversales
Cas d'Usage Typiques
Points d'Extension et Améliorations

1. Introduction et Contexte

Qu'est-ce qu'un CRM ?

Un CRM (Customer Relationship Management) est un système de gestion de la relation client qui permet aux entreprises de :

Centraliser les informations clients : Base de données unifiée de tous les contacts et clients
Suivre les interactions : Historique complet des communications, rendez-vous, transactions
Automatiser les processus : Workflows et automatisations pour gagner du temps
Analyser les performances : Statistiques et rapports pour prendre des décisions éclairées
Gérer les ventes : Suivi des devis, factures, paiements et pipeline commercial
Planifier et organiser : Calendrier, tâches, rappels pour une meilleure organisation

Aaperture : CRM spécialisé pour photographes

Aaperture est un CRM complet conçu spécifiquement pour répondre aux besoins des photographes professionnels. Contrairement aux CRM génériques, Aaperture intègre des fonctionnalités adaptées au métier de la photographie :

Gestion de sessions photographiques : Mariages, séances portrait, événements, etc.
Synchronisation calendrier : Intégration bidirectionnelle avec Google Calendar
Roadmaps intelligentes : Planification avec météo et horaires soleil
Checklists personnalisables : Par type de session pour ne rien oublier
Gestion des fichiers : Organisation des photos et documents par session
Devis et facturation : Création, envoi et suivi des devis/factures avec paiements en ligne
Assistant IA : Automatisation des tâches répétitives et création assistée

Public cible

Aaperture s'adresse aux photographes professionnels qui ont besoin de :

Gérer plusieurs projets simultanément (mariages, séances, événements)
Suivre leurs clients et leurs interactions
Organiser leur planning et leur disponibilité
Facturer leurs prestations et suivre les paiements
Automatiser leurs processus métier
Analyser leurs performances et revenus

Valeur ajoutée

Pourquoi un CRM dédié aux photographes ?

Workflows adaptés : Interface et processus conçus pour le cycle de vie d'un projet photographique
Intégrations spécialisées : Google Calendar, météo, horaires soleil, etc.
Gestion des sessions récurrentes : Support natif des événements récurrents (mariages annuels, séances régulières)
Checklists métier : Templates pré-configurés pour chaque type de session
Roadmaps intelligentes : Planification automatique avec données contextuelles (météo, horaires)
Assistant IA intégré : Création assistée et automatisation via prompts en langage naturel

2. Vue d'Ensemble du Produit

Modules principaux

Aaperture est organisé en 11 modules principaux (scopes) :

Sessions & Projets - Cycle de vie complet des projets photographiques
Contacts & Clients - Base de données clients avec historique et relations
Devis & Factures - Gestion financière complète (quotes, invoices, paiements)
Calendrier & Planification - Synchronisation Google Calendar et gestion de disponibilité
IA Proactive Insights ✅ - Système d'insights automatiques avec 8 règles déterministes
Recherche & IA - Global Search et Assistant IA conversationnel
Communication & Notifications - Emails, notifications push, tracking
Analytics & Reporting - Statistiques et rapports de performance
Workflows & Automatisation - Automatisation des processus métier
Sécurité & Conformité - GDPR, permissions, sécurité des données
Mobile - Push tokens, delta sync pour applications mobiles (Expo/FCM/APNs)

Architecture générale

Stack technique :

Backend : NestJS (Node.js 22) + TypeScript
Frontend : React 18 + TypeScript + TanStack Router
Python Services : FastAPI - Service unifié pour :
- Génération PDF (WeasyPrint)
- Génération Word (python-docx)
- Génération Excel (openpyxl)
- Embeddings (sentence-transformers)
- Intent Detection (transformers BART)
- Recherche sémantique (Qdrant)
OCR : Vision APIs (GPT-4o) + Tesseract.js fallback
Base de données : PostgreSQL avec Kysely (type-safe queries)
Migrations : Liquibase
Authentification : JWT + Google OAuth
Stockage fichiers : Cloudflare R2 (S3-compatible)
WebSocket : Socket.IO pour temps réel
Cache : Redis (ioredis) pour performance et rate limiting
Queue : BullMQ pour jobs asynchrones
Validation : Zod
IA : OpenAI API (clés utilisateur)
CI/CD : GitLab CI avec builds parallèles

Architecture logicielle :

Clean Architecture & Domain Driven Design
Repository Pattern : Abstraction de l'accès aux données
Service Layer : Logique métier encapsulée
DTO Pattern : Objets de transfert pour les API
Guard Pattern : Authentification et autorisation
Module Pattern : Organisation par fonctionnalité

Flux de données principaux

graph TB
    subgraph "Frontend"
        A[React App] --> B[TanStack Query]
        B --> C[API Client]
        C --> D[WebSocket Client]
    end

    subgraph "Backend API"
        E[NestJS Controllers] --> F[Services]
        F --> G[Repositories]
        G --> H[(PostgreSQL)]
        F --> I[External APIs]
        E --> J[WebSocket Gateway]
    end

    subgraph "External Services"
        I --> K[Google Calendar]
        I --> L[Stripe]
        I --> M[OpenAI]
        I --> N[Notion]
        I --> O[Cloudflare R2]
    end

    subgraph "Infrastructure"
        H --> P[Redis Cache]
        J --> D
    end

    C -->|HTTP REST| E
    D -->|WebSocket| J

Flux typique d'une requête :

Frontend : L'utilisateur interagit avec l'interface React
API Client : TanStack Query appelle l'API avec le token JWT
Backend : Le Guard valide le token et le statut utilisateur
Service : La logique métier est exécutée
Repository : Les données sont récupérées/modifiées dans PostgreSQL
Cache : Redis met en cache les données fréquemment accédées
Réponse : Les données sont retournées au frontend
WebSocket : Les notifications temps réel sont émises si nécessaire

3. Modules et Fonctionnalités Détaillés

3.1 Sessions & Projets

Objectif : Gérer l'ensemble du cycle de vie d'un projet photographique, de la création à la livraison.

Entités principales :

sessions : Sessions photographiques (mariages, séances, événements)
session_contacts : Relations sessions ↔ contacts
session_tags : Tags associés aux sessions
session_providers : Prestataires associés (traiteurs, DJ, etc.)
session_checklists : Checklists de session
session_checklist_items : Items de checklist avec statut
session_files : Fichiers associés à une session
session_planning_items : Items de planification (roadmap)

Fonctionnalités clés :

✅ CRUD complet : Création, lecture, mise à jour, suppression de sessions
✅ Sessions récurrentes : Support des patterns de récurrence (quotidien, hebdomadaire, mensuel, annuel)
✅ Gestion des contacts : Association de plusieurs contacts à une session
✅ Tags : Système de tags pour catégoriser les sessions
✅ Prestataires : Gestion des prestataires associés (traiteurs, DJ, etc.)
✅ Checklists : Checklists personnalisables par type de session avec statuts (PENDING, IN_PROGRESS, COMPLETED, SKIPPED)
✅ Roadmaps : Planification intelligente avec météo et horaires soleil
✅ Fichiers : Upload et organisation des fichiers par session
✅ Statuts : Suivi du statut de la session (DRAFT, CONFIRMED, IN_PROGRESS, COMPLETED, CANCELLED)
✅ Synchronisation Google Calendar : Création automatique d'événements dans Google Calendar
✅ Types de session : Types personnalisables par utilisateur (mariage, portrait, événement, etc.)

Intégrations :

Google Calendar : Synchronisation bidirectionnelle des événements
Weather API : Données météo pour les roadmaps
Sunrise/Sunset API : Horaires soleil pour planification

Cas d'usage typiques :

Création d'un mariage : Créer une session de type "mariage" avec date, lieu, contacts (mariés, témoins), checklist "mariage", roadmap avec météo
Sessions récurrentes : Créer une session de coaching photo tous les lundis à 10h pendant 3 mois
Suivi d'un projet : Consulter la checklist, uploader les photos, mettre à jour le statut

Références :

Documentation backend : backend/src/sessions/README.md
Schémas détaillés : architecture/scopes.md#1-sessions--projets

3.2 Contacts & Clients

Objectif : Gérer la base de données clients avec leurs informations, historique et relations.

Entités principales :

contacts : Contacts clients avec informations de base
contact_sessions : Relations contacts ↔ sessions
contact_files : Fichiers associés aux contacts
email_tracking : Tracking des emails envoyés (ouvertures, clics)

Fonctionnalités clés :

✅ CRUD complet : Création, lecture, mise à jour, suppression de contacts
✅ Informations complètes : Nom, prénom, email, téléphone, adresse
✅ Historique : Timeline des interactions (sessions, emails, notes)
✅ Relations sessions : Voir toutes les sessions associées à un contact
✅ Fichiers : Upload et organisation des fichiers par contact
✅ Détection de doublons : Détection automatique de contacts similaires (via IA)
✅ Tracking emails : Suivi des emails envoyés (ouvert, lien cliqué)
✅ Recherche : Recherche globale dans les contacts

Intégrations :

OpenAI : Détection de doublons via similarité sémantique
Email Service : Tracking des emails via pixels et liens

Cas d'usage typiques :

Création d'un contact : Créer un nouveau client avec ses informations
Historique client : Consulter toutes les sessions et interactions avec un client
Détection doublons : Le système détecte automatiquement les contacts similaires lors de la création

Références :

Documentation backend : backend/src/contacts/README.md
Schémas détaillés : architecture/scopes.md#2-contacts--clients

3.3 Devis & Factures

Objectif : Gérer la création, l'envoi et le suivi des devis et factures, ainsi que les paiements.

Entités principales :

quotes : Devis avec statuts (DRAFT, SENT, ACCEPTED, REJECTED, EXPIRED)
quote_items : Lignes de devis (description, quantité, prix)
invoices : Factures avec statuts (DRAFT, SENT, PAID, OVERDUE, CANCELLED)
invoice_items : Lignes de facture
payments : Paiements associés aux factures
credit_notes : Avoirs/notes de crédit
scheduled_emails : Emails planifiés pour devis/factures
email_tracking : Tracking des emails envoyés

Fonctionnalités clés :

✅ CRUD devis/factures : Création, modification, suppression
✅ Génération PDF : Génération automatique de PDFs professionnels
✅ Envoi par email : Envoi automatique avec tracking
✅ Emails planifiés : Planification d'envoi d'emails (ex: rappel)
✅ Paiements en ligne : Intégration Stripe pour paiement sécurisé
✅ Statuts : Suivi des statuts (devis accepté/rejeté, facture payée/en retard)
✅ Numérotation automatique : Numérotation séquentielle des factures
✅ Templates : Templates personnalisables pour devis/factures
✅ Avoirs : Gestion des notes de crédit
✅ Rappels automatiques : Rappels pour factures en retard
✅ Liens clients : Accès client sécurisé pour consulter/accepter devis

Intégrations :

Stripe : Paiements en ligne sécurisés
Cloudflare R2 : Stockage des PDFs générés
Email Service : Envoi et tracking des emails

Cas d'usage typiques :

Création d'un devis : Créer un devis pour une session, ajouter les lignes, générer le PDF, envoyer par email
Acceptation devis : Le client accepte le devis via le lien sécurisé
Création facture : Convertir un devis accepté en facture
Paiement : Le client paie la facture en ligne via Stripe
Rappel : Système de rappels automatiques pour factures en retard

Références :

Documentation backend : backend/src/quotes-invoices/README.md
Schémas détaillés : architecture/scopes.md#3-devis--factures

3.4 Calendrier & Planification

Objectif : Visualiser, planifier et synchroniser avec Google Calendar, gérer la disponibilité.

Entités principales :

sessions : Sessions synchronisées avec Google Calendar
availability_slots : Créneaux de disponibilité (uniques ou récurrents)
user_metadata : Tokens Google Calendar OAuth

Fonctionnalités clés :

✅ Vues calendrier : Mois, semaine, jour, année, liste
✅ Synchronisation bidirectionnelle : Sync automatique avec Google Calendar (toutes les 5 minutes)
✅ Gestion disponibilité : Création de créneaux disponibles/bloqués
✅ Créneaux récurrents : Support des patterns de récurrence pour disponibilité
✅ Drag & drop : Déplacement de sessions dans le calendrier
✅ Filtres : Filtrage par statut, type, contact, tags
✅ Recherche : Recherche rapide dans le calendrier
✅ Export iCal : Export au format ICS pour import dans d'autres calendriers
✅ Résolution de conflits : Gestion intelligente des conflits de synchronisation
✅ Système de réservation publique : Interface publique pour permettre aux clients de réserver des créneaux

Intégrations :

Google Calendar API : Synchronisation bidirectionnelle complète
Weather API : Données météo pour planification

Cas d'usage typiques :

Visualisation planning : Consulter le calendrier pour voir toutes les sessions du mois
Blocage créneaux : Bloquer des créneaux pour vacances ou indisponibilité
Synchronisation : Les modifications dans Google Calendar sont automatiquement synchronisées
Réservation client : Un client réserve un créneau via l'interface publique

Références :

Documentation : docs/CALENDAR_SYNC_ARCHITECTURE.md
Schémas détaillés : architecture/scopes.md#4-calendrier--planification

3.5 IA Proactive Insights ✅

Objectif : Générer automatiquement des insights actionnables basés sur les données CRM pour aider les photographes à identifier et résoudre rapidement les situations nécessitant une action.

Entités principales :

ai_insights : Insights générés avec type, sévérité, statut, actions suggérées
ai_insight_events : Audit trail des événements (création, lecture, archivage)
ai_insight_feedback : Feedback utilisateur pour améliorer la pertinence

Fonctionnalités clés :

✅ 8 règles d'insights : Détection automatique de situations critiques
- QUOTE_STALE : Devis envoyés en attente depuis 7+ jours
- INVOICE_OVERDUE : Factures en retard de paiement
- INVOICE_PARTIALLY_PAID : Factures partiellement payées
- SESSION_PREP_MISSING : Sessions à venir sans checklist ou checklist incomplète
- SESSION_POSTPROD_LAG : Retard de post-production (fichiers uploadés tardivement)
- SESSION_WITHOUT_DELIVERY : Sessions terminées sans fichiers de livraison
- BOOKING_UPCOMING : Sessions à venir dans les 3 prochains jours
- CHECKLIST_INCOMPLETE : Items de checklist en retard
✅ Génération automatique : Scheduler quotidien à 3h du matin pour tous les utilisateurs actifs
✅ Génération réactive : Déclenchement automatique via events (changement statut devis, création facture, etc.)
✅ Déduplication : Contrainte unique sur (unique_key, owner_id) pour éviter les doublons
✅ Sévérité intelligente : Calcul automatique INFO/WARN/CRITICAL selon la criticité
✅ Actions suggérées : Deep links vers entités et actions rapides (voir devis, envoyer rappel, etc.)
✅ Notifications : Notifications in-app + WebSocket + push pour insights critiques
✅ Feedback utilisateur : Système de feedback UP/DOWN pour améliorer la pertinence
✅ Filtres avancés : Filtrage par type, sévérité, statut dans l'interface
✅ Badge compteur : Affichage du nombre d'insights non lus dans la sidebar
✅ Navigation et breadcrumb : Configuration complète de la navigation et des breadcrumbs
✅ Corrections post-MVP : Colonnes SQL corrigées, sérialisation JSONB, gestion des erreurs améliorée
✅ Audit trail : Traçabilité complète via ai_insight_events
✅ Améliorations UI/UX : Graphiques et visualisations, vue calendrier, groupement intelligent, actions en lot, filtres sauvegardés, export multi-format
✅ Menu "More" : Regroupement des actions Generate/Export dans un menu déroulant compact
✅ Règles personnalisées : Système complet permettant aux utilisateurs de créer leurs propres règles d'insights
✅ 15 règles d'insights : 8 règles MVP + 7 nouvelles règles (CONTACT_NO_ACTIVITY, QUOTE_EXPIRING, INVOICE_PAYMENT_REMINDER, SESSION_FOLLOWUP_MISSING, CONTRACT_EXPIRING, RECURRING_SESSION_MISSING, EMAIL_BOUNCE)

Intégrations :

Queue BullMQ : Traitement asynchrone des générations d'insights
Notifications Service : Notifications in-app et push
WebSocket Service : Updates temps réel lors de création d'insights
Event Emitter : Déclenchement réactif via événements applicatifs

Cas d'usage typiques :

Devis en attente : Le système détecte un devis envoyé il y a 10 jours sans réponse et génère un insight WARN avec action "Envoyer un rappel"
Facture en retard : Une facture avec date d'échéance dépassée génère un insight CRITICAL avec lien direct vers la facture
Session sans préparation : Une session dans 2 jours sans checklist génère un insight CRITICAL pour rappeler la préparation
Post-production en retard : Une session terminée il y a 30 jours avec fichiers uploadés récemment génère un insight WARN sur le retard de livraison

Architecture :

Règles déterministes : Approche MVP sans LLM pour garantir fiabilité et performance
Clean Architecture : Repository, Service, Controller avec séparation des responsabilités
Queue asynchrone : Traitement en arrière-plan avec retry/backoff
Event-driven : Déclenchement réactif via EventEmitter2

Références :

Documentation backend : backend/src/insights/README.md
Plan d'implémentation : docs/INSIGHTS_IMPLEMENTATION_PLAN.md
Tests : backend/src/__tests__/insights/ (50+ tests unitaires)

3.6 Recherche & IA

Objectif : Recherche globale unifiée et Assistant IA conversationnel pour automatiser les tâches.

Entités principales :

conversations : Conversations avec l'Assistant IA
conversation_messages : Messages de conversation
Toutes les entités du CRM (sessions, contacts, quotes, invoices) pour la recherche

Fonctionnalités clés :

✅ Global Search : Recherche unifiée dans sessions, contacts, devis, factures, Notion
✅ Recherche temps réel : Debounce 300ms pour optimiser les performances
✅ Navigation clavier : Raccourcis clavier (Cmd+K / Ctrl+K)
✅ Assistant IA conversationnel : Chat avec l'IA pour questions et actions
✅ Builder de vues personnalisées : Génération de filtres via prompts en langage naturel
✅ Actions IA : Création assistée d'entités (sessions, contacts, devis, factures)
✅ Génération de rapports : Rapports intelligents générés par l'IA
✅ Rédaction assistée : Génération d'emails, descriptions, notes
✅ Intégration Notion : Recherche dans les pages et bases de données Notion

Intégrations :

OpenAI API : Intelligence artificielle (clés utilisateur)
Notion API : Recherche dans Notion

Cas d'usage typiques :

Recherche rapide : Appuyer sur Cmd+K, taper "mariage juillet", voir les résultats
Création assistée : "Crée une session pour le mariage de Marie et Pierre le 15 juillet"
Vue personnalisée : "Montre-moi tous les devis en attente pour les sessions de type portrait"
Rapport intelligent : "Génère un rapport des revenus par type de session pour le dernier trimestre"

Références :

Documentation : docs/AI_SEARCH_ARCHITECTURE.md
Documentation backend : backend/src/agent/README.md, backend/src/ai-assistant/README.md
Schémas détaillés : architecture/scopes.md#5-recherche--ia

3.6 Communication & Notifications

Objectif : Gérer les notifications in-app, push et les communications par email.

Entités principales :

notifications : Notifications système
user_notifications : Notifications utilisateur (lu/non lu)
push_subscriptions : Abonnements push notifications
scheduled_emails : Emails planifiés
email_tracking : Tracking des emails (ouvert, lien cliqué)
session_workflow_tasks : Tâches de notification de session (via workflow tasks unifié) ✅
default_workflow_tasks : Tâches système pour notifications de session ✅
user_metadata.session_reminder_settings : Configuration des notifications de session (JSONB) ✅

Fonctionnalités clés :

✅ Notifications in-app : Notifications dans l'interface avec centre de notifications
✅ Push notifications : Notifications navigateur même quand l'app est fermée
✅ WebSocket temps réel : Notifications instantanées via WebSocket
✅ Tracking emails : Suivi des ouvertures et clics sur les emails
✅ Emails planifiés : Planification d'envoi d'emails (devis, factures, rappels)
✅ Templates emails : Templates personnalisables avec variables
✅ Types de notifications : BOOKING_CREATED, PAYMENT_RECEIVED, PROJECT_CREATED, etc.
✅ Notifications de session automatiques : Système unifié de notifications de session via workflow tasks ✅
- Rappels automatiques (1 semaine, 24h, 1h avant la session)
- Configuration par utilisateur (activation, types, templates, destinataires)
- Templates email avec remplacement de variables (session, contact, user, etc.)
- Destinataires flexibles (user, contact, ou les deux)
- Intégration avec le système de workflow tasks existant

Intégrations :

Web Push API : Notifications push navigateur
Email Service : Envoi d'emails via SMTP ou Gmail API
WebSocket : Communication temps réel
Workflow Tasks System : Notifications de session via WorkflowTasksScheduler ✅

Cas d'usage typiques :

Notification réservation : Notification instantanée quand un client réserve un créneau
Rappel facture : Email automatique de rappel pour facture en retard
Tracking email : Voir si un client a ouvert le devis envoyé
Rappel de session : Email automatique de rappel 24h avant une session (configurable par utilisateur) ✅
Notification personnalisée : Rappels de paiement, rappels de rendez-vous avec templates personnalisés ✅

Références :

Documentation backend : backend/src/notifications/README.md
Documentation notifications de session : docs/SESSION_NOTIFICATIONS_ARCHITECTURE.md ✅
Schémas détaillés : architecture/scopes.md#6-communication--notifications

3.7 Analytics & Reporting

Objectif : Fournir des statistiques et rapports sur les performances du photographe.

Entités principales :

sessions : Données de sessions pour statistiques
quotes : Données de devis pour conversion
invoices : Données de factures pour revenus
payments : Données de paiements

Fonctionnalités clés :

✅ Dashboard : Vue d'ensemble des métriques principales
✅ Revenus : Statistiques de revenus par période, statut, type de session
✅ Conversion : Taux de conversion devis → facture
✅ Sessions : Statistiques de sessions par statut, période, type
✅ Graphiques : Visualisations interactives avec Recharts
✅ Export PDF : Génération de rapports PDF
✅ Presets de dates : Semaine, mois, trimestre, année, tout
✅ Comparaisons : Comparaison entre périodes

Intégrations :

PDF Service : Génération de rapports PDF
Cloudflare R2 : Stockage des rapports générés

Cas d'usage typiques :

Dashboard mensuel : Consulter les revenus et statistiques du mois
Rapport trimestriel : Générer un PDF avec les performances du trimestre
Analyse conversion : Voir le taux de conversion des devis en factures

Références :

Documentation backend : backend/src/analytics/README.md
Schémas détaillés : architecture/scopes.md#7-analytics--reporting

3.8 Workflows & Automatisation

Objectif : Automatiser les processus métier récurrents.

Entités principales :

user_workflows : Workflows personnalisés par utilisateur
user_workflow_phases : Phases d'un workflow
user_workflow_tasks : Tâches d'une phase
session_workflow_tasks : Tâches appliquées à une session (workflows + notifications système) ✅
default_workflows : Workflows système (ex: "Session Notifications") ✅
default_workflow_tasks : Tâches système pour notifications automatiques ✅
workflow_triggers : Déclencheurs de workflows
workflow_trigger_executions : Exécutions de déclencheurs

Fonctionnalités clés :

✅ Workflows personnalisables : Création de workflows avec phases et tâches
✅ Templates par défaut : Workflows pré-configurés (mariage, portrait, etc.)
✅ Déclencheurs : Déclenchement automatique sur événements (création session, changement statut)
✅ Tâches conditionnelles : Tâches avec conditions (ex: "Si devis accepté, créer facture")
✅ Actions : Actions automatiques (créer devis, envoyer email, etc.)
✅ Scheduler : Exécution automatique des tâches (toutes les minutes)
✅ Application à sessions : Application de workflows à des sessions spécifiques
✅ Notifications de session unifiées : Système de notifications automatiques intégré dans les workflow tasks ✅
- Workflow système "Session Notifications" avec tâches par défaut (1 semaine, 24h, 1h avant)
- Création automatique pour toutes les sessions (basée sur user_metadata.session_reminder_settings)
- Tâches marquées is_default_task = true dans session_workflow_tasks
- Exécution via WorkflowTasksExecutionService avec support template_key et recipients
- Configuration utilisateur : activation, types de notifications, templates, destinataires (user/contact)

Intégrations :

Services métier : Intégration avec tous les services (sessions, quotes, emails, etc.)
Email Templates : Chargement de templates HTML avec remplacement de variables ✅
User Metadata : Configuration des notifications dans user_metadata.session_reminder_settings ✅

Cas d'usage typiques :

Workflow mariage : Automatiser les étapes d'un mariage (devis → facture → rappels → livraison)
Déclenchement automatique : Quand une session est créée, appliquer automatiquement le workflow correspondant
Notifications automatiques : Rappels de session envoyés automatiquement selon la configuration utilisateur (24h avant, 1h avant, etc.) ✅
Rappels personnalisés : Rappels de paiement, rappels de rendez-vous avec templates et destinataires configurables ✅

Références :

Documentation : docs/WORKFLOW_TRIGGERS.md
Documentation notifications : docs/SESSION_NOTIFICATIONS_ARCHITECTURE.md ✅
Schémas détaillés : architecture/scopes.md#8-workflows--automatisation

3.9 Sécurité & Conformité

Objectif : Gérer la conformité RGPD et la sécurité des données.

Entités principales :

gdpr_consents : Consentements RGPD par utilisateur
gdpr_requests : Demandes RGPD (accès, rectification, effacement, portabilité)
gdpr_data_exports : Exports de données générés
gdpr_deletion_logs : Logs de suppression de données
audit_logs : Logs d'audit des actions utilisateur
permissions : Permissions granulaires par plan d'abonnement
user_permission_overrides : Overrides de permissions par utilisateur

Fonctionnalités clés :

✅ Consentements RGPD : Gestion des consentements (NECESSARY, FUNCTIONAL, ANALYTICS, MARKETING, THIRD_PARTY)
✅ Demandes RGPD : Traitement des demandes d'accès, rectification, effacement, portabilité
✅ Export de données : Export complet des données utilisateur (JSON)
✅ Suppression sécurisée : Suppression de données avec logs d'audit
✅ Permissions granulaires : Système de permissions par plan d'abonnement
✅ Audit logging : Traçabilité complète des actions utilisateur
✅ Vérification email : Vérification par email pour opérations sensibles

Intégrations :

Export Service : Génération d'exports de données
Email Service : Envoi de confirmations et vérifications

Cas d'usage typiques :

Demande d'accès : Un utilisateur demande l'accès à ses données, export généré automatiquement
Suppression de compte : Suppression sécurisée avec logs d'audit
Gestion permissions : Attribution de permissions selon le plan d'abonnement

Références :

Documentation backend : backend/src/gdpr/README.md, backend/src/permissions/README.md
Schémas détaillés : architecture/scopes.md#9-sécurité--conformité

3.10 Mobile

Objectif : Permettre l'intégration d'applications mobiles natives avec le backend, notamment pour les notifications push et la synchronisation de données hors ligne.

Entités principales :

mobile_push_tokens : Tokens de notification push pour appareils mobiles (iOS/Android)

Fonctionnalités clés :

✅ Enregistrement push tokens : Enregistrement et mise à jour des tokens de notification push (idempotent)
✅ Multi-providers : Support Expo Push, Firebase Cloud Messaging (FCM), Apple Push Notification Service (APNs)
✅ Révocation tokens : Révocation propre des tokens lors de la déconnexion
✅ Envoi automatique : Notifications push envoyées automatiquement lors de la création de notifications in-app
✅ Gestion erreurs Expo : Révocation automatique des tokens invalides (DeviceNotRegistered)
✅ Queue asynchrone : Traitement via BullMQ avec retry et backoff exponentiel
✅ Delta sync : Synchronisation incrémentale pour le cache mobile (sessions, contacts, notifications, checklists)
✅ Cursor opaque : Support de curseurs ISO date ou base64 JSON pour pagination
✅ Multi-device : Gestion de plusieurs appareils par utilisateur (via device_id)

Endpoints :

Méthode	Chemin	Description
POST	`/api/mobile/push-tokens`	Enregistrer/mettre à jour un push token
DELETE	`/api/mobile/push-tokens`	Révoquer un push token
POST	`/api/mobile/sync`	Synchronisation delta pour le cache mobile

Schéma de données :

interface MobilePushToken {
  id: string;              // UUID auto-généré
  owner_id: string;        // FK vers users
  platform: 'ios' | 'android';
  provider: 'expo' | 'fcm' | 'apns';
  token: string;           // Token push de l'appareil
  device_id?: string;      // Identifiant optionnel de l'appareil
  app_version?: string;    // Version de l'app pour compatibilité
  last_seen_at: Date;      // Dernière utilisation du token
  created_at: Date;
  revoked_at?: Date;       // null = token actif
}

Sync API :

// Requête de sync
interface MobileSyncRequest {
  cursor?: string;         // Curseur opaque (ISO date ou base64 JSON)
  entities: ('sessions' | 'contacts' | 'notifications' | 'checklists')[];
  limit?: number;          // 1-500, défaut: 200
}

// Réponse de sync
interface MobileSyncResponse {
  cursor: string;          // Nouveau curseur pour la prochaine requête
  serverTime: string;      // Timestamp serveur (ISO)
  sessions?: { upserts: Session[]; deletes: string[] };
  contacts?: { upserts: Contact[]; deletes: string[] };
  notifications?: { upserts: Notification[]; deletes: string[] };
  checklists?: { upserts: ChecklistItem[]; deletes: string[] };
}

Comportement du curseur :

Sans curseur : Retourne les données des 30 derniers jours
Curseur ISO date : "2024-06-15T10:00:00.000Z" - filtre depuis cette date
Curseur base64 : eyJ0cyI6IjIwMjQtMDYtMTVUMTA6MDA6MDAuMDAwWiJ9 - décodé en { ts: ISO_STRING }

Architecture Push Notifications :

NotificationsCreationService.createForUser()
    │
    ├── 1. Crée notification en BDD
    ├── 2. Émet événement WebSocket (temps réel)
    └── 3. Enqueue job mobile-push (async)
            │
            └── MobilePushProcessor
                    │
                    └── MobilePushProvider.sendToUser()
                            │
                            └── Expo Push API

Gestion des erreurs Expo :

Erreur Expo	Action
`DeviceNotRegistered`	Token révoqué automatiquement
`MessageTooBig`	Log, pas de retry
`MessageRateExceeded`	Retry avec backoff
Erreurs réseau	Retry exponentiel (3 tentatives)

Cas d'usage typiques :

Première connexion mobile : Enregistrer le push token, puis sync sans curseur pour charger les 30 derniers jours
Sync incrémental : Appeler sync avec le curseur reçu précédemment pour obtenir les nouvelles modifications
Réception push : L'app reçoit automatiquement les push quand des notifications sont créées côté serveur
Déconnexion : Révoquer le push token pour arrêter les notifications sur cet appareil
Multi-device : L'utilisateur peut avoir plusieurs appareils enregistrés avec des tokens différents

Références :

Code backend : backend/src/mobile/, backend/src/notifications/providers/
Queue/Processor : backend/src/notifications/processors/
OpenAPI : openapi/components/mobile.yaml, openapi/paths/mobile/

4. Entités et Relations

Modèle de données principal

erDiagram
    users ||--o{ sessions : "owns"
    users ||--o{ contacts : "owns"
    users ||--o{ quotes : "owns"
    users ||--o{ invoices : "owns"
    users ||--o{ mobile_push_tokens : "has"
    
    sessions ||--o{ session_contacts : "has"
    contacts ||--o{ session_contacts : "participates"
    sessions ||--o{ session_tags : "tagged"
    tags ||--o{ session_tags : "applies"
    
    sessions ||--o{ quotes : "has"
    sessions ||--o{ invoices : "has"
    contacts ||--o{ quotes : "for"
    contacts ||--o{ invoices : "for"
    
    quotes ||--o{ quote_items : "contains"
    invoices ||--o{ invoice_items : "contains"
    invoices ||--o{ payments : "paid_by"
    
    sessions ||--o{ session_checklists : "has"
    session_checklists ||--o{ session_checklist_items : "contains"
    
    users ||--o{ user_workflows : "creates"
    user_workflows ||--o{ user_workflow_phases : "has"
    user_workflow_phases ||--o{ user_workflow_tasks : "contains"
    sessions ||--o{ session_workflow_tasks : "has"
    default_workflows ||--o{ default_workflow_phases : "has"
    default_workflow_phases ||--o{ default_workflow_tasks : "contains"
    default_workflow_tasks ||--o{ session_workflow_tasks : "referenced_by"

Relations entre entités

Users (Utilisateurs) :

Possède des Sessions (via owner_id)
Possède des Contacts (via owner_id)
Possède des Quotes (via owner_id)
Possède des Invoices (via owner_id)
Possède des Workflows (via owner_id)
Possède des Mobile Push Tokens (via owner_id) - tokens pour notifications push mobiles

Sessions (Sessions) :

A plusieurs Contacts (via session_contacts)
A plusieurs Tags (via session_tags)
A plusieurs Providers (via session_providers)
Peut avoir des Quotes (via session_id)
Peut avoir des Invoices (via session_id)
A une Checklist (via session_checklists)
A des Fichiers (via session_files)
A des Workflow Tasks (via session_workflow_tasks) - inclut workflows personnalisés et notifications système ✅

Contacts (Contacts) :

Participe à plusieurs Sessions (via session_contacts)
Peut avoir des Quotes (via contact_id)
Peut avoir des Invoices (via contact_id)
A des Fichiers (via contact_files)

Quotes (Devis) :

Appartient à un User (via owner_id)
Peut être lié à une Session (via session_id)
Est pour un Contact (via contact_id)
A plusieurs Items (via quote_items)

Invoices (Factures) :

Appartient à un User (via owner_id)
Peut être lié à une Session (via session_id)
Est pour un Contact (via contact_id)
A plusieurs Items (via invoice_items)
Peut avoir des Payments (via invoice_id)

Cycle de vie des données

Création :

Utilisateur crée une entité (session, contact, devis, etc.)
Validation des données (Zod)
Insertion en base de données
Intégrations déclenchées (Google Calendar, notifications, etc.)
Notification temps réel via WebSocket

Modification :

Utilisateur modifie une entité
Validation des données
Mise à jour en base de données
Audit log créé
Intégrations mises à jour si nécessaire
Notification temps réel

Suppression :

Utilisateur supprime une entité
Vérification des dépendances
Suppression en cascade si nécessaire
Audit log créé
Nettoyage des intégrations (Google Calendar, fichiers, etc.)

Archivage :

Les données sont conservées selon les règles RGPD
Les données peuvent être exportées avant suppression
Les logs d'audit sont conservés pour traçabilité

5. Intégrations Externes

Google Calendar

Objectif : Synchronisation bidirectionnelle entre sessions et événements Google Calendar.

Fonctionnalités :

✅ Synchronisation bidirectionnelle : Modifications dans Google Calendar → CRM et vice versa
✅ Scheduler automatique : Synchronisation toutes les 5 minutes
✅ Résolution de conflits : Gestion intelligente des conflits (timestamp last_modified)
✅ Événements récurrents : Support complet des événements récurrents avec exceptions
✅ Création calendrier dédié : Création automatique d'un calendrier "Aaperture" dans Google Calendar
✅ Gestion disponibilité : Blocage de créneaux dans Google Calendar
✅ Réservations publiques : Création d'événements [MEETING] pour les réservations

Configuration :

OAuth 2.0 avec scopes calendar.events.owned et calendar
Tokens stockés de manière sécurisée (encryptés)
Refresh automatique des tokens

Références :

Documentation : docs/CALENDAR_SYNC_ARCHITECTURE.md
Backend : backend/src/google-calendar/

Stripe

Objectif : Gestion des paiements en ligne et des abonnements.

Fonctionnalités :

✅ Paiements factures : Paiement sécurisé des factures via Payment Intents
✅ Abonnements : Gestion des abonnements (FREE, BASIC, PRO) avec cycles mensuels/annuels
✅ Collecte méthodes de paiement : SetupIntent pour collecter les cartes
✅ Webhooks : Synchronisation automatique des événements Stripe
✅ Historique paiements : Suivi complet de tous les paiements
✅ Gestion abonnements : Création, annulation, reprise d'abonnements

Configuration :

Clés API Stripe (secret key, publishable key)
Webhook secret pour vérification
Price IDs configurables via interface admin

Références :

Documentation backend : backend/src/stripe/README.md

Notion

Objectif : Recherche et intégration avec Notion pour centraliser les informations.

Fonctionnalités :

✅ Recherche Notion : Recherche dans les pages et bases de données Notion
✅ Intégration Global Search : Résultats Notion dans la recherche globale
✅ Authentification OAuth : Connexion avec compte Notion

Configuration :

OAuth Notion avec clés client
Tokens stockés de manière sécurisée

Références :

Backend : backend/src/notion/

OpenAI

Objectif : Intelligence artificielle pour assistant conversationnel et automatisations.

Fonctionnalités :

✅ Assistant conversationnel : Chat avec l'IA pour questions et actions
✅ Génération d'actions : Traduction de prompts en actions structurées
✅ Création assistée : Génération de brouillons d'entités
✅ Rapports intelligents : Génération de rapports personnalisés
✅ Rédaction assistée : Génération d'emails, descriptions, notes
✅ Détection doublons : Détection de contacts similaires

Configuration :

Clés API OpenAI configurées par utilisateur (dans les paramètres)
Modèle configurable (GPT-4, GPT-3.5, etc.)
Clés encryptées en base de données

Références :

Documentation : docs/AI_SEARCH_ARCHITECTURE.md
Backend : backend/src/agent/, backend/src/ai-assistant/, backend/src/openai/

Email (SMTP/Gmail)

Objectif : Envoi d'emails et tracking.

Fonctionnalités :

✅ Envoi emails : Envoi via SMTP ou Gmail API
✅ Templates : Templates personnalisables avec variables
✅ Tracking : Suivi des ouvertures (pixel) et clics (liens)
✅ Emails planifiés : Planification d'envoi d'emails
✅ Configuration par utilisateur : Chaque utilisateur configure ses propres credentials

Configuration :

SMTP custom : Host, port, username, password
Gmail : OAuth avec Gmail API
Credentials stockés de manière sécurisée (encryptés)

Références :

Backend : backend/src/communication/, backend/src/email-tracking/

Cloudflare R2

Objectif : Stockage des fichiers (photos, PDFs, documents).

Fonctionnalités :

✅ Upload fichiers : Upload sécurisé avec presigned URLs
✅ Download fichiers : Téléchargement via signed URLs
✅ Stockage PDFs : Stockage des PDFs générés (devis, factures, rapports)
✅ Stockage photos : Stockage des photos de sessions

Configuration :

Credentials R2 (access key, secret key, bucket name)
Public URL optionnelle pour CORS

Références :

Backend : backend/src/storage/

Sentry (Error Tracking)

Objectif : Monitoring des erreurs et traçabilité pour debugging.

Fonctionnalités :

✅ Backend : Capture automatique des erreurs 5xx avec contexte utilisateur/requête
✅ Frontend : Capture des erreurs JavaScript avec session replay
✅ Worker : Erreurs des jobs BullMQ capturées
✅ Contexte utilisateur : ID et email attachés aux erreurs
✅ Performance : Transaction tracing pour API et pages

Configuration :

SENTRY_DSN : DSN backend (NestJS)
VITE_SENTRY_DSN : DSN frontend (React)
SENTRY_RELEASE : Version (auto-set au commit SHA en CI)

Références :

Documentation : docs/SENTRY_SETUP.md
Backend : backend/src/common/sentry/
Frontend : frontend/src/lib/sentry.ts

6. Fonctionnalités Transversales

Système de permissions

Objectif : Gestion fine des accès par plan d'abonnement.

Fonctionnalités :

✅ Plans d'abonnement : FREE, BASIC, PRO, ADMIN
✅ Permissions granulaires : Permissions par fonctionnalité (CREATE_SESSION, UPLOAD_FILE, etc.)
✅ Limites de ressources : Limites numériques par plan (max_projects, max_contacts, max_storage_mb)
✅ Guards : Décorateurs pour vérifier les permissions sur les endpoints
✅ Overrides : Possibilité d'override de permissions pour des utilisateurs spécifiques

Structure :

subscription_plans : Plans disponibles
permissions : Liste de toutes les permissions
plan_permissions : Association plans ↔ permissions
plan_limits : Limites par plan
user_subscriptions : Abonnements actifs des utilisateurs
user_permission_overrides : Overrides de permissions

Références :

Documentation backend : backend/src/permissions/README.md

Multi-utilisateurs et organisations

Objectif : Collaboration entre utilisateurs et partage de ressources.

Fonctionnalités :

✅ Organisations : Création d'organisations pour regrouper des utilisateurs
✅ Membres : Ajout de membres à une organisation
✅ Partage de ressources : Partage de sessions, contacts, devis, factures
✅ Invitations : Système d'invitations avec codes et tokens
✅ Amis : Système d'amis (friends) pour collaboration
✅ Rôles : Rôles dans les organisations (OWNER, MEMBER)

Structure :

organizations : Organisations
organization_members : Membres d'organisations
organization_resource_shares : Partage de ressources
organization_invitations : Invitations à rejoindre
user_friends : Relations d'amitié

Références :

Documentation backend : backend/src/organizations/README.md, backend/src/invitations/README.md, backend/src/friends/README.md

Export/Import

Objectif : Gestion des données (export, import, sauvegarde).

Fonctionnalités :

✅ Export multi-formats : CSV, Excel (XLSX), JSON, PDF
✅ Export par entité : Sessions, contacts, devis, factures, ou tout
✅ Export RGPD : Export complet des données utilisateur
✅ Import CSV/Excel : Import de contacts, sessions, devis, factures
✅ Mapping automatique : Auto-détection du mapping de colonnes
✅ Validation : Validation des données importées avec rapport d'erreurs
✅ Exports planifiés : Exports automatiques récurrents
✅ Templates d'export : Templates réutilisables avec champs sélectionnés

Références :

Documentation : docs/EXPORT_SYSTEM.md, docs/IMPORT_SYSTEM.md
Backend : backend/src/export/, backend/src/import/, backend/src/scheduled-exports/, backend/src/export-templates/

PWA (Progressive Web App)

Objectif : Application installable avec support offline.

Fonctionnalités :

✅ Service Worker : Cache automatique et support offline
✅ Installable : Ajout à l'écran d'accueil (mobile et desktop)
✅ Manifest : Configuration PWA complète avec raccourcis
✅ Cache stratégique : Cache intelligent pour assets, API calls, images, fonts

Références :

Frontend : Configuration PWA dans frontend/vite.config.ts

Notifications temps réel

Objectif : Notifications instantanées via WebSocket.

Fonctionnalités :

✅ WebSocket : Communication bidirectionnelle temps réel
✅ Notifications in-app : Notifications dans l'interface
✅ Push notifications : Notifications navigateur même quand l'app est fermée
✅ Événements : Émission d'événements pour toutes les actions importantes

Références :

Documentation backend : backend/src/websocket/README.md
Documentation frontend : frontend/src/client/websocket/README.md

Système de progression

Objectif : Gamification avec XP, niveaux, badges, défis.

Fonctionnalités :

✅ XP et niveaux : 7 niveaux (Apprenti → Légende) avec progression exponentielle
✅ Badges : 20+ badges dans différentes catégories
✅ Défis : Défis quotidiens, hebdomadaires, mensuels
✅ Classements : Leaderboards par type (XP total, CA mensuel, etc.)
✅ Aaperture Coins : Monnaie virtuelle gagnée via progression
✅ Boutique de récompenses : Récompenses disponibles (templates, fonctionnalités, visuels, formations)

Références :

Documentation backend : backend/src/progression/README.md

Portail Client (LOT D - En planification) 🚀

Objectif : Portail public sécurisé pour les clients permettant de centraliser la relation projet, réduire les emails de suivi, et améliorer l'expérience client.

Fonctionnalités prévues :

🚀 Lien token sécurisé : Génération de liens publics avec tokens hashés, scopes granulaires, expiration
🚀 Hub centralisé : Vue unifiée avec documents (devis, factures, contrats), timeline, livraisons
🚀 Tasks client : Questionnaires et tâches pour le client (infos manquantes, préférences)
🚀 Paiement direct : Intégration Stripe pour paiement des factures via le portail
🚀 Audience control : ANYONE_WITH_LINK ou CONTACTS_ONLY avec restriction par contacts
🚀 Timeline projet : Événements affichables (devis envoyé, facture payée, session programmée, etc.)

Architecture :

4 tables : client_portal_links, client_portal_tasks, client_portal_timeline_events, client_portal_access_logs
Token sécurisé : Hash SHA-256 avec pepper, jamais stocké en clair
Scopes : READ_DOCS, PAY_INVOICES, SIGN_CONTRACTS, SUBMIT_TASKS, VIEW_FILES
Intégrations : Stripe (paiements), R2 (fichiers), quotes/invoices/contracts existants

Statut : 🚀 En planification - Architecture et plan d'implémentation détaillés disponibles

Références :

Documentation : docs/PLAN_AMELIORATIONS_CRM.md - Section "Insights Proactifs & Intelligence > LOT D"

7. Cas d'Usage Typiques

Workflow complet d'un mariage

Scénario : Un photographe gère un mariage de A à Z.

Prise de contact :
- Le client remplit un formulaire de contact public (lead form)
- Un contact est créé automatiquement
- Notification au photographe
Création de la session :
- Le photographe crée une session "Mariage" avec date, lieu, contacts (mariés, témoins)
- Application d'un template de checklist "Mariage"
- Génération automatique d'une roadmap avec météo et horaires soleil
- Création d'un événement dans Google Calendar
Devis :
- Création d'un devis avec les prestations (cérémonie, cocktail, soirée)
- Génération du PDF
- Envoi par email au client avec lien sécurisé
- Tracking de l'ouverture et du clic
Acceptation :
- Le client accepte le devis via le lien sécurisé
- Le statut du devis passe à ACCEPTED
- Notification au photographe
Facturation :
- Création d'une facture à partir du devis accepté
- Envoi par email avec lien de paiement Stripe
- Le client paie en ligne
- Le statut de la facture passe à PAID
- Notification au photographe
Préparation :
- Le photographe suit la checklist (équipement, batteries, cartes mémoire)
- Consultation de la roadmap pour planifier la journée
- Vérification de la météo
Jour J :
- Le photographe suit la checklist en temps réel
- Upload des photos pendant la journée (optionnel)
Post-production :
- Upload des photos finales
- Mise à jour du statut de la session à COMPLETED
- Envoi des photos au client
Suivi :
- Le client peut consulter toutes les informations via le lien client (portail client)
- Le photographe peut générer un rapport analytics pour analyser les performances
- 🚀 Futur : Le client accède au portail client pour voir la timeline, payer les factures, remplir des questionnaires, accéder aux livraisons

Gestion d'un client récurrent

Scénario : Un photographe suit un client sur plusieurs sessions.

Première session :
- Création du contact avec toutes les informations
- Création de la première session (séance portrait)
- Devis et facturation
Sessions suivantes :
- Création de nouvelles sessions liées au même contact
- Consultation de l'historique du client (toutes les sessions précédentes)
- Réutilisation des informations (adresse, préférences)
Relation long terme :
- Le photographe peut voir toutes les interactions avec le client
- Tracking des emails envoyés
- Analyse de la valeur client (revenus totaux, nombre de sessions)

Facturation et paiements

Scénario : Cycle complet devis → facture → paiement.

Création devis :
- Le photographe crée un devis avec lignes (prestations, quantités, prix)
- Application d'un template personnalisé
- Génération du PDF
Envoi :
- Envoi par email avec lien sécurisé
- Tracking de l'ouverture et du clic
- Rappel automatique si pas de réponse après X jours
Acceptation :
- Le client accepte le devis
- Le statut passe à ACCEPTED
Création facture :
- Conversion du devis en facture
- Numérotation automatique
- Génération du PDF
Paiement :
- Envoi de la facture avec lien de paiement Stripe
- Le client paie en ligne avec sa carte
- Confirmation de paiement en temps réel
- Le statut passe à PAID
Rappels :
- Rappels automatiques si facture en retard
- Notifications au photographe

Planification et disponibilité

Scénario : Gestion du calendrier et des réservations.

Configuration disponibilité :
- Le photographe bloque ses créneaux de vacances
- Création de créneaux récurrents (disponible tous les lundis de 9h à 17h)
Réservation client :
- Un client consulte la page de réservation publique
- Sélection d'un créneau disponible
- Remplissage du formulaire (nom, email, téléphone, type de rendez-vous)
- Confirmation de réservation
Synchronisation :
- Création automatique d'un événement [MEETING] dans Google Calendar
- Notification au photographe
- Le créneau devient indisponible pour les autres clients
Gestion :
- Le photographe peut voir toutes ses réservations dans le calendrier
- Modification ou annulation possible
- Le client reçoit un email de confirmation avec lien d'annulation

8. Points d'Extension et Améliorations

Domaines d'amélioration identifiés

Pour une liste complète et détaillée des améliorations possibles, consultez docs/PLAN_AMELIORATIONS_CRM.md qui organise toutes les améliorations par domaine fonctionnel.

Domaines principaux :

Insights Proactifs & Intelligence : ✅ LOT A - IA Proactive Insights (100% complété) - Système d'insights automatiques avec 8 règles déterministes, génération quotidienne, notifications, et interface complète
Portail Client : 🚀 LOT D - Portail Client Enrichi (en planification) - Portail public sécurisé pour centraliser la relation projet
Communication & Relances : Invitations portail client, emails planifiés, tracking
Analytics & Reporting : Tableaux de bord personnalisables, alertes sur métriques, graphiques interactifs
Export & Import : Import depuis autres sources (Google Contacts, Outlook), synchronisation bidirectionnelle
Recherche & Filtrage : Filtres sauvegardés, recherche par tags avancée, suggestions de recherche
Gestion des Contacts : Segmentation avancée, scoring de contacts, relations entre contacts, fusion de contacts
Gestion des Sessions : Rappels automatiques, améliorations calendrier, planification récurrente (✅ complété)
Gestion Financière : Améliorations Stripe, gestion avancée des paiements, rappels personnalisés
Communication : Templates emails avancés, SMS, intégration réseaux sociaux
Workflows : Éditeur visuel de workflows, plus d'actions automatiques
Sécurité : Améliorations GDPR, audit avancé, sécurité renforcée

Architecture extensible

Comment ajouter de nouvelles fonctionnalités :

Nouveau module backend :
- Créer le dossier dans backend/src/{module}/
- Créer {module}.module.ts, {module}.controller.ts, {module}.service.ts
- Ajouter les DTOs dans dto/
- Ajouter le module dans ApiModule ou un group module approprié
Nouveau module frontend :
- Créer les pages dans frontend/src/pages/{domain}/
- Créer les hooks API dans frontend/src/client/{module}/
- Ajouter les routes dans frontend/src/router.tsx
Nouvelle intégration :
- Créer le service dans backend/src/{integration}/
- Configurer les credentials dans user_metadata ou table dédiée
- Ajouter les endpoints d'authentification si nécessaire
Nouvelle entité :
- Créer la migration Liquibase dans infra/liquibase/changes/
- Ajouter les types dans backend/src/db/database.types.ts
- Créer le service et controller

APIs et hooks

Points d'intégration disponibles :

Webhooks :
- Stripe webhooks : POST /api/stripe/webhooks
- PayPal webhooks : POST /api/paypal/webhooks
Hooks système :
- Hooks de devis/factures : Voir docs/QUOTES_INVOICES_HOOKS.md
- Workflow triggers : Déclencheurs sur événements système
APIs publiques :
- Réservation publique : GET /api/public/booking/:userId/*
- Lead forms : POST /api/public/lead-forms/:formId/submit
- Client access : GET /client-access?token=...
- 🚀 Portail client : GET /api/public/client-portal/:token (en planification)
APIs internes :
- Tous les endpoints REST documentés dans OpenAPI
- WebSocket events pour notifications temps réel

Références :

OpenAPI : openapi/ (spécification complète)
Documentation hooks : docs/QUOTES_INVOICES_HOOKS.md
Documentation workflows : docs/WORKFLOW_TRIGGERS.md

📚 Références

Documentation principale

ARCHITECTURE.md - Architecture générale du système
BACKEND.md - Documentation backend détaillée
FRONTEND.md - Documentation frontend détaillée
Schémas des Scopes - Schémas détaillés de chaque module
PLAN_AMELIORATIONS_CRM.md - Liste complète des améliorations possibles

Documentation spécialisée

CALENDAR_SYNC_ARCHITECTURE.md - Architecture de synchronisation calendrier
AI_SEARCH_ARCHITECTURE.md - Architecture de recherche IA
WORKFLOW_TRIGGERS.md - Documentation des déclencheurs de workflows
EXPORT_SYSTEM.md - Documentation du système d'export
IMPORT_SYSTEM.md - Documentation du système d'import
BOOKING_SYSTEM.md - Documentation du système de réservation

Documentation technique

QUEUE_SYSTEM.md - Système de queue et traitement asynchrone
TIMEOUT_MANAGEMENT.md - Gestion des timeouts
PERMISSIONS_ARCHITECTURE.md - Architecture des permissions

Dernière mise à jour : 2025-01-XX

Version du document : 1.0

📋 Table des Matières​

1. Introduction et Contexte​

Qu'est-ce qu'un CRM ?​

Aaperture : CRM spécialisé pour photographes​

Public cible​

Valeur ajoutée​

2. Vue d'Ensemble du Produit​

Modules principaux​

Architecture générale​

Flux de données principaux​

3. Modules et Fonctionnalités Détaillés​

3.1 Sessions & Projets​

3.2 Contacts & Clients​

3.3 Devis & Factures​

3.4 Calendrier & Planification​

3.5 IA Proactive Insights ✅​

3.6 Recherche & IA​

3.6 Communication & Notifications​

3.7 Analytics & Reporting​

3.8 Workflows & Automatisation​

3.9 Sécurité & Conformité​

3.10 Mobile​

4. Entités et Relations​

Modèle de données principal​

Relations entre entités​

Cycle de vie des données​

5. Intégrations Externes​

Google Calendar​

Stripe​

Notion​

OpenAI​

Email (SMTP/Gmail)​

Cloudflare R2​

Sentry (Error Tracking)​

6. Fonctionnalités Transversales​

Système de permissions​

Multi-utilisateurs et organisations​

Export/Import​

PWA (Progressive Web App)​

Notifications temps réel​

Système de progression​

Portail Client (LOT D - En planification) 🚀​

7. Cas d'Usage Typiques​

Workflow complet d'un mariage​

Gestion d'un client récurrent​

Facturation et paiements​

Planification et disponibilité​

8. Points d'Extension et Améliorations​

Domaines d'amélioration identifiés​

Architecture extensible​

APIs et hooks​

📚 Références​

Documentation principale​

Documentation spécialisée​

Documentation technique​

📋 Table des Matières

1. Introduction et Contexte

Qu'est-ce qu'un CRM ?

Aaperture : CRM spécialisé pour photographes

Public cible

Valeur ajoutée

2. Vue d'Ensemble du Produit

Modules principaux

Architecture générale

Flux de données principaux

3. Modules et Fonctionnalités Détaillés

3.1 Sessions & Projets

3.2 Contacts & Clients

3.3 Devis & Factures

3.4 Calendrier & Planification

3.5 IA Proactive Insights ✅

3.6 Recherche & IA

3.6 Communication & Notifications

3.7 Analytics & Reporting

3.8 Workflows & Automatisation

3.9 Sécurité & Conformité

3.10 Mobile

4. Entités et Relations

Modèle de données principal

Relations entre entités

Cycle de vie des données

5. Intégrations Externes

Google Calendar

Stripe

Notion

OpenAI

Email (SMTP/Gmail)

Cloudflare R2

Sentry (Error Tracking)

6. Fonctionnalités Transversales

Système de permissions

Multi-utilisateurs et organisations

Export/Import

PWA (Progressive Web App)

Notifications temps réel

Système de progression

Portail Client (LOT D - En planification) 🚀

7. Cas d'Usage Typiques

Workflow complet d'un mariage

Gestion d'un client récurrent

Facturation et paiements

Planification et disponibilité

8. Points d'Extension et Améliorations

Domaines d'amélioration identifiés

Architecture extensible

APIs et hooks

📚 Références

Documentation principale

Documentation spécialisée

Documentation technique