Aller au contenu

Module Chantiers

Objectif

Le module Chantiers pilote le cycle opérationnel d'un chantier Solutravo : création depuis une opportunite ou un document commercial, suivi kanban, lots et tâches, planning, achats, accès collaborateurs, sous-traitance, documents, reception/PV, signature et suivi financier.

La reprise du module doit se faire comme un ensemble cohérent. Les écrans "Chantiers", "PV de fin de chantier", "Finances des chantiers" et "Sous-traitants des chantiers" partagent des données et des invariants métier. Une modification locale sur le PV, les achats ou la finance peut casser un flux voisin.

Architecture fonctionnelle

flowchart LR
  Router[Router.php] --> Management[ChantierManagementController]
  Router --> PV[ChantierController]
  Router --> Finance[ChantierFinanceController]
  Router --> Subcontractor[ChantierSubcontractorController]

  Management --> ManagementModel[ChantierManagementModel]
  PV --> PVModel[ChantierModel]
  Finance --> FinanceModel[ChantierFinanceModel]
  Subcontractor --> SubcontractorModel[ChantierSubcontractorModel]

  ManagementModel --> DB[(MySQL)]
  PVModel --> DB
  FinanceModel --> DB
  SubcontractorModel --> DB

  Management --> Views[Views chantier]
  PV --> Signature[Pages PV/signature]
  Finance --> FinanceView[Vue finance]
  Subcontractor --> SubcontractorView[Vue sous-traitants]

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

Contrôleurs

  • app/controllers/ChantierManagementController.php : tableau de bord principal, liste, kanban, planning, documents, achats, accès collaborateurs, rattachements devis/factures.
  • app/controllers/ChantierController.php : flux PV de chantier, signature présentielle ou distante, déclaration de paiement liée au PV, génération PDF.
  • app/controllers/ChantierFinanceController.php : revenus, achats affectés, catégories de dépense, marges.
  • app/controllers/ChantierSubcontractorController.php : sous-traitants, affectations, invitations, conversations.

Modèles

  • app/models/ChantierManagementModel.php : modèle central du module opérationnel.
  • app/models/ChantierModel.php : modèle du PV, signature et paiement declare.
  • app/models/ChantierFinanceModel.php : modèle des données financieres chantier.
  • app/models/ChantierSubcontractorModel.php : modèle sous-traitants, invitations et affectations.

Vues et scripts front

  • app/views/chantier-management.php
  • app/views/chantiers.php
  • app/views/chantier-finance.php
  • app/views/chantier-subcontractors.php
  • app/views/pv-chantier-signature.php
  • app/views/pv-chantier-client-signature.php
  • public/assets/js/chantier-management.js
  • public/assets/js/chantiers.js
  • public/assets/js/chantier-finance.js
  • public/assets/js/chantier-subcontractors.js

Routes principales

Les routes sont declarees dans app/core/Router.php.

Pages

  • chantiers : page de gestion principale.
  • chantiers/vue-globale : vue globale.
  • chantiers/liste : liste.
  • chantiers/partages : partages/accès.
  • chantiers/receptions : receptions et PV.
  • chantiers/kanban : vue kanban.
  • chantiers/planning : planning.
  • chantiers/sous-traitants : sous-traitants.
  • pv-chantiers : espace PV de fin de chantier.

Actions chantier-management

  • Lecture et sauvegarde : get, save, archive, archiveMany, access, saveAccess, updateStatus.
  • Kanban : moveToColumn, saveColumn, deleteColumn, deleteColumns, reorderColumns.
  • Lots et tâches : saveLot, deleteLot, saveTask, updateTaskStatus, deleteTask.
  • Planning : planning, savePlanningEvent, deletePlanningEvent, markPlanningEventSeen.
  • Cartographie : mapboxSuggest, mapboxRetrieve, mapboxRoute.
  • Documents : saveDocument, deleteDocument.
  • Reception : createReception.
  • Documents commerciaux : linkDevis, unlinkDevis, linkInvoice.
  • Achats : assignPurchase, createPurchase, unassignPurchase.

Actions chantier

  • CRUD et contexte formulaire : index, get, formContext, clientDocuments, sourceDocument, save, delete.
  • Signature : signaturePage, signInPerson, sendSignatureRequest, remoteSignaturePage, signRemoteClient.
  • Paiement declare PV : recordPayment.
  • PDF : pdf.

