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_IAet les permissionsprojection 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() :
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_swapest normalise versimage_merge;- les anciens champs upload
facade_imageetdoor_imagesont encore acceptes comme fallback pourprimary_imageetsecondary_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 :
- Vérifier l'accès Projection IA.
- Normaliser
mode. - Construire les fichiers uploadés :
primary_imageou fallbackfacade_image;secondary_imageou fallbackdoor_image.- Débiter la société via
AiProjectionCreditModel::debitCurrentSocieteForGeneration($mode). - Si le débit échoue, retourner
success=falseavec le solde etcost_per_generation. - Appeler
AiProjectionService::generate(). - Enregistrer l'historique via
AiProjectionLogModel::recordGeneration(). - Retourner le resultat IA et le nouveau solde.
- 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()retournecredit_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_endnon 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_endou 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_societiesest 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_etsource_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_idselon le contexte ; - seules les lignes non expirees avec
result_image_pathnon 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 lignepending;sendNotificationById()passe la ligne enprocessing, 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éeversprojection iasi nécessaire ; - créé/met à jour la feature id
43nommeeProjection IA; - lie la feature aux plans
17,18,19,20; - renomme
door_projection_usage_logsversai_projection_usage_logssi l'ancienne table existe et pas la nouvelle ; - convertit les anciens modes vides ou
door_swapenimage_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_imageetsecondary_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¶
- 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.
recordGeneration()retournefalsesans bloquer la réponse si l'historique ne peut pas être stocke. Une generation peut donc reussir sans apparaitre dans l'historique.- Les images sources et resultats sont stockes temporairement 7 jours. Ne pas allonger la retention sans revoir volume disque, données personnelles et purge.
- Le routage Projection IA est dupliqué dans
Router.php. Nettoyer ce doublon avant une refonte de routes reduirait le risque d'ecart. - Le client OpenAI utilise aussi
OPENAI_DOCUMENT_EXTRACTION_TIMEOUT. Modifier ce timeout impacte potentiellement d'autres usages du client catalogue. - La table
ai_projection_credit_notificationsest créée par le service PHP, pas parprojection-ia.sql. Sur un environnement strict, vérifier que l'utilisateur SQL applicatif a le droitCREATE TABLE. - Les variables legacy
OPENAI_DOOR_PROJECTION_MODEL,DOOR_PROJECTION_MAX_IMAGE_SIZE_MB,DOOR_PROJECTION_MAX_IMAGE_DIMENSIONsont encore lues comme fallback. Les supprimer demande une migration de configuration.
Vérification conseillée¶
- Lancer
php -l app/cron/ai_projection_subscription_credits_cron.php. - Vérifier
.env:OPENAI_API_KEY,OPENAI_AI_PROJECTION_MODEL, limites image. - En compte non admin avec crédits, générer en
single_editpuis vérifier : - solde decremente ;
- ligne
ai_projection_credit_historysourcegeneration; - ligne
ai_projection_usage_logs; - fichiers dans
public/uploads/ai_projection/history/<societe_id>/. - Simuler une erreur OpenAI après débit et vérifier le remboursement
generation_refund. - Tester
image_mergeavec deux images. - Tester un solde insuffisant : pas d'appel IA attendu.
- En admin, charger
settings, modifier crédits par plan et packs. - 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_notificationsdans le service devrait idealement être rapprochee des migrations SQL pour rendre les environnements plus prévisibles.