Aller au contenu

Module Projection IA

Objectif

Projection IA permet à une société de générer des visuels assistés par IA à partir d'une ou deux images. Le module couvre :

  • génération d'une image modifiée ;
  • fusion d'une image principale avec une image de référence ;
  • contrôle d'accès via la feature FEATURE_PROJECTION_IA et les permissions projection ia / projection porte entrée ;
  • débit de crédits image avant génération ;
  • remboursement automatique du débit si la génération échoue ;
  • historique temporaire des générations ;
  • attribution de crédits par renouvellement d'abonnement ;
  • administration des packs, des crédits par plan et des crédits manuels ;
  • notifications email lors des créditations.

Le module remplace progressivement l'ancien vocabulaire projection porte entrée / door_projection. Des alias existent encore dans le code et dans les migrations.

Carte technique

flowchart TD
    Router["app/core/Router.php"] --> Controller["AiProjectionController"]
    Controller --> Service["AiProjectionService"]
    Controller --> Credits["AiProjectionCreditModel"]
    Controller --> Logs["AiProjectionLogModel"]
    Service --> OpenAI["OpenAIClient"]
    Credits --> Notifications["AiProjectionCreditNotificationService"]
    Notifications --> Mailer["MailerService"]
    Logs --> Uploads["public/uploads/ai_projection/history/<societe_id>/"]

    View["app/views/projection-ia.php"] --> Js["public/assets/js/projection-ia.js"]
    Js --> Controller

    CronCredits["ai_projection_subscription_credits_cron.php"] --> Credits
    CronCleanup["ai_projection_history_cleanup_cron.php"] --> Logs
    CronNotifications["ai_projection_credit_notifications_cron.php"] --> Notifications

Fichiers à connaître

Rôle Fichiers
Routage app/core/Router.php
Contrôleur app/controllers/AiProjectionController.php
Service IA app/services/ai_projection/AiProjectionService.php
Client OpenAI app/services/catalog/OpenAIClient.php
Crédits app/models/AiProjectionCreditModel.php
Historique app/models/AiProjectionLogModel.php
Notifications crédits app/services/AiProjectionCreditNotificationService.php
Vue app/views/projection-ia.php
Frontend public/assets/js/projection-ia.js
SQL app/bd/projection-ia.sql
Crons app/cron/ai_projection_subscription_credits_cron.php, app/cron/ai_projection_history_cleanup_cron.php, app/cron/ai_projection_credit_notifications_cron.php

Routes

Toutes les routes vérifiées passent par :

  • Auth::check() ;
  • requireFeatureAccess(FEATURE_PROJECTION_IA, APP_DIR . '/dashboard') ;
  • puis AiProjectionController.
Route Méthode Contrôleur Usage
projection-ia GET index() Page complète.
projection-ia/generate POST generate() Génération IA avec débit crédit.
projection-ia/logs GET logs() Logs admin.
projection-ia/settings GET settings() Paramètres admin : crédits par plan, packs, logs.
projection-ia/plan-credits POST savePlanCredits() Enregistrer les crédits par renouvellement de plan.
projection-ia/credit-packs GET/POST manageCreditPacks() Lister les packs actifs, créer/modifier/supprimer côté admin.
projection-ia/companies/search GET searchCompanies() Recherche de sociétés pour crédit admin.
projection-ia/credit-company POST creditCompany() Crédit manuel d'une ou plusieurs sociétés.
projection-ia/history GET history() Historique visible par la société courante.
projection-ia/history-entry GET historyEntry() Détail d'une génération.
projection-ia/history/delete POST deleteHistory() Suppression d'une entrée d'historique.
projection-porte-entree GET redirection Redirige vers projection-ia?mode=image_merge.
projection-porte-entree/generate POST generate() Alias legacy, force mode=image_merge si absent.
projection-porte-entree/logs GET logs() Alias legacy.

Point de vigilance vérifié : le bloc de routes Projection IA est dupliqué deux fois de suite dans Router.php. Comme il s'agit d'une chaîne elseif, le second bloc est normalement inatteignable. Toute modification de route doit tenir compte de cette duplication pour éviter une correction appliquée à un seul des deux blocs.

Accès et permissions

Le contrôleur refait un contrôle applicatif via enforceProjectionAccess() :

can('projection ia', 'view_all') || can('projection porte entrée', 'view_all')

Pour une requête AJAX, l'échec retourne un JSON success=false. Pour une page, l'utilisateur est redirigé vers le dashboard.

