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 ; GRATUITest 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 :
nameunique ;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éponseDescription générale;statut;created_by;societe_idpour 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
editprésente ; - pas archivée ;
- statut
incomplèteouen 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_atreste nul.
Depot :
- statut
en cours; referenceobligatoire ;detail_demandeobligatoire ;- tous les documents obligatoires doivent être présents ou déjà existants ;
- toutes les questions obligatoires doivent avoir une réponse ;
submitted_atest 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_pathsousattachments/<fichier>; - calcule
mime_typeviamime_content_type(); - stocke
original_name,file_size,uploaded_at.
URL de lecture :
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éeverrouillé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()renseignearchived_atetarchived_by_membre_id;unarchive()remet ces champs àNULL;delete()renseignedeleted_atetdeleted_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 :
300secondes ; 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 :
Integration Notes¶
NoteModel appelle dispatchDeclarationNoteNotification() quand resource_type === 'dp'.
Le payload de note contient :
source_type:note_from_adminounote_from_societeselon 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()appelleensureLifecycleColumns()pour ajouter les colonnes archive/suppression ;DeclarationPrealableNotificationService::__construct()appelleensureStorageSchema()pour créerdp_notifications.
Impact :
- l'utilisateur SQL applicatif doit pouvoir
ALTER TABLEetCREATE 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¶
- Utiliser les statuts exacts avec accents. Une variante comme
incomplèteoutermineene correspond pas à l'enum. - Les admins ne voient que les demandes déposées (
submitted_at IS NOT NULL). Les brouillons restent côté société. - Une demande
terminée,non réalisable, archivée ou supprimée ne doit pas être modifiable côté société. - Le champ
accepted_cguest reçu par le contrôleur mais aucune colonne équivalente n'a été identifiée dans le schéma inspecté. - La création de
dp_notificationsest dans le service, pas dansdeclarations-prealables.sql. - La suppression de type peut être bloquée par
dp_instancesviaON DELETE RESTRICT. - 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¶
- Créer un type avec un document obligatoire et une question obligatoire.
- En société TPE ou plus, créer un brouillon : statut
incomplète,submitted_atnul. - Tenter le dépôt sans document obligatoire : refus attendu.
- Ajouter les pièces et réponses, déposer : statut
en cours,submitted_atrenseigné, notificationnew_request. - En admin, vérifier que la demande apparaît dans la liste.
- Changer le statut vers
déposée, puis vérifierreviewed_at,reviewed_by_membre_id,review_reasonet notificationstatus_changed. - Ajouter une note côté société et côté admin ; vérifier les sources
note_from_societeetnote_from_admin. - Lancer
php app/cron/dp_notifications_cron.phppour 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_cgusemble 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.