Portée produit Aaperture — document unique
Ce texte décrit l’ensemble du produit dans une lecture continue : acteurs, surfaces, flux métier, domaines fonctionnels, règles transverses et socle technique. Il vise l’autonomie : les détails d’implémentation (API OpenAPI, schéma SQL précis, contrats d’agents) restent dans le dépôt, mais vous n’avez pas besoin d’ouvrir d’autres markdown pour comprendre ce qu’est Aaperture et ce qu’il couvre.
1. Proposition de valeur et personas
Aaperture est une plateforme CRM et de livraison centrée photographe. Un studio (indépendant ou petite équipe) y gère tout le cycle : prospection (formulaires publics, pipeline), vente (devis, propositions signables, contrats), planification (calendrier, réservation en ligne), préparation et exécution de séances (sessions, informations client, documents), collaboration (messagerie, portail), livraison média (galeries, sélection, téléchargements, diaporamas dont rendu vidéo), facturation (contexte France / Union européenne), automatisation (workflows), pilotage (insights, notifications) et productivité (recherche globale, assistant conversationnel Iris).
Persona principal — photographe / staff : utilisateur authentifié sur l’application web, rattaché à une organisation (studio), avec des permissions qui limitent ou autorisent les modules (contacts, sessions, facturation, réglages sensibles, etc.).
Persona client : personne qui reçoit un accès au portail (/portal/*) : compte global (plusieurs sessions visibles selon ce que le studio expose), documents, messages, fichiers, galeries, paiements lorsque le flux est activé.
Visiteur anonyme : parcourt les surfaces publiques (réservation, proposition commerciale sans compte studio, galerie publique, soumission de formulaire lead) selon les liens ou slugs fournis par le studio.
Mobile : application dédiée qui reprend les parcours clés avec des règles de parité UX (navigation, composants, typographie) alignées sur le web.
2. Surfaces produit (qui voit quoi)
| Surface | Accès | Fonction |
|---|---|---|
| Application web studio | JWT (connexion classique) et OAuth Google | CRM complet, configuration, production, facturation, automatisations, insights, Iris, recherche |
| Portail client | Compte portail | Sessions autorisées, documents, messagerie, fichiers, réglages, galeries (sélection / téléchargement), paiement si proposé |
| Réservation publique | Sans compte studio | Choix de créneaux, réservation, confirmation ; pages tenant (marque du studio) |
| Proposition publique | Lien token ou slug | Consultation d’offre, options / add-ons liés au type de séance, acceptation, mise à jour du devis côté serveur ; en fin de parcours, invitation à rejoindre le portail si pertinent |
| Galerie publique | URL slug, éventuellement mot de passe ou contrôle d’identité | Consultation, favoris, panier de téléchargement, lecture du diaporama et, si généré, de la vidéo publiée |
| Formulaires lead | Embed (souvent iframe) | Collecte de demandes ; côté studio : liste des soumissions, création ou liaison de contact (automatique ou manuelle) |
| Legacy | L’ancienne base /client n’est plus le chemin principal ; le produit standardise sur /portal |
Direction produit annexe — add-on Gmail : intégration prévue dans Gmail (Google Workspace) pour contextualiser un email entrant avec le CRM et déclencher des actions (sans recréer une boîte mail complète dans Aaperture).
3. Parcours métier de bout en bout
Le même périmètre peut se lire comme une chaîne plutôt que comme une liste de modules.
-
Acquisition — Un visiteur remplit un lead form ; le studio importe ou crée des contacts ; les opportunités rentrent dans le pipeline (
/pipeline, fiche/pipeline/$leadId). -
Qualification et vente — Devis, contrats, PDF ; suivi des statuts et des montants sur la session liée.
-
Planification — Calendrier multi-vues (jour / semaine / etc.), synchronisation avec Google Calendar quand l’utilisateur la connecte ; le booking public propose des créneaux sans exposer toute la complexité du calendrier interne.
-
Préparation de séance — La session (mariage, portrait, corporate…) porte statut, blocs financiers, documents et renseignements : modèles d’information configurables par le studio, saisie côté client (portail ou flux invité), relances possibles via workflows.
-
Collaboration — Fils de messages (client et, le cas échéant, « amis » / tiers), pièces jointes, mises à jour temps réel (WebSocket) ; les mêmes conversations sont accessibles depuis l’app studio, le portail et le contexte contact quand c’est pertinent.
-
Livraison — Galeries : upload côté studio, organisation, partage ; côté client / public : sélection, favoris, téléchargements (y compris via panier). Diaporamas : édition (timeline, modes de couverture), lecture synchronisée sur les surfaces autorisées ; rendu MP4 délégué à une file d’attente dédiée pour ne pas bloquer l’API.
-
Encaissement — Factures avec numérotation séquentielle, immutabilité après émission dans les cas réglementés, avoirs, intégration PayPal et règles de calcul / validation orientées France–UE.
-
Fidélisation et réactivité — Insights (règles, centre de notifications), rappels proactifs ; Iris pour poser des questions métier et exécuter des actions (création / mise à jour d’entités) avec contexte conversationnel.
-
Conformité et exploitation — Emails transactionnels (templates système, expéditeur configuré), thème fiscal / conservation lorsque le studio est concerné ; côté ops : pipelines de déploiement, sauvegardes, secrets, monitoring (Sentry, métriques de résilience).
4. Application photographe / staff — domaines en détail
4.1 CRM cœur : contacts, sessions, pipeline
Contacts sont la base relationnelle : coordonnées, localisation, tags, détection de doublons, lien vers une ou plusieurs sessions. Les droits d’accès peuvent restreindre la visibilité ou l’édition selon le rôle dans l’organisation.
Sessions représentent un projet de prise de vue (ou un regroupement métier équivalent) : type de prestation, dates, statut, équipe, pièces jointes « documents », vue financière (devis, factures, acomptes) et liens vers le calendrier et les galeries.
Pipeline est le workspace commercial : liste de leads / opportunités, filtres, actions rapides, sélection multiple pour opérations groupées, et page lead dédiée pour travailler une opportunité sans tout mélanger avec la fiche contact générique seule.
4.2 Documents commerciaux : devis, factures, contrats
Le studio émet des devis (quotes), des factures et des contrats. La génération PDF est intégrée. Des hooks métier permettent d’accrocher des comportements lors des transitions (validation, envoi, paiement, etc.) sans que ce document liste chaque hook.
Exports de données (CSV, Excel, JSON selon les besoins) et exports planifiés permettent des extractions récurrentes ou ponctuelles pour compta ou archivage.
4.3 Calendrier et réservation publique
Le calendrier interne supporte plusieurs vues et la sync Google (disponibilité, événements). Le booking public affiche des créneaux réservables pour le tenant, avec confirmation et parcours volontairement légers (moins de dépendances lourdes côté chargement initial) pour l’expérience visiteur.
4.4 Galeries, partage et diaporamas
Côté studio : bibliothèque de galeries en évolution vers une vraie surface « bibliothèque » (galeries parfois non assignées à une session), tout en gardant l’onglet session comme contexte rapide. Côté livraison : partage vers des destinataires (y compris nominativement dans les évolutions prévues), panier de téléchargement, notifications possibles côté photographe lors de téléchargements.
Diaporama : éditeur orienté timeline, politique de couverture et de lecture cohérente entre owner, portail et public ; rendu vidéo asynchrone sur une file gallery-slideshow distincte des exports génériques.
4.5 Messagerie, Iris et recherche globale
Messagerie : conversations par thread, fichiers images ou autres avec prévisualisation, uploads résilients, événements temps réel pour rafraîchir les listes et le fil sans recharger toute la page.
Iris (nom produit de l’assistant) : chat workspace transversal au CRM — pas seulement un widget : variantes d’affichage (panneau latéral, fenêtre, mobile, plein écran) autour d’un même concept, actions structurées (création / mise à jour d’entités avec formulaires inline), pièces jointes, mémoire courte métier pour rester dans le contexte du studio.
Recherche globale : palette de commande et recherche textuelle sur les entités pertinentes ; évolutions assistées par IA pour reformuler ou regrouper des résultats selon les phases produit.
4.6 Insights et workflows
Insights : règles métier qui déclenchent des notifications (in-app, email selon configuration) ; centre pour consulter l’historique et l’état des signaux.
Workflows : modèles en phases et tâches, déclencheurs (événements métier), instances rattachées aux sessions ; éditeur visuel côté configuration. Le moteur a une architecture documentée (runtime, limites actuelles) ; ce document retient seulement l’idée : automatiser la répétition des étapes studio (relances, checklists, invitations aux renseignements).
4.7 Organisations, amis et invitations
Une organisation regroupe utilisateurs, réglages et données. Le graphe amis / invitations permet partage léger, cooptation, notifications sociales autour des contacts et du portail — sans confondre avec le rôle « staff » classique.
4.8 Formulaires lead
Formulaires embarquables sur le site du photographe ; côté studio : file des soumissions, contrôle qualité avant conversion en contact, champs adaptés au type d’événement (nombre d’invités, etc.).
4.9 Configuration, administration et navigation
Réglages types de séance, prestataires, barèmes et grilles tarifaires, plans de paiement, types de tâches, configuration des workflows, templates de renseignements de session par défaut, expéditeur email, etc.
La navigation (sidebar, favoris, raccourcis clavier) suit une spec d’ordre et des identifiants stables pour ne pas casser les habitudes ni les analytics à chaque release.
4.10 Facturation et paiements (rappel fonctionnel)
Numérotation séquentielle des factures, cycle de vie (brouillon → émis → payé / impayé), calculs (TVA, remises, arrondis) et validations métier ; PayPal comme passerelle notable ; orientation conformité Europe (sans figer ici la liste des textes).
4.11 Fiscalité et conservation (lorsque applicable)
Pour les studios concernés : trajectoire attestation, conservation longue durée, archivage et FAQ comptable — le détail juridique et procédural vit dans le dossier fiscal du dépôt, mais le scope produit inclut bien cette couche compliance optionnelle.
5. Portail client (/portal/*)
Le portail est le hub client après authentification : liste (ou accès) aux sessions qui lui sont attribuées, documents (devis à signer, factures, contrats), messagerie avec le studio, fichiers échangés, réglages de compte, galeries avec les mêmes primitives de sélection et téléchargement que sur le web public lorsque le studio ouvre ce flux, et paiement lorsque activé.
Le studio contrôle quoi apparaît par session et par type de document ; le client voit une expérience cohérente avec les emails et liens qu’il a reçus (devis, invitation galerie, etc.).
6. Surfaces publiques (sans compte studio)
- Galerie : URL connue du client ; protection optionnelle ; favoris ; téléchargements groupés ; lecture diaporama / vidéo si publiée.
- Booking : fenêtre de réservation alignée visuellement avec la marque du tenant.
- Lead form : même logique d’embed que ci-dessus.
7. Mobile
L’app mobile reprend les mêmes règles métier que le web sur les écrans exposés : authentification, consultation des entités autorisées, messagerie, notifications push navigateur côté web (PWA) et stratégies équivalentes côté natif selon les modules livrés. L’objectif est d’éviter deux « vérités » produit (web vs mobile) sur les mêmes flux.
8. Plateforme technique (vue d’ensemble)
Monorepo typique : backend NestJS (TypeScript, Node 22), frontend React 18, OpenAPI partagée, infra (Docker, reverse proxy, Liquibase), éventuellement service Python FastAPI pour charges lourdes (ML, traitements longs).
Données : PostgreSQL, accès Kysely (requêtes typées), migrations Liquibase. Fichiers : stockage objet compatible S3 (usage Cloudflare R2). Cache et limites : Redis. Auth : JWT + OAuth Google, garde-fous sur le statut utilisateur (compte actif).
Frontend : TanStack Router et Query, Zustand, TanStack Form, Tailwind, composants style shadcn, i18n react-i18next (fr + en), PWA et notifications push web où activées.
Temps réel : Socket.IO côté serveur et client pour messages et notifications.
Asynchrone : BullMQ — notamment un routeur sur la file exports (exports tabulaires, certains traitements documents), une file gallery-slideshow pour le rendu vidéo des diaporamas, des jobs planifiés, OCR et extraction, notifications différées. Les workers peuvent être activés ou désactivés par variables d’environnement pour le développement local.
Qualité : lint/tests au niveau racine du dépôt ; télémétrie d’erreurs (Sentry) et docs d’observabilité / résilience pour la production.
Sécurité : politiques de données, procédures opérationnelles, bonnes pratiques dans les guides agents du dépôt (non recopiés ici mot pour mot).
Déploiement : pipeline CI/CD documenté (GitLab), gestion des secrets (SOPS, fichiers chiffrés), guides de reprise après sinistre et d’alignement des environnements.
9. Permissions, multi-tenant et API
Le produit est multi-tenant par organisation : presque toute donnée métier est scopée au studio. Les permissions combinent rôles, parcours « friend », et règles fines sur les modules (lecture seule facturation, accès messagerie, etc.). Les schémas de scopes décrivent finement quels endpoints acceptent quel type d’acteur (staff, client, public) ; l’idée générale est : jamais mélanger les contextes public token, JWT client et JWT staff sans garde explicite.
10. Synthèse
Aaperture, c’est un CRM photographe qui enchaîne pipeline et vente documentaire, calendrier et booking, sessions et collaboration client, livraison média riche (galeries, diaporamas, téléchargements, vidéo asynchrone), facturation UE, automatisations, insights, Iris et recherche globale, sur web studio, portail, pages publiques et mobile, avec workers, stockage objet et temps réel pour ce qui dépasse le simple CRUD synchrone.
11. Où creuser (lecture facultative)
Une fois la portée comprise, la doc du dépôt regroupe les plans par chantier (priorités, roadmap, CRM, galeries, workflows, billing, fiscal…) et les références techniques (architecture, backend, frontend, files, workers). Le fichier APP_OVERVIEW.md reste l’index court par liste ; PRIORITES.md et ROADMAP.md répondent à « quoi faire maintenant », pas à « quel est le périmètre fonctionnel total ».