Les actions admin appellent ensuite requireAdmin() :

  • settings() ;
  • savePlanCredits() ;
  • manageCreditPacks() en POST ;
  • searchCompanies() ;
  • creditCompany() ;
  • logs().

manageCreditPacks() en GET reste accessible aux utilisateurs autorisés pour afficher les packs actifs.

Modes de génération

AiProjectionService expose deux modes.

Mode Constante Images requises Usage
single_edit MODE_SINGLE_EDIT primary_image Modifier une seule image selon des instructions.
image_merge MODE_IMAGE_MERGE primary_image + secondary_image Appliquer un détail, style ou matériau de la seconde image sur la première.

Compatibilité legacy :

  • door_swap est normalise vers image_merge ;
  • les anciens champs upload facade_image et door_image sont encore acceptes comme fallback pour primary_image et secondary_image.

Configuration OpenAI et images

Variables lues :

Variable Défaut Usage
OPENAI_API_KEY aucun Obligatoire pour générer.
OPENAI_BASE_URL https://api.openai.com/v1 Base API du client OpenAI.
OPENAI_AI_PROJECTION_MODEL aucun Modèle prioritaire pour Projection IA.
OPENAI_DOOR_PROJECTION_MODEL aucun Fallback legacy si le modèle Projection IA est absent.
AI_PROJECTION_MAX_IMAGE_SIZE_MB 10 Taille upload max, borne basse à 1 Mo.
DOOR_PROJECTION_MAX_IMAGE_SIZE_MB 10 Fallback legacy.
AI_PROJECTION_MAX_IMAGE_DIMENSION 1536 Dimension max avant compression, borne basse à 512 px.
DOOR_PROJECTION_MAX_IMAGE_DIMENSION 1536 Fallback legacy.
OPENAI_DOCUMENT_EXTRACTION_TIMEOUT 180 Timeout aussi utilisé par OpenAIClient.

Formats acceptés par AiProjectionService :

  • image/jpeg ;
  • image/png ;
  • image/webp.

Avant l'appel API, le service peut redimensionner l'image avec GD :

  • si imagecreatefromstring() existe ;
  • si l'image dépasse AI_PROJECTION_MAX_IMAGE_DIMENSION ;
  • sortie temporaire en JPEG qualité 85 ;
  • nettoyage des fichiers temporaires en finally.

Si GD n'est pas disponible ou si le redimensionnement échoue, l'image originale est transmise au client OpenAI.

Flux : génération

POST /projection-ia/generate suit cet ordre :

  1. Vérifier l'accès Projection IA.
  2. Normaliser mode.
  3. Construire les fichiers uploadés :
  4. primary_image ou fallback facade_image ;
  5. secondary_image ou fallback door_image.
  6. Débiter la société via AiProjectionCreditModel::debitCurrentSocieteForGeneration($mode).
  7. Si le débit échoue, retourner success=false avec le solde et cost_per_generation.
  8. Appeler AiProjectionService::generate().
  9. Enregistrer l'historique via AiProjectionLogModel::recordGeneration().
  10. Retourner le resultat IA et le nouveau solde.
  11. Si une exception survient après le débit, appeler refundGenerationDebit() avec l'id d'historique de débit.

Le coût d'une generation est fixe dans AiProjectionCreditModel::GENERATION_COST = 1.

Les admins ont un bypass crédit :

  • getCurrentSocieteCreditSummary() retourne credit_bypass=true ;
  • debitCurrentSocieteForGeneration() ne créé pas de ligne de débit et ne diminue pas le solde.

Credits image

Solde société

app/bd/projection-ia.sql ajouté sur societes :

  • ai_projection_credit_balance INT UNSIGNED NOT NULL DEFAULT 0 ;
  • ai_projection_credit_last_awarded_period_end DATETIME NULL.

AiProjectionCreditModel utilise SELECT ... FOR UPDATE dans lockSocieteCreditState() pour éviter les débits/credits concurrents sur une même société.

Historique crédits

Table ai_projection_credit_history :

  • operation_type : débit, credit, refund, etc. ;
  • amount ;
  • balance_before ;
  • balance_after ;
  • source_type ;
  • source_id ;
  • justification.

Sources vérifiées :

  • generation : débit d'une generation ;
  • generation_refund : remboursement automatique après échec ;
  • subscription_bonus : attribution liée au renouvellement d'abonnement ;
  • admin_adjustment : crédit manuel admin.