Actions finance

  • index, saveRevenue, deleteRevenue, assignPurchase, unassignPurchase, saveCategory, archiveCategory.

Actions sous-traitants

  • index, saveSubcontractor, getSubcontractor, archiveSubcontractor, saveAssignment, createAssignmentWithSubcontractor, searchCompanies, deleteAssignment, sendInvitation, startConversation, acceptInvitation, showInvitation.

Permissions et accès

Les permissions ne sont pas seulement decoratives : elles conditionnent l'affichage, les données exposees et les actions disponibles.

  • Module PV de fin de chantier : accès aux PV, signatures et receptions.
  • Module Finances des chantiers : accès aux revenus, catégories, achats affectes et marges.
  • Module Sous-traitants des chantiers : accès aux sous-traitants et affectations.
  • Feature FEATURE_GERER_PV_CHANTIER : active les capacites PV. Les scripts SQL la referencent avec l'identifiant historique 46.

Le modèle de gestion contient aussi des droits par collaborateur sur certaines sections chantier :

  • informations chantier ;
  • email et téléphone client ;
  • adresse ;
  • tâches et toutes les tâches ;
  • planning ;
  • documents ;
  • achats ;
  • finance et marge ;
  • facturation ;
  • reception/PV ;
  • messagerie.

Point important : un utilisateur peut avoir une permission globale sans avoir accès a toutes les données d'un chantier partage. Inversement, un accès collaborateur ne doit pas contourner les permissions sensibles, notamment finance et marge.

Modèle de données

Scripts SQL a lire avant toute modification :

  • app/bd/chantiers.sql
  • app/bd/chantiers-management.sql
  • app/bd/chantiers-collaborator-access.sql
  • app/bd/chantiers-mapbox.sql
  • app/bd/chantiers-payment-confirmation.sql
  • app/bd/chantiers-payment-declaration.sql
  • app/bd/chantiers-planning-operational-assignment.sql
  • app/bd/chantiers-subcontractor-invitations.sql
  • app/bd/chantiers-tpe-feature.sql
  • app/bd/chantiers-v1-corrections.sql

Tables a connaitre :

  • chantiers : entité principale.
  • chantier_lines : lignes du chantier ou du PV.
  • chantier_installers : installateurs/intervenants.
  • chantier_receptions : réception, réserves, signatures, paiement déclaré.
  • chantier_lots : découpage opérationnel.
  • chantier_tasks : tâches rattachées au chantier ou aux lots.
  • chantier_documents : documents chantier.
  • chantier_planning_events : événements planning.
  • chantier_access_grants : droits collaborateurs.
  • chantier_kanban_columns : colonnes kanban personnalisées.
  • chantier_expense_categories : catégories financières.
  • chantier_revenues : revenus chantier.
  • chantier_subcontractors : sous-traitants.
  • chantier_subcontractor_assignments : affectations de sous-traitants.
  • devis, factures, achats, clients, membres, societes, fournisseurs : tables reliées au module.

Plusieurs modèles vérifient ou complètent le schéma à l'exécution. Cette logique aide en reprise, mais elle ne remplace pas une migration SQL claire. Une évolution durable doit être documentée dans app/bd/ et testée sur une base staging.

Colonnes sensibles de chantiers

Colonnes d'identité et d'isolation :

  • id : identifiant technique.
  • societe_id : cloisonnement principal. Toute requête métier doit l'utiliser ou passer par une methode qui le fait.
  • client_id : client rattaché, nullable.
  • created_by_membre_id : membre createur.
  • responsible_membre_id : responsable opérationnel.
  • parent_chantier_id : lien vers un chantier parent, notamment utile dans le suivi de reserves.
  • origin_reception_id : reception d'origine pour les suivis.

Colonnes de workflow :

  • pv_kind : vaut reception par défaut ; les suivis de réserve utilisent reserve_follow_up.
  • status : statut opérationnel/kanban.
  • pv_status : statut de PV/signature, distinct du statut opérationnel.
  • archived_at : archive logique ; les listes principales filtrent archived_at IS NULL.
  • progress_percent, planned_start_date, planned_end_date, actual_start_date, actual_end_date : pilotage planning/progression.

