Aller au contenu

Module Déclarations préalables

Objectif

Le module Déclarations préalables gère des demandes administratives structurées par type. Chaque type définit :

  • les documents attendus ;
  • les questions à renseigner ;
  • les champs obligatoires ;
  • l'icône et le libellé affichés.

Une société crée une demande en brouillon ou la dépose pour examen. Les administrateurs suivent ensuite la demande, changent son statut, archivent/suppriment et reçoivent/envoient des notifications.

Carte technique

flowchart TD
    Router["app/core/Router.php"] --> Controller["DeclarationPrealableController"]
    Router --> TypeController["admin/DeclarationPrealableTypeController"]

    Controller --> Model["DeclarationPrealableModel"]
    TypeController --> TypeModel["DeclarationPrealableTypeModel"]

    Model --> Tables["dp_instances / dp_instance_*"]
    TypeModel --> TypeTables["dp_types / dp_type_*"]
    Model --> Notifications["DeclarationPrealableNotificationService"]
    NoteModel["NoteModel"] --> Notifications
    Notifications --> Mailer["MailerService"]
    Cron["app/cron/dp_notifications_cron.php"] --> Notifications

    View["declarations-prealables.php"] --> Details["declaration-prealable-details.php"]
    AdminView["admin/declaration-prealable-types.php"] --> TypeModal["ajouter-modifier-pour-declaration-prealable-type.php"]

Fichiers à connaître

Rôle Fichiers
Routes app/core/Router.php
Contrôleur demandes app/controllers/DeclarationPrealableController.php
Modèle demandes app/models/DeclarationPrealableModel.php
Contrôleur types admin app/controllers/admin/DeclarationPrealableTypeController.php
Modèle types admin app/models/admin/DeclarationPrealableTypeModel.php
Notifications app/services/DeclarationPrealableNotificationService.php, app/cron/dp_notifications_cron.php
Notes liées app/models/NoteModel.php
Vues app/views/declarations-prealables.php, app/views/partials/details/declaration-prealable-details.php
Admin types app/views/admin/declaration-prealable-types.php, app/views/partials/modals/ajouter-modifier-pour-declaration-prealable-type.php
SQL app/bd/declarations-prealables.sql

Routes demandes

Route Méthode Accès routeur Contrôleur Usage
declarations-prealables GET FEATURE_GERER_DECLARATION_PREALABLE index() Liste et page principale.
declaration-prealable/get POST FEATURE_GERER_DECLARATION_PREALABLE get() Détail complet d'une demande.
declaration-prealable/save POST FEATURE_GERER_DECLARATION_PREALABLE save() Brouillon ou dépôt.
declaration-prealable/change-status POST admin changeStatus() Changement de statut.
declaration-prealable/archive POST admin archive() Archivage logique.
declaration-prealable/unarchive POST admin unarchive() Désarchivage.
declaration-prealable/delete POST admin delete() Suppression logique.

Routes admin des types

Route Méthode Accès Contrôleur Usage
declaration-prealable-types GET admin index() Liste des types.
declaration-prealable-type/add POST admin add() Création d'un type.
declaration-prealable-type/update POST admin update() Modification d'un type.
declaration-prealable-type/delete POST admin delete() Suppression d'un type.

Droits et plans

Le routeur contrôle la feature FEATURE_GERER_DECLARATION_PREALABLE.

Le modèle refait un contrôle via checkFeatureAccess(), puis un contrôle de plan via checkRequestActionAccess() pour les actions de création/modification.

Plan minimal pour créer ou modifier une demande :

  • MINIMUM_REQUIRED_PLAN_NAME = TPE ;
  • admins : rang forcé à 999, donc bypass de plan ;
  • GRATUIT est insuffisant.

Permissions utilisées :

  • liste/détail : PermissionMiddleware::require('déclarations préalable', 'view_all') ;
  • création : déclarations préalable/create ;
  • édition : déclarations préalable/edit.

Les constantes de permissions contiennent le module déclarations préalable.

Schéma de données

dp_types

Types administrables :

  • name unique ;
  • icon ;
  • timestamps.

dp_type_documents

Documents attendus par type :

  • dp_type_id ;
  • label ;
  • required ;
  • sort_order.

Suppression en cascade quand le type est supprimé.

dp_type_questions

Questions attendues par type :

  • dp_type_id ;
  • label ;
  • required ;
  • sort_order.