Credits par abonnement

Table ai_projection_plan_credits :

  • plan_id ;
  • credits_per_renewal ;
  • active ;
  • updated_by ;
  • updated_at.

getSocietesEligibleForSubscriptionRenewalCredits() sélectionne les sociétés :

  • rôle artisan ;
  • current_period_end non nul ;
  • plan actif dans ai_projection_plan_credits ;
  • credits_per_renewal > 0 ;
  • pas encore creditees pour cette période (current_period_end > ai_projection_credit_last_awarded_period_end ou champ nul).

creditSubscriptionRenewal() met à jour en transaction :

  • le solde ;
  • ai_projection_credit_last_awarded_period_end ;
  • l'historique ;
  • puis déclenche une notification de credit.

Credits admin

creditCompany() permet :

  • crédit d'une sélection de sociétés ;
  • crédit de toutes les sociétés si all_societies est présent ;
  • compatibilité legacy avec societe_id.

Règles vérifiées :

  • montant strictement positif ;
  • motif obligatoire ;
  • notification envoyée après commit.

Packs

Table ai_projection_credit_packs :

  • name ;
  • price ;
  • credit_amount ;
  • bonus ;
  • price_id ;
  • active ;
  • sort_order.

Le modèle permet de lister les packs actifs pour l'interface, et de créer/modifier/supprimer les packs côté admin.

Historique des générations

Table ai_projection_usage_logs :

  • societe_id, membre_id ;
  • mode ;
  • response_time_ms ;
  • tokens_consumed ;
  • instructions ;
  • primary_image_path ;
  • secondary_image_path ;
  • result_image_path ;
  • result_mime_type ;
  • expires_at ;
  • created_at.

Retention :

  • AiProjectionLogModel::HISTORY_RETENTION_DAYS = 7 ;
  • chaque generation expire a created_at + 7 jours ;
  • les lectures d'historique declenchent purgeExpiredHistorySilently() ;
  • le cron de purge appelle purgeExpiredHistory(2000).

Stockage fichiers :

  • chemin relatif : ai_projection/history/<societe_id>/ ;
  • chemin public : public/uploads/ai_projection/history/<societe_id>/ ;
  • images sources copiees avec préfixe source_primary_ et source_secondary_ ;
  • resultat stocke avec préfixe result_.

deleteHistoryEntry() doit supprimer la ligne et les fichiers associés. purgeExpiredHistory() supprime les fichiers des lignes expirées puis les lignes.

Accès historique :

  • une société voit ses lignes par societe_id ;
  • un admin peut voir les lignes de sa société active ou celles rattachees à son membre_id selon le contexte ;
  • seules les lignes non expirees avec result_image_path non vide sont renvoyees.

Notifications de credit

AiProjectionCreditNotificationService créé sa table de stockage à l'instanciation via ensureStorageSchema() :

ai_projection_credit_notifications :

  • societe_id ;
  • source_type ;
  • payload_json ;
  • status : pending, processing, sent, failed ;
  • retry_count ;
  • next_retry_at ;
  • last_error ;
  • sent_at ;
  • timestamps.

Comportement :

  • queueNotification() inséré une ligne pending ;
  • sendNotificationById() passe la ligne en processing, recharge le payload puis envoie ;
  • si l'envoi reussit, statut sent ;
  • en cas d'échec, retry après 300 s ;
  • abandon à partir de MAX_RETRIES = 3.

Le destinataire est resolu à partir de la société cible. Le service cherche un email valide pour construire et envoyer un message via MailerService.

Crons

Cron Rôle Commande CLI
ai_projection_subscription_credits_cron.php Attribue les crédits d'abonnement aux sociétés eligibles. php app/cron/ai_projection_subscription_credits_cron.php
ai_projection_history_cleanup_cron.php Purge l'historique expire et les fichiers associés. php app/cron/ai_projection_history_cleanup_cron.php
ai_projection_credit_notifications_cron.php Traite les notifications de crédits en attente. php app/cron/ai_projection_credit_notifications_cron.php

ai_projection_subscription_credits_cron.php journalise :

  • AI_PROJECTION_CREDITS_CRON_START ;
  • AI_PROJECTION_CREDITS_CRON_SOCIETE_START ;
  • AI_PROJECTION_CREDITS_CRON_SUCCESS ;
  • AI_PROJECTION_CREDITS_CRON_ERROR ;
  • AI_PROJECTION_CREDITS_CRON_FINISH ;
  • AI_PROJECTION_CREDITS_CRON_CRITICAL_ERROR.