Colonnes source commerciale :

  • source_type : source fonctionnelle, par exemple manuel ou devis selon les normalisations du modèle.
  • source_id : identifiant du document source.
  • source_number : numéro/référence lisible.
  • amount_ttc, deposit_paid_ttc, balance_due_ttc : montants issus du PV/document. Ne pas les confondre avec le paiement declare.

Colonnes adresse/carte :

  • site_address
  • site_address_formatted
  • site_lat
  • site_lng
  • site_place_id
  • site_map_provider
  • site_geocoded_at

Colonnes paiement PV declare :

  • payment_declared_amount_ttc
  • payment_declared_mode
  • payment_declared_at
  • payment_declared_by_membre_id

Colonnes historiques a manier avec prudence :

  • payment_facture_id
  • payment_id
  • payment_confirmed_at
  • payment_confirmed_by_membre_id

Les tests actuels imposent que recordPayment n'utilise pas payment_facture_id, payment_id, deposit_paid_ttc ni balance_due_ttc. Ces colonnes peuvent encore exister pour compatibilité ou historique, mais elles ne doivent pas être reactives dans le flux de declaration de paiement PV.

Tables operationnelles

chantier_lines

  • Lignes simples du chantier/PV : designation, quantity, sort_order.
  • Suppression en cascade via chantier_id.

chantier_installers

  • Table pivot chantier_id / membre_id.
  • Sert à matérialiser les installateurs liés au PV.

chantier_receptions

  • Une seule reception par chantier via UNIQUE KEY uk_chantier_reception_chantier.
  • Champs de decision : decision, reserve_text.
  • Signature artisan : artisan_signer_name, artisan_membre_id, artisan_signature_path, artisan_signed_at.
  • Signature client : client_signer_name, client_signature_path, client_signed_at.
  • Audit signature : signed_mode, signed_ip, signed_user_agent, signed_pdf_path.

chantier_lots et chantier_tasks

  • Les tâches dependent d'un lot (lot_id obligatoire), pas directement du chantier.
  • Les deux tables portent status, sort_order, created_at, updated_at.
  • Supprimer un lot supprime ses tâches par cascade.

chantier_planning_events

  • Lie un événement au chantier et à la société.
  • assigned_to est textuel ; assigned_membre_id est l'affectation opérationnelle structuree.
  • assignment_status vaut assigned par défaut depuis la migration opérationnelle.

chantier_documents

  • Document rattaché au chantier avec type, name, url, notes.
  • Le code stocke une URL/chemin, pas un blob.

chantier_access_grants

  • Accès collaborateurs par chantier.
  • Sert a restreindre les sections visibles pour les collaborateurs assignes.
  • Le modèle peut backfiller des grants existants au constructeur.

chantier_kanban_columns

  • Colonnes kanban par société.
  • Le modèle crée les colonnes par défaut, assure le schéma, puis backfill les chantiers sans colonne.

Tables finance et achats

chantier_expense_categories

  • Categories par société.
  • Unicite societe_id + name.
  • Categories par défaut inserees par migration : Materiaux, Transport, Location, Sous-traitance, Consommables, Deplacement, Autre.

chantier_revenues

  • Revenus et crédits chantier.
  • kind vaut revenue par défaut, ou credit pour inverser le signe dans certains calculs.
  • status est utilise dans les agregats ; getPaginatedChantiers ne compte que validated, invoiced, collected.
  • source_type + source_id sont uniques par société pour éviter le double rattachement d'une même source.

achats

  • La migration ajouté chantier_id et expense_category_id.
  • chantier_id est en ON DELETE SET NULL : supprimer un chantier ne supprimé pas l'achat.
  • Les agregats de depenses de getPaginatedChantiers additionnent achats.montant_ht quand chantier_id IS NOT NULL.

Tables sous-traitance

chantier_subcontractors

  • Fiche sous-traitant propre à une société.
  • Peut pointer vers fournisseur_id, linked_societe_id, linked_membre_id.
  • invitation_status vaut external par défaut.

chantier_subcontractor_assignments

  • Affectation d'un sous-traitant à un chantier.
  • Porte les montants prevus/réels, les dates prévues et les droits de section.
  • Les colonnes access_* de cette table ne couvrent pas access_all_tasks, présent dans les accès collaborateurs du modèle. Ne pas aligner ces deux mecanismes sans vérifier le besoin produit.