Suppression en cascade quand le type est supprimé.

dp_instances

Demande concrète d'une société.

Champs principaux :

  • dp_type_id ;
  • societe_id ;
  • created_by_membre_id ;
  • reference ;
  • status ;
  • submitted_at ;
  • reviewed_at ;
  • reviewed_by_membre_id ;
  • review_reason ;
  • timestamps.

Statuts exacts dans l'enum SQL :

  • incomplète ;
  • en cours ;
  • déposée ;
  • non réalisable ;
  • terminée.

Colonnes de cycle de vie ajoutees au runtime par ensureLifecycleColumns() si absentes :

  • archived_at ;
  • archived_by_membre_id ;
  • deleted_at ;
  • deleted_by_membre_id.

dp_instance_documents

Documents d'une demande :

  • dp_instance_id ;
  • dp_type_document_id ;
  • label ;
  • required ;
  • file_path ;
  • original_name ;
  • mime_type ;
  • file_size ;
  • uploaded_at.

dp_instance_answers

Réponses d'une demande :

  • dp_instance_id ;
  • dp_type_question_id ;
  • label ;
  • answer.

Le détail général de la demande est stocke comme une réponse avec le libellé Description générale.

Flux : liste et visibilité

getPaginatedDeclarations() applique toujours deleted_at IS NULL.

En contexte admin :

  • seules les demandes déposées sont visibles (submitted_at IS NOT NULL) ;
  • filtre optionnel par societe_id.

En contexte société :

  • filtre obligatoire sur societe_id = active_societe_id ;
  • les brouillons de la société restent visibles.

Filtres supportés :

  • search : référence, nom du type, réponse Description générale ;
  • statut ;
  • created_by ;
  • societe_id pour admin ;
  • date_debut ;
  • date_fin ;
  • tri autorisé : id, reference, status, created_at.

Une demande est éditable côté société seulement si :

  • l'utilisateur n'est pas admin ;
  • permission edit présente ;
  • pas archivée ;
  • statut incomplète ou en cours.

Flux : brouillon et dépôt

save() recoit :

  • declaration_id ;
  • type_id ;
  • reference ;
  • detail_demande ;
  • accepted_cgu ;
  • save_mode ;
  • documents ;
  • answers ;
  • fichiers $_FILES.

save_mode = draft :

  • statut incomplète ;
  • documents/réponses obligatoires peuvent manquer ;
  • submitted_at reste nul.

Depot :

  • statut en cours ;
  • reference obligatoire ;
  • detail_demande obligatoire ;
  • tous les documents obligatoires doivent être présents ou déjà existants ;
  • toutes les questions obligatoires doivent avoir une réponse ;
  • submitted_at est posé à la première soumission.

Notification admin :

  • envoyée seulement si la demande n'est pas un brouillon ;
  • et si c'est une nouvelle demande déposée ou une demande qui n'avait pas encore submitted_at.

Flux : documents uploadés

Constantes :

  • module upload : dp ;
  • type de document : attachments ;
  • taille max : 5 Mo.

prepareInstanceDocument() :

  • conserve le fichier existant si aucun nouvel upload n'arrive ;
  • upload avec BaseModel::uploadFile($file, 'dp', 'attachments', 5242880, false) ;
  • stocke file_path sous attachments/<fichier> ;
  • calcule mime_type via mime_content_type() ;
  • stocke original_name, file_size, uploaded_at.

URL de lecture :

asset('uploads/dp/' . file_path)

Donc un fichier stocké en base comme attachments/x.pdf est servi via uploads/dp/attachments/x.pdf.

Flux : changement de statut

updateStatus() est réservé admin.

Statuts autorisés par le modèle :

  • en cours ;
  • incomplète ;
  • déposée ;
  • non réalisable ;
  • terminée.

Règles :

  • statut inconnu refuse ;
  • demande introuvable refusée ;
  • demande archivée refusée ;
  • demande déjà terminée verrouillée ;
  • si le statut ne change pas, retour success sans notification ;
  • sinon mise à jour de status, reviewed_at, reviewed_by_membre_id, review_reason, updated_at ;
  • notification de changement de statut ensuite.

Archivage et suppression

Actions admin :

  • archive() renseigne archived_at et archived_by_membre_id ;
  • unarchive() remet ces champs à NULL ;
  • delete() renseigne deleted_at et deleted_by_membre_id.

