Module Missions¶
Objectif¶
Le module Missions gère une place de marche interne Solutravo : une société publie une mission, d'autres sociétés la consultent, candidatent, echangent et peuvent être acceptées. Le module couvre aussi la revue administrateur, les filtres, les pièces jointes, la galerie, les notifications email et les règles d'accès selon le plan d'abonnement.
Ce module ne doit pas être traité comme une simple liste CRUD. Il porte des règles produit sensibles : visibilité publique, validation admin, quotas de candidature, fermeture automatique après acceptation et isolation entre sociétés.
Architecture fonctionnelle¶
flowchart LR
Router[Router.php] --> Controller[MissionController]
Controller --> Model[MissionModel]
Model --> AdminNotif[MissionAdminNotificationService]
Model --> AudienceNotif[MissionAudienceNotificationService]
Model --> Messaging[MessagingService / MessagingModel]
Model --> MailQueue[Email queue / Brevo templates]
Model --> DB[(MySQL)]
Controller --> Views[missions.php + partials]
Views --> JS[public/assets/js/missions/*]
Périmètre documenté¶
Cette page documente les fichiers listés dans les points d'entrée ci-dessous. Avant une correction, ouvrir ces fichiers dans la branche de travail concernée et vérifier l'historique git du module si le comportement observé ne correspond pas à la documentation.
Points d'entrée¶
Backend¶
app/controllers/MissionController.php: endpoints HTTP, normalisation des filtres, réponses JSON, chargement de la page.app/models/MissionModel.php: règles métier, requêtes, permissions, transitions de statut, fichiers, candidatures, notifications.app/services/MissionAdminNotificationService.php: alertes administrateur quand une mission attend validation.app/services/MissionAudienceNotificationService.php: briefs email envoyés aux sociétés eligibles quand une mission publiée correspond à leur activite.app/services/MessagingService.phpetapp/models/MessagingModel.php: création de conversation liée à une candidature.
Front¶
app/views/missions.phpapp/views/partials/missions/filter-form.phpapp/views/partials/missions/list-section.phpapp/views/partials/missions/mission-card.phpapp/views/partials/missions/tab-navigation.phpapp/views/partials/modals/mission-application-modal.phpapp/views/partials/modals/mission-applications-drawer.phpapp/views/partials/modals/mission-details-modal.phpapp/views/partials/modals/mission-edit-modal.phpapp/views/partials/modals/mission-publish-modal.phpapp/views/partials/modals/mission-candidates-modal.phpapp/views/partials/modals/mission-gallery-viewer-modal.phpapp/views/partials/modals/mission-share-email-modal.phpapp/views/partials/modals/mission-application-details-modal.phpapp/views/partials/modals/mission-confirm-action-modal.phpapp/views/partials/modals/mission-personal-list-modal.phpapp/views/partials/modals/mission-review-list-modal.phppublic/assets/js/missions/app.jspublic/assets/js/missions/actions.jspublic/assets/js/missions/core.jspublic/assets/js/missions/pickers.jspublic/assets/js/missions/renderers.jspublic/assets/css/missions.css
Routes¶
Les routes sont declarees dans app/core/Router.php.
Pages¶
missions: redirige versmissions/allen conservant la query string.missions/all: catalogue global des missions visibles.missions/personal: missions personnelles de la société courante.missions/review: file de revue administrateur, uniquement pour les administrateurs.
Actions mission¶
mission/add: création.mission/update: modification.mission/delete: suppression définitive, réservée aux administrateurs selon le modèle.mission/reopen: réouverture d'une mission clôturée.mission/archive: archivage.mission/unarchive: désarchivage.mission/approve: validation admin et publication.mission/view: enregistrement d'une vue.mission/share-email: partage par email.mission/activities/search: recherche d'activités.mission/companies/search: recherche de sociétés pour filtre/admin.
Actions candidature¶
mission/apply: candidature à une mission.mission/application/update: modification de sa propre candidature.mission/application/delete: suppression de sa propre candidature.mission/application/status: changement de statut par le propriétaire de mission.mission/applications: liste des candidatures recues.mission/application: détail d'une candidature reçue.
Permissions, features et plans¶
Le module combine permissions applicatives et features de plan.
Permissions appelées par le contrôleur ou le modèle :
missions:view_allmissions:createmissions:editmissions:apply_to_missionmissions:view_applications
Features de plan appelées par le modèle :
FEATURE_CONSULTER_MISSIONFEATURE_POSTULER_MISSION
Plans utilisés par les règles de candidature :
GRATUITTPEPMEENTREPRISE
Regle importante : le plan gratuit est limite à une candidature par mois pour les non-admins. Les plans superieurs sont ordonnes par rang pour vérifier si une société peut candidater à une mission exigeant un plan minimum.
Statuts mission¶
Statuts techniques :
draft: brouillon.pending_review: en attente de validation admin.published: visible dans le catalogue.closed: clôturée, notamment après acceptation d'une candidature.archived: archivée.
Transitions principales :
- création par admin : publication directe en
published. - création par non-admin : passage en
pending_review. - modification par admin avec demande de publication :
published. - modification par non-admin d'une mission ouverte : retour en
pending_review. - validation admin :
publishedavecpublished_at,reviewed_by,reviewed_at. - acceptation d'une candidature : mission en
closed. - désarchivage admin :
published. - désarchivage non-admin :
pending_review.
La logique de visibilité dépend du scope :
all: missions publiees et clôturées pour les utilisateurs standards ; l'admin voit aussi des états internes.personal: toutes les missions de la société courante, y compris brouillon, attente, publiee, clôturée, archivée.review: missionspending_review, réservé admin.
Méthodes de transition¶
Les transitions sont centralisees dans MissionModel :
resolveMissionStatusContextOnCreate: admin verspublished, non-admin verspending_review.resolveMissionStatusContextOnUpdate: admin peut publier ; non-admin renvoie en revue sauf mission déjàclosed.resolveMissionStatusContextOnUnarchive: admin republie, non-admin renvoie en revue.approve: publication admin depuispending_review.archive/unarchive/reopen: transitions explicites appelées par le contrôleur.
Garde-fou important : un changement annonceur sur une mission ouverte retire la mission du flux public. C'est une règle produit de moderation, pas un détail d'interface.
Donnees¶
Tables directement manipulées par le module :
missions: mission principale.mission_activities: relation mission / activités.mission_departements: relation mission / départements.mission_files: images et pièces jointes.mission_applications: candidatures.mission_views: vues journalières par membre/société.mission_brief_email_recipients: réservation/idempotence des briefs email.societes,membres,plans,activites,departements: tables référencées.
Scripts SQL actuellement présents :
app/bd/missions-departements.sql: créemission_departements, rendcitynullable, retirepostal_code, ajouteis_nationwide.app/bd/missions-nationwide.sql: ajouteis_nationwide.app/bd/missions-notifications.sql: créemission_brief_email_recipients.app/bd/missions-original-societe.sql: ajouteoriginal_societe_idet backfill depuissociete_id.
Point de reprise important : la fiche historique mentionnait app/bd/missions.sql, mais ce fichier n'est pas présent dans le checkout actuel. Avant d'installer le module sur une nouvelle base, retrouver la migration initiale ou reconstruire explicitement le schéma de base (missions, mission_activities, mission_files, mission_applications, mission_views) depuis la base de référence.
État vérifié des migrations¶
Recherche locale effectuee dans app/bd :
- aucune migration initiale
CREATE TABLE missionstrouvée ; - aucune migration initiale
CREATE TABLE mission_applicationstrouvée ; - aucune migration initiale
CREATE TABLE mission_filestrouvée ; - aucune migration initiale
CREATE TABLE mission_viewstrouvée ; - aucune migration initiale
CREATE TABLE mission_activitiestrouvée ; - migration trouvée pour
mission_departements; - migration trouvée pour
mission_brief_email_recipients.
Conséquence : le code actuel dépend de tables qui existent probablement déjà dans les bases de travail, mais le repository ne documente pas totalement une installation neuve. C'est un risque majeur de reprise.
Colonnes attendues par missions¶
Le modèle lit ou écrit notamment :
idsociete_id: propriétaire courant de la mission.original_societe_id: société d'origine, ajoutée parmissions-original-societe.sql.created_by: membre createur.titledescriptioncityis_nationwidebudget_amountis_budget_on_quotebudget_scopeis_budget_negotiableexecution_deadlineminimum_candidate_plan_idis_urgentstatuspublished_atreviewed_byreviewed_atclosed_atcreated_atupdated_at
Ces colonnes doivent être confirmees dans la base de référence avant tout déploiement. La migration initiale manquante doit être reconstituee à partir de la base et du code, pas devinee.
Tables de liaison et d'activite¶
mission_activities
- Relation entre une mission et une activite.
- Utilisee pour les filtres, la recherche d'activités et les briefs audience.
- Le modèle supprime puis réinsère les activités lors d'une synchronisation.
mission_departements
- Relation entre une mission et un departement.
- Cle primaire composite
mission_id,departement_id. - Suppression en cascade quand la mission est supprimée.
- Si
is_nationwideest vrai, le modèle supprime les départements et n'en réinsère pas.
mission_files
- Stocke
file_type,file_path,original_name,mime_type,file_size,sort_order. - Les chemins physiques sont reconstruits depuis
public/+file_path. - Les suppressions partielles passent par
removed_file_ids.
mission_views
- Enregistre
mission_id,viewer_societe_id,viewer_membre_id,viewed_at. - Le modèle évite de compter plusieurs vues le même jour pour un même membre.
mission_applications
- Stocke la candidature : mission, société candidate, membre candidat, message, statut.
- Le modèle utilise au moins
mission_id,candidate_societe_id,candidate_membre_id,message,status,created_at. - Les statuts gérés par le code sont
new,viewed,accepted,rejected.
mission_brief_email_recipients
- Table d'idempotence des briefs audience.
- Cle unique
mission_id,societe_id. - Colonnes :
email,template_brevo_id,email_queue_id,status,skip_reason,created_at.
Localisation et audience¶
La localisation repose sur :
cityfacultatif ;mission_departementspour les departements cibles ;is_nationwidepour les missions "toute la France".
Quand is_nationwide est actif, les départements ne doivent pas limiter la visibilité. Quand il est inactif, les départements deviennent structurants pour les filtres, les emails de brief et la recherche.
Budget et délais¶
Scopes budgetaires :
supply_and_installation: fourniture + pose.installation_only: pose uniquement.
Delais techniques :
under_10_daysbetween_10_days_and_1_monthbetween_1_and_3_monthsover_3_months
Regle importante : si is_budget_on_quote est actif, le montant fixe, le scope et la negociabilite sont neutralises. Si la mission n'est pas "sur devis", le montant et le scope deviennent obligatoires.
Normalisation budget¶
normalizeMissionBudgetContext applique exactement cette logique :
- si
is_budget_on_quoteest vrai,budget_amountdevientnull,is_budget_on_quotevaut1,budget_scopedevientnulletis_budget_negotiablevaut0; - si
is_budget_on_quoteest faux et que le montant est absent, le modèle renvoie une erreur car le forfait est obligatoire sauf attente d'un devis ; - si le montant existe mais que le scope est invalide ou absent, le modèle renvoie une erreur demandant de preciser fourniture + pose ou pose uniquement.
Ne pas valider uniquement côté JS : le modèle porte déjà la règle et doit rester la source de vérité.
Fichiers et galerie¶
Les uploads mission utilisent :
- module d'upload :
missions; - taille maximum :
5 242 880octets, soit 5 Mio ; - stockage logique :
uploads/missions/...; - type
imagepour les mimesimage/*, sinonattachment.
Les fichiers sont référencés en base dans mission_files. La suppression définitive d'une mission récupère les chemins puis supprime les fichiers physiques. Les suppressions partielles de fichiers passent par removed_file_ids.
Avant de modifier ce flux, tester :
- upload multiple ;
- retrait d'un fichier existant ;
- suppression définitive de mission ;
- affichage galerie ;
- pièce jointe non image ;
- fichier trop lourd.
Cycle de vie des fichiers¶
syncMissionUploads fait deux choses :
- supprimer les fichiers demandes via
removed_file_ids; - ajouter les nouveaux fichiers via
storeMissionUploads.
storeMissionUploads attend les fichiers sous la clé files. Une intégration front qui envoie une autre clé peut donner l'impression que l'upload fonctionne côté formulaire mais ne rien enregistrer en base.
uploadSingleMissionFile classe les fichiers en :
imagesi le mime commence parimage/;attachmentsinon.
Le chemin stocke en base commence par uploads/missions/. Le chemin disque de suppression est reconstruit avec dirname(__DIR__, 2) . '/public/'.
Flux : création et publication¶
Création :
- Le contrôleur lit les champs
societe_id,title,description,city,is_nationwide,department_ids, budget, délai, plan minimum, urgence, statut et activités. - Le modèle valide les features, permissions, budget, departements, activités et société propriétaire.
- Les administrateurs peuvent choisir la société propriétaire.
- Les non-admins publient pour leur société active.
- Le statut final depend du rôle : admin publie directement, non-admin passe en revue.
- Les activités, departements et fichiers sont synchronises.
- Si la mission passe en attente de validation, une notification admin est tentee hors transaction critique.
Piege a éviter : ne pas rendre une mission non revue visible dans all. Une modification par annonceur sur une mission ouverte doit la retirer du flux public jusqu'a validation.
Champs lus par le contrôleur¶
MissionController::add et MissionController::update collectent :
societe_idtitledescriptioncityis_nationwidedepartment_idsbudget_amountis_budget_on_quotebudget_scopeis_budget_negotiableexecution_deadlineminimum_candidate_plan_idis_urgentstatusactivitiesremoved_file_idsen édition.
Une évolution de formulaire doit donc être raccordee a ces noms exacts ou au mapping du contrôleur.
Societe propriétaire¶
La resolution de société propriétaire est volontairement differente selon le rôle :
- admin : peut choisir
societe_id, avec validation que la société existe ; - non-admin : force la société active ;
- édition par non-admin : conserve le propriétaire courant.
original_societe_id conserve l'origine historique. Ne pas le modifier pour transferer une mission : utiliser societe_id.
Flux : revue administrateur¶
Une mission en pending_review est visible dans le scope review. L'admin peut la valider via mission/approve.
MissionAdminNotificationService gère :
- notification immédiate de mission en attente ;
- rappel hebdomadaire des missions en attente ;
- limitation de l'aperçu email aux cinq dernieres missions ;
- destinataires : membres actifs de type
admin, non collaborateurs, avec email valide.
La notification ne doit jamais bloquer la sauvegarde d'une mission. Le modèle loggue les échecs et laisse la mission comme source de vérité.
Notifications admin¶
MissionAdminNotificationService :
- cherche les membres
type = admin; - exige
statut = actif; - exclut
COALESCE(is_collaborator, 0) = 0; - dedoublonne les emails ;
- envoie au premier admin en destinataire principal et les autres en copie ;
- utilise un lien de revue
/missions/all?missions_modal=review.
Le service n'utilise pas la table mission_brief_email_recipients, réservée aux briefs audience.
Flux : consultation, filtres et vues¶
Les filtres supportes côté contrôleur incluent :
- recherche texte ;
- dates de publication ;
- urgence ;
- missions personnelles ;
- activités ;
- departements ;
- sociétés, pour admin uniquement.
registerMissionView enregistre une vue dans mission_views si le membre n'a pas déjà vu la mission le même jour. Cela évite de gonfler artificiellement les compteurs.
Scopes et filtres¶
Le contrôleur accepte seulement :
allpersonalreview, pour admin.
Filtres normalises :
searchdate_publication_debutdate_publication_finis_urgentmine_onlyactivity_idsdepartment_idssociete_ids, admin uniquement.
Le contrôleur force actuellement l'appel principal à getPaginatedMissions(..., 'all') pour la page, puis charge les listes modales personal et review à part. Si un futur développeur modifie les onglets pour charger chaque scope directement, il doit vérifier ce comportement et les compteurs.
Flux : candidature¶
Le flux candidature passe par mission/apply.
Règles à respecter :
- permission
missions:apply_to_missionobligatoire ; - feature
FEATURE_POSTULER_MISSIONobligatoire ; - la société active doit être valide ;
- impossible de candidater à sa propre mission ;
- impossible de candidater deux fois a la même mission ;
- impossible de candidater si le plan courant est inferieur au plan minimum de la mission ;
- le plan gratuit non-admin est limite à une candidature par mois ;
- une candidature crée une conversation mission, mais l'échec de messagerie ne doit pas annuler la candidature.
Statuts candidature :
newviewedacceptedrejected
L'acceptation est transactionnelle : le statut de la candidature passe a accepted, la mission est fermee, puis une notification d'acceptation est planifiee. Le modèle protège le cas ou une autre candidature serait déjà acceptée.
Politique de candidature¶
getApplicationPolicyContext calcule :
- plan courant ;
- si le plan est gratuit ;
- limite mensuelle ;
- nombre utilise ce mois ;
- reste disponible ;
- feature d'upgrade
FEATURE_POSTULER_MISSION.
Le quota gratuit est calcule sur mission_applications avec candidate_societe_id = activeSocieteId et created_at >= premier jour du mois courant. Le code ne filtre pas explicitement les candidatures supprimées dans ce compteur ; vérifier le comportement attendu avant de changer la suppression de candidature.
Acceptation et concurrence¶
updateApplicationStatus ouvre une transaction, relit le contexte candidature avec verrou FOR UPDATE, puis appelle getApplicationProcessingGuard.
Garde-fous :
- impossible de traiter manuellement
acceptedourejectedsi la mission est déjàclosed; - accepter une candidature déjà acceptée est idempotent ;
- accepter une autre candidature est refuse si une candidature acceptée existe déjà ;
closeMissionAfterAcceptedApplicationmetmissions.status = 'closed'etclosed_at = NOW().
La notification d'acceptation est envoyée après commit. Si elle échoue, la candidature acceptée et la mission clôturée restent la vérité.
Flux : gestion des candidatures recues¶
Le propriétaire d'une mission, ou un admin, peut lister et traiter les candidatures. L'accès passe par missions:view_applications et par userCanManageMission.
Règles sensibles :
- une société ne doit jamais gérer les candidatures d'une mission qui ne lui appartient pas ;
- une mission
closedne doit plus permettre acceptation/refus manuel ; - une seule candidature acceptée par mission ;
- les conversations liées aux candidatures doivent rester accessibles aux participants autorisés seulement.
Messagerie¶
Après création de candidature, createMissionApplicationConversation tente MessagingService::createForMissionApplication.
Le commentaire du code est important : la candidature reste la source de vérité et la messagerie ne doit pas bloquer le dépôt. En cas d'échec, le modèle loggue l'erreur. Une reprise doit donc prévoir un outil de diagnostic ou de recréation de conversation si une candidature existe sans conversation.
app/bd/messaging.sql contient des vues/requêtes liées à mission_applications. Le module Missions et la Messagerie sont donc couplés par la structure de candidature.
Flux : partage email¶
mission/share-email partage une mission par email.
Protections existantes :
- permission
missions:view_all; - email destinataire obligatoire ;
- rate limit session : 5 partages maximum par fenêtre de 15 minutes ;
- template Brevo source
mission_share_email.
Les URLs absolues sont construites via APP_URL, puis APP_BASE_URL, puis l'hote HTTP courant. Ne pas hardcoder de domaine dans ce module.
Rate limit partage¶
allowMissionShareEmailRequest stocke les timestamps en session sous mission_share_email_timestamps.
- fenêtre : 900 secondes ;
- maximum : 5 tentatives ;
- le nettoyage garde seulement les timestamps encore dans la fenêtre.
Ce rate limit est par session PHP, pas global. Il limite les abus simples mais ne remplace pas une protection serveur globale si le partage devient critique.
Flux : briefs audience¶
MissionAudienceNotificationService envoie des briefs aux sociétés eligibles quand une mission publiée correspond à leurs activités.
Parametres importants :
- source email :
mission_brief_matched_activity; - variable d'activation :
MISSION_BRIEF_EMAILS_ENABLED; - batch : 50 destinataires ;
- délai entre batches : 300 secondes ;
- limite quotidienne : 3 briefs par société ;
- table d'idempotence :
mission_brief_email_recipients.
La table d'idempotence empêche de renvoyer le même brief a la même société pour une même mission. Les statuts possibles dans cette table sont queued, skipped et failed.
Selection et idempotence audience¶
MissionAudienceNotificationService est volontairement opt-in :
- si
MISSION_BRIEF_EMAILS_ENABLEDest absent ou invalide, aucun envoi ; reserveRecipientfait unINSERT IGNOREdansmission_brief_email_recipients;- si la reservation existe déjà, le destinataire est ignore ;
- si la limite quotidienne est atteinte, la ligne est réservée avec
status = skippedetskip_reason = daily_limit; - si la mise en file email échoue, la ligne passe en
failed.
La limite quotidienne compte les lignes queued créées depuis UTC_DATE(). Elle ne compte pas les failed ni les skipped.
Integrations internes¶
- Messagerie : conversation créée pour une candidature via
MessagingService::createForMissionApplication. - Emails :
MailerService, file email et templates Brevo. - Plans/features :
getCurrentPlanName,hasFeatureAccess, constantes feature. - Permissions :
PermissionMiddleware. - Societes et membres : ownership, candidature, destinataires.
- Activités et départements : matching, filtres, audience.
Risques et pieges¶
- Ne pas confondre
societe_idetoriginal_societe_id:societe_idrepresente le propriétaire courant,original_societe_idconserve l'origine historique. - Ne pas exposer les missions en attente dans le flux public.
- Ne pas permettre à une société de candidater à sa propre mission.
- Ne pas autoriser plusieurs candidatures acceptées pour une même mission.
- Ne pas casser la limite de candidature du plan gratuit.
- Ne pas bloquer la création/modification d'une mission si l'email admin ou audience échoue.
- Ne pas supprimer physiquement les fichiers sans nettoyer
mission_files, et inversement. - Ne pas reconstruire le schéma depuis les seules migrations partielles : la migration initiale manque dans le checkout actuel.
- Ne pas considerer le rate limit email comme global : il est base session.
- Ne pas rendre bloquants les emails ou la messagerie si le code les traite comme secondaires.
- Ne pas modifier les transitions sans vérifier les statuts visibles par scope.
- Ne pas oublier que les fichiers physiques peuvent rester sur disque si une suppression base échoue ou inversement.
Tests recommandés avant livraison¶
- Création mission admin : publication directe.
- Création mission non-admin :
pending_review. - Modification non-admin d'une mission publiée : retour en revue.
- Validation admin : publication, dates et reviewer renseignés.
- Filtres par activité, département, urgence, dates et société admin.
- Mission nationale avec
is_nationwide. - Candidature acceptée : mission fermée.
- Deux candidatures concurrentes : une seule acceptée.
- Candidature plan gratuit : quota mensuel appliqué.
- Plan minimum requis : blocage si plan insuffisant.
- Candidature à sa propre mission : refusée.
- Upload image et pièce jointe.
- Suppression définitive admin avec fichiers associés.
- Partage email : rate limit session.
- Brief audience : idempotence par mission/société.
Commandes utiles¶
Il n'y a pas encore de test automatisé dédié au module Missions dans le checkout actuel. Pour une reprise serieuse, ajouter au minimum des tests PHP de modèle sur :
- transitions de statut ;
- candidature et fermeture automatique ;
- quota plan gratuit ;
- filtrage multi-société ;
- idempotence email audience.
Checklist de reprise¶
- Lire
MissionController.phpetMissionModel.phpensemble. - Vérifier la présence du schéma initial en base avant de lancer les migrations partielles.
- Tester avec un admin, une société annonceuse et une société candidate.
- Tester avec au moins deux sociétés pour détecter les fuites de données.
- Vérifier les constantes de feature et les permissions en base.
- Vérifier les templates Brevo attendus pour
mission_application_created,mission_application_accepted,mission_share_email,mission_brief_matched_activity. - Vérifier que
MISSION_BRIEF_EMAILS_ENABLEDest volontairement activé seulement dans les environnements où l'envoi est souhaité.
Questions ouvertes¶
- Où se trouve la migration initiale du module Missions pour une installation neuve ?
- Le statut
draftest-il encore créé depuis l'interface ou seulement conservé pour compatibilité ? - Une mission archivée doit-elle rester visible aux candidats ayant déjà postule ?
- Le quota gratuit doit-il compter les candidatures supprimées ou seulement les candidatures actives ?
- La fermeture automatique après acceptation doit-elle notifier les autres candidats non retenus ?