Statuts et constantes métier

Statuts kanban par défaut :

  • a_planifier
  • planifie
  • en_cours
  • a_receptionner
  • reserves_a_lever
  • termine
  • annule

Priorites connues :

  • low
  • normal
  • high
  • urgent

Les libellés peuvent être affichés différemment dans l'interface, mais les identifiants ci-dessus sont les valeurs techniques attendues par le backend. Éviter de renommer ces valeurs sans migration complète des données existantes.

Statuts PV observes dans le code

Les tests et le code referencent notamment :

  • draft
  • pending_client_signature
  • signed
  • signed_with_reserve
  • closed

recordPayment refuse la declaration si pv_status est déjà dans signed, signed_with_reserve ou closed. Cette condition protège contre une declaration concurrente après signature.

Flux : création et édition chantier

Le flux de création peut partir d'un formulaire chantier, d'un devis, d'une facture ou d'un contexte commercial déjà connu.

Points a vérifier dans le code avant modification :

  • filtrage systematique par societe_id ;
  • rattachement client ;
  • reprise des lignes du document source ;
  • initialisation des statuts ;
  • création eventuelle de lots, tâches ou données planning ;
  • contrôles sur les droits d'accès et les permissions module.

Une erreur classique consiste a créer un chantier visible globalement mais incomplet pour les vues détaillées. Apres modification du flux de sauvegarde, tester au minimum la liste, la fiche, le kanban, le planning et le PV.

Lecture liste et filtrage

ChantierManagementModel::getPaginatedChantiers applique les contraintes suivantes :

  • pagination bornee entre 1 et 100 éléments par page ;
  • ch.societe_id = activeSocieteId ;
  • ch.archived_at IS NULL ;
  • exclusion des suivis de réserve : COALESCE(ch.pv_kind, 'reception') <> 'reserve_follow_up' ;
  • recherche sur reference, title, client_name, site_address ;
  • filtre status seulement si la colonne kanban existe ;
  • filtre responsible_membre_id ;
  • restriction supplementaire si l'utilisateur courant est un collaborateur assigne.

La liste enrichit chaque ligne avec :

  • client ;
  • responsable ;
  • colonne kanban ;
  • revenu realise ;
  • nombre de revenus ;
  • depense realisee.

Si l'utilisateur est restreint à des chantiers assignes, le modèle charge le grant courant, ajouté les champs shared_access_*, pose is_restricted_collaborator = 1, force can_manage = 0 et sanitize la ligne. C'est une barriere de confidentialite importante : ne pas la contourner en ajoutant une requête parallele côté contrôleur.

Sauvegarde PV historique

ChantierModel::save protège explicitement plusieurs cas :

  • en édition, le chantier doit exister ;
  • un PV déjà signé ne peut plus être modifié ;
  • le client est obligatoire et doit appartenir à la société active ;
  • une source de type facture est refusée pour le PV historique avec le message invitant a rattacher un devis ou a utiliser la saisie manuelle.

Cette distinction est importante parce que le module de gestion chantier accepte des rattachements plus larges, alors que le flux PV historique reste plus strict.

Flux : kanban, lots et tâches

Le kanban est gère par ChantierManagementController et ChantierManagementModel.

Le module supporte :

  • deplacement d'un chantier entre colonnes ;
  • création, édition, suppression et reordonnancement de colonnes ;
  • lots de chantier ;
  • tâches rattachees à un chantier ou à un lot ;
  • changement de statut des tâches ;
  • suppression de tâches et de lots.

La suppression d'une colonne, d'un lot ou d'une tâche doit toujours être analysee avec les relations existantes. Avant de supprimer physiquement une donnée, vérifier si l'interface attend un archivage, une reaffectation ou une suppression en cascade.

Colonnes kanban

Le modèle exécute au constructeur :

  • ensureKanbanSchema;
  • ensureDefaultKanbanColumns;
  • backfillKanbanColumns;
  • backfillCollaboratorAccessGrants.

Cela signifie que le module peut modifier ou complèter la base au chargement. En reprise, ne pas se contenter de tester une base déjà chaude : tester aussi une base fraiche ou partiellement migrée pour vérifier que les migrations SQL et les ensure runtime racontent la même histoire.