La suppression est logique. Les listes excluent les lignes avec deleted_at.

Administration des types

DeclarationPrealableTypeModel::saveType() crée ou modifie un type et ses enfants dans une transaction.

Règles utiles :

  • nom obligatoire ;
  • documents et questions sont remplaces par les valeurs postees ;
  • chaque enfant porte label, required, sort_order ;
  • la suppression d'un type supprime d'abord documents/questions puis dp_types.

Attention : dp_instances.dp_type_id à une contrainte ON DELETE RESTRICT. Supprimer un type utilise par une demande peut donc échouer selon l'état des données.

Notifications

DeclarationPrealableNotificationService crée dynamiquement la table dp_notifications :

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

Retries :

  • MAX_RETRIES = 3 ;
  • délai entre retries : 300 secondes ;
  • processPendingNotifications($limit) borne la limite entre 1 et 100.

Sources vérifiées :

  • new_request : nouvelle demande déposée, notification aux admins ;
  • status_changed : changement de statut, notification à la société ;
  • note_from_societe : note ajoutée par la société, notification aux admins ;
  • note_from_admin : note ajoutée par un admin, notification à la société.

queueNotification() envoie les sources new_request et note_from_societe vers queueAdminNotifications(), donc potentiellement plusieurs lignes de notification.

Le modèle tente l'envoi immédiat après mise en file via sendNotificationById(). Le cron sert de rattrapage pour les notifications pending.

Cron :

php app/cron/dp_notifications_cron.php

Integration Notes

NoteModel appelle dispatchDeclarationNoteNotification() quand resource_type === 'dp'.

Le payload de note contient :

  • source_type : note_from_admin ou note_from_societe selon la session ;
  • dp_instance_id ;
  • societe_id ;
  • reference ;
  • type_name ;
  • societe_name ;
  • detail_demande ;
  • nom de la personne ayant ajouté la note ;
  • note_content ;
  • redirect_path.

Particularites runtime

Deux schémas sont créés/alteres au runtime :

  • DeclarationPrealableModel::__construct() appelle ensureLifecycleColumns() pour ajouter les colonnes archive/suppression ;
  • DeclarationPrealableNotificationService::__construct() appelle ensureStorageSchema() pour créer dp_notifications.

Impact :

  • l'utilisateur SQL applicatif doit pouvoir ALTER TABLE et CREATE TABLE ;
  • un environnement avec droits limités peut échouer tardivement ;
  • ces changements devraient idéalement être appliqués par migration avant usage.

Points de vigilance

  1. Utiliser les statuts exacts avec accents. Une variante comme incomplète ou terminee ne correspond pas à l'enum.
  2. Les admins ne voient que les demandes déposées (submitted_at IS NOT NULL). Les brouillons restent côté société.
  3. Une demande terminée, non réalisable, archivée ou supprimée ne doit pas être modifiable côté société.
  4. Le champ accepted_cgu est reçu par le contrôleur mais aucune colonne équivalente n'a été identifiée dans le schéma inspecté.
  5. La création de dp_notifications est dans le service, pas dans declarations-prealables.sql.
  6. La suppression de type peut être bloquée par dp_instances via ON DELETE RESTRICT.
  7. Les documents obligatoires sont vérifiés deux fois dans save() : avant préparation, puis après préparation. Garder ce double verrou si la logique upload évolue.

Vérification conseillée

  1. Créer un type avec un document obligatoire et une question obligatoire.
  2. En société TPE ou plus, créer un brouillon : statut incomplète, submitted_at nul.
  3. Tenter le dépôt sans document obligatoire : refus attendu.
  4. Ajouter les pièces et réponses, déposer : statut en cours, submitted_at renseigné, notification new_request.
  5. En admin, vérifier que la demande apparaît dans la liste.
  6. Changer le statut vers déposée, puis vérifier reviewed_at, reviewed_by_membre_id, review_reason et notification status_changed.
  7. Ajouter une note côté société et côté admin ; vérifier les sources note_from_societe et note_from_admin.
  8. Lancer php app/cron/dp_notifications_cron.php pour traiter les notifications restantes.

Questions ouvertes

  • Aucun test automatisé dédié aux Déclarations préalables n'a été trouvé dans les fichiers inspectés.
  • accepted_cgu semble capturé au POST mais n'est pas persisté dans les tables inspectées.
  • Les migrations runtime devraient être clarifiées avant durcissement des droits SQL de production.