ai_projection_history_cleanup_cron.php journalise :

  • AI_PROJECTION_HISTORY_CLEANUP_START ;
  • AI_PROJECTION_HISTORY_CLEANUP_FINISH ;
  • AI_PROJECTION_HISTORY_CLEANUP_ERROR.

Migrations et compatibilité legacy

projection-ia.sql fait plus qu'une création de tables :

  • créé ou met à jour la permission projection ia ;
  • migre projection porte entrée vers projection ia si nécessaire ;
  • créé/met à jour la feature id 43 nommee Projection IA ;
  • lie la feature aux plans 17, 18, 19, 20 ;
  • renomme door_projection_usage_logs vers ai_projection_usage_logs si l'ancienne table existe et pas la nouvelle ;
  • convertit les anciens modes vides ou door_swap en image_merge ;
  • ajouté les colonnes manquantes de l'historique de facon idempotente ;
  • ajouté les colonnes de crédits sur societes ;
  • crée les tables de crédits.

Ne pas separer ces migrations sans vérifier l'état de la base cible : elles portent la compatibilité entre l'ancien module porte d'entrée et le module Projection IA.

Frontend

app/views/projection-ia.php injecte notamment :

  • configuration des modes ;
  • résumé crédit ;
  • packs de crédits ;
  • données pour les panneaux admin ;
  • la page currentPage = projection-ia.

public/assets/js/projection-ia.js gère :

  • sélection du mode ;
  • uploads primary_image et secondary_image ;
  • appel projection-ia/generate ;
  • affichage du resultat ;
  • résumé du solde et coût par generation ;
  • historique ;
  • paramètres admin ;
  • packs ;
  • crédit manuel de sociétés ;
  • tiroirs/modales et validations UI.

Points de vigilance

  1. Le débit crédit se fait avant l'appel OpenAI. Garder le remboursement automatique en cas d'exception, sinon une erreur fournisseur consommera un credit.
  2. recordGeneration() retourne false sans bloquer la réponse si l'historique ne peut pas être stocke. Une generation peut donc reussir sans apparaitre dans l'historique.
  3. Les images sources et resultats sont stockes temporairement 7 jours. Ne pas allonger la retention sans revoir volume disque, données personnelles et purge.
  4. Le routage Projection IA est dupliqué dans Router.php. Nettoyer ce doublon avant une refonte de routes reduirait le risque d'ecart.
  5. Le client OpenAI utilise aussi OPENAI_DOCUMENT_EXTRACTION_TIMEOUT. Modifier ce timeout impacte potentiellement d'autres usages du client catalogue.
  6. La table ai_projection_credit_notifications est créée par le service PHP, pas par projection-ia.sql. Sur un environnement strict, vérifier que l'utilisateur SQL applicatif a le droit CREATE TABLE.
  7. Les variables legacy OPENAI_DOOR_PROJECTION_MODEL, DOOR_PROJECTION_MAX_IMAGE_SIZE_MB, DOOR_PROJECTION_MAX_IMAGE_DIMENSION sont encore lues comme fallback. Les supprimer demande une migration de configuration.

Vérification conseillée

  1. Lancer php -l app/cron/ai_projection_subscription_credits_cron.php.
  2. Vérifier .env : OPENAI_API_KEY, OPENAI_AI_PROJECTION_MODEL, limites image.
  3. En compte non admin avec crédits, générer en single_edit puis vérifier :
  4. solde decremente ;
  5. ligne ai_projection_credit_history source generation ;
  6. ligne ai_projection_usage_logs ;
  7. fichiers dans public/uploads/ai_projection/history/<societe_id>/.
  8. Simuler une erreur OpenAI après débit et vérifier le remboursement generation_refund.
  9. Tester image_merge avec deux images.
  10. Tester un solde insuffisant : pas d'appel IA attendu.
  11. En admin, charger settings, modifier crédits par plan et packs.
  12. Lancer les trois crons en CLI et vérifier les logs ActivityLogger.

Questions ouvertes

  • Aucun test automatisé dédié au module n'a été identifié dans les fichiers inspectés.
  • Le cycle d'achat réel des packs depend probablement d'un autre module de paiement ; ici, le modèle expose les packs mais ne traite pas l'achat.
  • La création dynamique de ai_projection_credit_notifications dans le service devrait idealement être rapprochee des migrations SQL pour rendre les environnements plus prévisibles.