Les actions de colonnes exposees par le contrôleur sont :

  • création/mise à jour : saveColumn;
  • suppression simple : deleteColumn;
  • suppression multiple : deleteColumns;
  • reordonnancement : reorderColumns;
  • deplacement chantier : moveToColumn.

Avant de supprimer une colonne, vérifier la stratégie exacte du modèle : reaffectation des chantiers, archivage de colonne, ou refus si la colonne contient encore des chantiers.

Flux : planning et carte

Le planning s'appuie sur chantier_planning_events.

Fonctions associées :

  • lecture du planning ;
  • création et mise à jour d'événement ;
  • suppression d'événement ;
  • marquage "vu" ;
  • suggestion, récupération et itineraire Mapbox.

Mapbox est une dependance externe : ne pas exposer de clé dans la documentation publique. Pour reprendre le module, chercher les variables d'environnement ou la configuration applicative déjà en place au lieu de hardcoder une clé dans le code.

Affectation planning

chantier_planning_events contient deux notions :

  • assigned_to : texte libre historique ;
  • assigned_membre_id : relation structuree vers un membre.

La migration chantiers-planning-operational-assignment.sql ajouté aussi assignment_status et l'index idx_chantier_planning_events_assignee. Les vues operationnelles peuvent donc filtrer un planning par membre assigne. Tester le cas ou assigned_to est rempli mais assigned_membre_id est nul : c'est un état possible sur données anciennes.

Flux : documents, achats, devis et factures

Le module fait le pont entre le suivi opérationnel et les documents commerciaux.

Fonctions importantes :

  • ajout/suppression de documents chantier ;
  • rattachement et detachement de devis ;
  • rattachement de factures ;
  • affectation d'achats existants ;
  • création d'achat depuis un chantier ;
  • retrait d'une affectation achat.

Le risque principal est de melanger les notions suivantes :

  • document commercial client : devis/facture ;
  • achat fournisseur : table achats ;
  • document chantier : table chantier_documents ;
  • revenu chantier : table chantier_revenues ;
  • paiement declare dans un PV : données de reception, sans effet comptable facture.

Rattachements commerciaux

Le contrôleur de gestion expose trois familles d'actions a ne pas confondre :

  • linkDevis / unlinkDevis : relation devis vers chantier.
  • linkInvoice : rattachement facture.
  • assignPurchase / createPurchase / unassignPurchase : achat fournisseur.

Le modèle financier utilise chantier_revenues pour representer les revenus chantier. Les factures/devis peuvent donc être source d'un revenu, mais une ligne de revenu chantier n'est pas automatiquement une facture, et un achat chantier n'est pas automatiquement un document Pennylane.

Flux : finances chantier

Le module finance permet de suivre revenus, achats affectes, catégories et marges. Il doit rester strictement cloisonne par société et par permission.

Règles de reprise :

  • masquer les montants et marges aux utilisateurs non autorisés ;
  • ne pas recalculer la comptabilite facture depuis un simple changement de catégorie chantier ;
  • ne pas assimiler une declaration de paiement PV à un paiement comptable ;
  • vérifier les totaux HT/TTC et les arrondis si des montants sont modifiés ;
  • tester les cas sans achat, sans revenu, avec plusieurs achats et avec achat retire.

Calculs à surveiller

Dans la liste chantier, le revenu realise est calcule depuis chantier_revenues :

  • kind = credit est soustrait ;
  • les autres kind sont ajoutes ;
  • seuls les statuts validated, invoiced, collected comptent.

La depense realisee est calculee depuis achats.montant_ht. Si le modèle des achats évolue vers plusieurs montants HT/TTC, catégories multiples ou devises, cette requête devra être revue.

Les permissions finance et marge sont separees dans les grants :

  • access_finance
  • access_margin
  • access_billing
  • access_purchases

Ne pas afficher une marge simplement parce que l'utilisateur peut voir les achats.

Flux : reception, PV et signature

Le PV de chantier est gère par ChantierController et ChantierModel.

Flux principal :

  1. création du chantier ou rattachement à un document source ;
  2. préparation des données de reception ;
  3. signature interne ou presentielle selon le contexte ;
  4. envoi eventuel de demande de signature client ;
  5. signature distante via page publique contrôlee ;
  6. generation/consultation PDF ;
  7. declaration de paiement liée au PV, si applicable.

Invariants importants :

  • une signature ne doit pas rendre modifiable un PV qui doit rester auditable ;
  • les reserves doivent rester visibles et exploitables après signature ;
  • la signature client distante doit être contrôlee par un jeton ou un contexte sécurisé ;
  • les actions publiques ne doivent pas exposer d'autres chantiers de la société ;
  • la signature business/interne reste requise avant certains envois client selon le workflow teste.

Reception depuis gestion chantier

ChantierManagementController::createReception delegue a ChantierManagementModel::createReception. Le test chantier_reception_workflow_test.php vérifie que :

  • la création depuis chantier est presentee comme un brouillon ;
  • le statut pending_client_signature est visible côté JS ;
  • le panneau PV exploite chantier.reserve_follow_ups ;
  • le modèle enrichit les chantiers avec appendPvWorkflowContext ;
  • les suivis de reserves sont recuperes via getReserveFollowUps ;
  • l'envoi client passe par pv-chantier/send-signature-request ;
  • la signature entreprise reste obligatoire avant l'envoi client ;
  • la signature client reste obligatoire pour une signature sur place.

Ces assertions sont textuelles, mais elles capturent une intention produit : le PV n'est pas un simple bouton "signer", il à un état de brouillon, un mode de signature distante et un mecanisme de reserves.

Paiement declare dans le PV

La declaration de paiement du PV est volontairement isolee de la comptabilite facture. Les tests existants protegent cette règle.

Ce que le flux doit faire :

  • enregistrer le montant declare sur les données chantier/reception ;
  • permettre la signature finale quand les conditions sont remplies ;
  • éviter les doubles soumissions côté front et côté backend.

Ce que le flux ne doit pas faire automatiquement :

  • créer une ligne de paiement comptable ;
  • modifier l'état de paiement d'une facture ;
  • recalculer deposit_paid_ttc, balance_due_ttc ou des champs equivalents ;
  • appeler des méthodes de rapprochement facture sans intention explicite.

Avant toute évolution, relire tests/chantier_payment_accounting_isolation_test.php et tests/pv_signature_payment_submission_test.php.

Garde-fous vérifiés par test

tests/chantier_payment_accounting_isolation_test.php extrait directement les methodes du modèle et vérifie que :

  • le schéma contient payment_declared_amount_ttc ;
  • recordPayment écrit payment_declared_amount_ttc ;
  • recordPayment écrit payment_declared_at ;
  • recordPayment passe par normalizeDeclaredPaymentAmount ;
  • recordPayment contient la condition pv_status NOT IN ('signed', 'signed_with_reserve', 'closed') ;
  • recordPayment vérifie mysqli_stmt_affected_rows après mise à jour conditionnelle ;
  • recordPayment ne contient pas resolvePaymentFactureId, insertPayment, refreshFacturePaymentState, payment_facture_id, payment_id, deposit_paid_ttc, balance_due_ttc ;
  • markPaymentAlreadyHandled et signRemoteClient ne modifient pas deposit_paid_ttc ni balance_due_ttc.

Si un futur besoin produit demande de convertir une declaration PV en paiement comptable, le faire dans un flux explicite, nomme et teste separement. Ne pas réutiliser silencieusement recordPayment.

Flux : sous-traitants

Le module sous-traitants couvre :

  • fiche sous-traitant ;
  • recherche de sociétés ;
  • affectation sur chantier ;
  • création d'affectation avec un nouveau sous-traitant ;
  • invitation ;
  • acceptation d'invitation ;
  • démarrage d'une conversation ;
  • archivage.

Les affectations croisent les modules Chantiers et Messagerie. Une invitation acceptée peut donc avoir des effets sur les droits d'accès, la visibilité des données et la conversation associée.

Accès sous-traitants vs accès collaborateurs

Deux mecanismes coexistent :

  • les grants collaborateurs gérés par chantier_access_grants et les colonnes ACCESS_COLUMNS du modèle ;
  • les droits d'affectation sous-traitant portes directement par chantier_subcontractor_assignments.

Ils se ressemblent, mais ne sont pas identiques. Par exemple, access_all_tasks existe dans le modèle de grants collaborateurs, alors que l'affectation sous-traitant expose access_tasks sans access_all_tasks. Toute factorisation doit donc commencer par une matrice de compatibilité, pas par un renommage mecanique.

Schémas runtime vs migrations SQL

Le module contient beaucoup de logique ensure* et backfill*. C'est utile en production pour absorber des données anciennes, mais c'est aussi un risque documentaire : un développeur peut croire que le schéma est entierement porte par app/bd.

Regle de reprise :

  • quand une colonne est utilisée par le code, chercher d'abord la migration SQL ;
  • si elle est créée seulement par une methode ensure*, documenter l'ecart ;
  • si la migration SQL et le runtime divergent, corriger la migration avant de livrer une installation neuve ;
  • ne pas ajouter une nouvelle colonne uniquement dans un ensure* sans script SQL.

Integrations internes

  • Devis et factures : source de création ou de rattachement.
  • Achats fournisseurs : depenses operationnelles.
  • Messagerie : conversations avec sous-traitants ou collaborateurs.
  • Clients : données de contact et signature.
  • Membres/collaborateurs : accès et attribution.
  • Pennylane : indirectement via factures/avoirs et états commerciaux, mais le paiement déclaré PV ne doit pas déclencher de synchronisation comptable.

Bugs et zones signalées

À confirmer en environnement staging avant correction :

  • incohérences possibles entre données chantier, facture et avoir lorsque le chantier est rattaché à des documents commerciaux modifiés ensuite ;
  • confusion possible entre paiement déclaré au PV et paiement facture ;
  • comportements à vérifier sur les documents commerciaux archivés ou modifiés après rattachement.

Pour qualifier un bug, relever :

  • identifiant chantier ;
  • société ;
  • document source ;
  • facture/devis/avoir rattaché ;
  • statut kanban ;
  • statut de réception/PV ;
  • utilisateur et permissions ;
  • action exacte effectuee ;
  • état attendu et état observe.

Tests existants

  • tests/chantier_payment_accounting_isolation_test.php : vérifie que le paiement PV ne touche pas la comptabilite facture.
  • tests/chantier_reception_workflow_test.php : couvre le workflow reception/signature/reserves.
  • tests/pv_signature_payment_submission_test.php : couvre la sauvegarde paiement avant signature et la prevention des doubles soumissions.

Tests recommandés avant livraison

  • Création chantier depuis formulaire vierge.
  • Création chantier depuis devis.
  • Rattachement puis detachement devis.
  • Rattachement facture.
  • Création achat depuis chantier puis retrait.
  • Vue finance avec et sans permission.
  • Création lot, tâche, changement statut, suppression.
  • Deplacement kanban et reordonnancement colonnes.
  • Planning : création, modification, suppression.
  • Accès collaborateur avec droits limités.
  • Invitation sous-traitant et acceptation.
  • Création PV, reserves, signature interne, signature client distante.
  • Declaration de paiement PV sans changement d'état facture.

Commandes utiles

php tests/chantier_payment_accounting_isolation_test.php
php tests/chantier_reception_workflow_test.php
php tests/pv_signature_payment_submission_test.php

Adapter les commandes si l'environnement local utilise un lanceur de tests different.

Checklist de reprise

  • Lire les quatre contrôleurs avant de modifier un flux.
  • Vérifier les migrations SQL disponibles dans app/bd/.
  • Identifier les permissions nécessaires pour reproduire le cas.
  • Tester avec au moins deux sociétés pour valider l'isolation societe_id.
  • Tester un utilisateur sans permission finance.
  • Tester un chantier avec documents commerciaux rattaches.
  • Tester un PV signé pour éviter les régressions d'auditabilité.
  • Vérifier que les exports/PDF ne revelent pas des données masquees dans l'interface.

Questions ouvertes

  • Faut-il consolider les anciens écrans chantiers.php et les vues chantier-management.php ou conserver les deux surfaces ?
  • Quelle est la règle produit exacte entre chantier terminé, PV signé et facture soldée ?
  • Les documents commerciaux archives doivent-ils rester rattachables en lecture seule ou être totalement exclus des nouveaux rattachements ?
  • Les colonnes kanban personnalisees doivent-elles être globales à la société ou propres à chaque utilisateur ?