Transactions

Les transactions créent une piste d'audit immuable de chaque mouvement d'inventaire, consommation, réception et ajustement. Les transactions ne peuvent pas être éditées ou supprimées - les corrections ajoutent de nouvelles transactions d'ajustement.

Types de Transactions

Flux de Transaction :

Réception     Transfert          Collecte              Consommation    Ajustement
   ↓              ↓                  ↓                      ↓               ↓
Nouveau Stock  Site A→Site B  QR Tâche-Ressource   Le Travail Épuise  Correction Manuelle
(Achat)       (Dépl. générique) (Scan pour collecter) (Soumis rapport) (Comptage cyclique)

Page des transactions montrant la piste d'audit de tous les mouvements d'inventaire

Réception

Nouvel inventaire arrive à un site (achats, retours du terrain).

Champs :

• toSite - Site destination
• resource - Ce qui est arrivé
• toVolume - Nouveau solde d'élément de stock après réception
• uom - Unité de mesure

Exemple : 100m de câble arrive à l'entrepôt

type: "receipt"
toSite: Entrepôt Central
resource: Câble Cat6
toVolume: 600m (était 500m, maintenant 600m)

Transfert

L'inventaire se déplace entre sites (entrepôt → travailleur, travailleur → site terrain).

Champs :

• fromSite - Emplacement source
• toSite - Emplacement destination
• resource - Ce qui s'est déplacé
• fromVolume - Solde source après transfert
• toVolume - Solde destination après transfert
• pickupCode - JWT scanné (si transfert basé QR)
• scannerUserId - Qui a scanné QR
• scanMethod - "self" (travailleur) ou "staff" (personnel d'entrepôt)
• scanLocation - Coordonnées GPS où le scan s'est produit

Exemple : Le travailleur retire 10m de câble via scan QR

type: "transfer"
fromSite: Entrepôt Central
toSite: Inventaire Personnel de John
resource: Câble Cat6
fromVolume: 590m (entrepôt réduit de 600m)
toVolume: 10m (nouvel élément de stock de John)
pickupCode: "eyJhbGc..." (JWT)
scannerUserId: john_id
scanMethod: "self"
scanLocation: { lat: 40.7128, lng: -74.0060 }

Consommation

Le travail sur le terrain épuise l'inventaire (création automatique lors de la soumission du rapport).

Champs :

• fromSite - D'où les matériaux ont été consommés (généralement site personnel du travailleur)
• resource - Ce qui a été consommé
• fromVolume - Solde restant après consommation
• reportId - Lien vers le rapport de travail (pour calcul de paiement)

Exemple : Le travailleur utilise 8m de câble en terminant la tâche

type: "consumption"
fromSite: Inventaire Personnel de John
resource: Câble Cat6
fromVolume: 2m (réduit de 10m)
reportId: report_abc123

Ajustement

Correction manuelle des niveaux de stock (comptages cycliques, dommage, perte).

Champs :

• stockItemId - Quel élément de stock ajusté
• resource - Ce qui a été ajusté
• fromVolume - Solde précédent
• toVolume - Nouveau solde
• reason - Explication requise (par exemple, "Correction de comptage physique", "Endommagé en transit")

Exemple : Le comptage cyclique trouve un écart

type: "adjustment"
stockItemId: stock_xyz
resource: Câble Cat6
fromVolume: 2m (solde enregistré)
toVolume: 0m (comptage physique réel)
reason: "Comptage cyclique 2026-02-10 - extrémité de rouleau jetée"

Collecte

Collecte de matériau liée à une tâche, créée automatiquement lorsqu'un travailleur scanne le code QR d'une ressource de tâche.

Une transaction de collecte enregistre la ressource collectée, le volume, le site source, la personne qui a scanné (collecteur effectif), ainsi qu'un lien vers la tâche et la ligne de ressource spécifique au sein de cette tâche (context: { taskId, taskResourceIdx }). La collecte se distingue du transfert : un transfert déplace de l'inventaire entre sites de façon générique ; une collecte est un transfert avec contexte de tâche — elle rattache directement la déduction de stock à un poste de travail planifié spécifique. Ce lien contextuel permet d'interroger « quelle quantité de cette ressource a été collectée pour la tâche X » en agrégeant les transactions de collecte, plutôt qu'en maintenant un total courant sur la tâche elle-même.

Les codes QR de collecte sont à usage unique (la réutilisation est rejetée avec une erreur de conflit). Les codes peuvent être annulés (stock restitué via une transaction de retour) ou régénérés (nouveau code émis, ancien code invalidé) de façon indépendante.

Champs de Transaction

Communs à Tous les Types :

• type - receipt, transfer, consumption, adjustment
• resource - Référence de définition de ressource
• uom - Unité de mesure
• createdAt - Horodatage (auto-généré)
• createdBy - Utilisateur qui a initié (auto-capturé)
• properties - JSON flexible pour données personnalisées

Spécifiques au Type :

• fromSite / toSite - Points d'extrémité de mouvement
• fromVolume / toVolume - Changements de solde
• reportId - Lien vers rapport de travail (consommation)
• pickupCode - JWT scanné (transferts protégés)
• scannerUserId - Qui a scanné (transferts)
• scanMethod - Auto-retrait vs assisté par le personnel
• scanLocation - GPS au moment du scan
• reason - Explication (ajustements)

Immuabilité des Transactions

Ne Peuvent Pas Être Éditées :

• Les transactions sont en écriture seule
• Pas d'opérations de mise à jour ou suppression
• Préserve l'intégrité de la piste d'audit

Faire des Corrections :

1. N'essayez pas d'éditer la mauvaise transaction
2. Créez une nouvelle transaction adjustment
3. Incluez une raison détaillée expliquant la correction
4. Les deux transactions restent dans l'historique

Exemple de Flux de Correction :

Jour 1 : La réception montre 100 unités arrivées
  → Crée transaction : toVolume = 100

Jour 2 : Découvre que seulement 95 unités reçues réellement
  → Crée ajustement : fromVolume = 100, toVolume = 95
  → Raison : "Erreur de comptage de réception - seulement 95 unités dans l'expédition"

Résultat : Les deux transactions visibles dans la piste d'audit

Création Automatique de Transactions

Depuis la Soumission de Rapport

Lorsque le travailleur soumet un rapport avec le champ consumedFrom :

1. Le système valide la disponibilité du stock à chaque élément de stock
2. Crée atomiquement des transactions de consommation pour chaque ressource
3. Lie les transactions au rapport via reportId
4. Épuise les volumes d'éléments de stock
5. Si stock insuffisant → rejette le rapport OU invite à consommation partielle

Avantages :

• Le stock toujours précis (impossible d'oublier d'enregistrer la consommation)
• Rapport + transaction validés ensemble (atomique)
• Le calcul de paiement a des données fiables

Depuis le Scan de Retrait QR

Lorsque le travailleur scanne le QR de retrait d'attribution :

1. Valide la signature JWT et l'expiration
2. Vérifie que le scanner est le destinataire autorisé OU a canFacilitatePickups
3. Vérifie la disponibilité du stock au site source
4. Crée automatiquement la transaction de transfert
5. Enregistre l'identité du scanner, la méthode, l'emplacement GPS

Avantages :

• Pas d'entrée manuelle de transaction
• GPS prouve la présence physique
• La piste d'audit montre qui a autorisé le transfert

Voir les Transactions

Journal Global des Transactions :

• Naviguer vers Inventaire → Transactions
• Filtrer par type, plage de dates, site, ressource
• Exporter pour rapprochement ou conformité

Historique d'Élément de Stock :

• Naviguer vers un élément de stock spécifique
• "Historique des Transactions" montre tous les mouvements affectant cet élément
• Tracer la lignée (d'où venaient les matériaux, où sont-ils allés)

Consommation de Rapport :

• Naviguer vers le rapport de travail
• La section "Matériaux Utilisés" lie aux transactions de consommation
• Vérifier ce qui a été réellement épuisé de l'inventaire

Activité du Site :

• Naviguer vers le site
• "Transactions Récentes" montre réceptions, transferts, consommations
• Surveiller le débit de l'entrepôt

Cas d'Usage

Audit de Conformité

• Montrer tous les mouvements de matériaux contrôlés
• Prouver la chaîne de garde (réception → transfert → consommation)
• Exporter le journal des transactions pour les rapports réglementaires

Prévention des Pertes

• Comparer les réceptions aux consommations au fil du temps
• Identifier les écarts nécessitant une enquête
• Suivre les patterns d'ajustement (ajustements fréquents = problèmes potentiels)

Calcul de Paiement

• Consommations liées aux rapports via reportId
• Calculer les coûts de matériaux pour le travail terminé
• Vérifier que le travailleur a utilisé les matériaux assignés (pas le stock personnel)

Rapprochement d'Inventaire

• Comparer les soldes basés sur transactions aux comptages physiques
• Identifier la contraction ou les erreurs de comptage
• Créer des ajustements pour corriger les écarts

Responsabilité du Travailleur

• Voir l'historique de retrait et consommation du travailleur individuel
• Identifier qui a scanné l'inventaire protégé
• La validation GPS montre où les matériaux ont été transférés

Meilleures Pratiques

Toujours Inclure la Raison pour les Ajustements :

• "Correction de comptage physique" est mieux que pas de raison
• "Matériaux endommagés jetés - événement tempête 2026-02-08" encore mieux
• Aide les futurs auditeurs à comprendre les corrections

Utiliser les Plus Petits Types de Transaction :

• N'utilisez pas d'ajustements quand réception/transfert approprié
• Les ajustements devraient être l'exception, pas la routine
• Les réceptions/transferts préservent un contexte plus riche

Rapprochement Régulier :

• Hebdomadaire : Examiner les ajustements (devraient être rares)
• Mensuel : Comptage cyclique des éléments de stock majeurs
• Trimestriel : Rapprochement complet d'entrepôt

Tirer Partie du GPS pour les Transferts :

• Examiner scanLocation pour l'inventaire protégé
• Détecter les anomalies (scan 100km de l'entrepôt)
• La validation de géofence empêche le partage QR à distance

Surveiller le Volume des Transactions :

• Taux d'ajustement élevé = problèmes de processus
• Faible consommation avec retraits élevés = accumulation ou vol
• Inadéquation réception/consommation = problèmes de prévision de demande

Permissions de Transaction

Créer des Transactions :

• transactionsCreate - Peut créer des réceptions, ajustements
• Les transactions auto-créées (depuis rapports, scans QR) ne nécessitent pas de permission
• Les permissions spécifiques au site peuvent limiter qui crée des réceptions à quels sites

Voir les Transactions :

• Tous les utilisateurs peuvent voir les transactions pour leurs propres éléments de stock
• Les restrictions de rôle peuvent masquer les transactions pour certaines ressources/sites
• viewDeleted permet de voir les transactions supprimées logiquement (si jamais implémenté)

Pas de Permission de Suppression :

• Les transactions ne peuvent pas être supprimées par quiconque
• Maintient l'intégrité de la piste d'audit
• Seulement l'administrateur de base de données pourrait supprimer (urgence opérationnelle seulement)

Saisie de Transaction Manuelle avec Numérisation de Code QR

Pour les expéditions arrivant sur des sites où les articles n'ont pas d'existant codes QR, le personnel de terrain peut utiliser le Formulaire de Transaction Manuel avec numérisation QR intégrée pour accepter rapidement l'inventaire en utilisant un livre de référence physique de codes QR de ressources.

Création d'un Livre de Référence Physique de Ressources

Configuration Admin (Une Fois) :

1. Naviguer vers Admin → Codes QR de Ressource (/admin/resource-qr-codes)
2. Filtrer par type de ressource si nécessaire (Matériel, Main-d'œuvre, Équipement)
3. Rechercher des ressources spécifiques à inclure
4. Cliquer sur Imprimer pour générer une feuille de codes QR imprimable
5. Imprimer sur du papier standard lettre/A4
6. Laminer les pages et relier en livre de référence
7. Placer le livre au quai de réception ou station d'entrepôt

Format de Code QR : Chaque code QR contient des données JSON :

{
  "type": "resource",
  "id": "resource_id_123",
  "name": "Câble Cat6",
  "defaultUom": "m",
  "resourceType": "material"
}

Workflow Mobile pour l'Acceptation d'Expéditions

Processus du Personnel de Terrain :

1. Ouvrir le Formulaire de Transaction Manuel
   • Naviguer vers Inventaire → Transactions
   • Cliquer sur le bouton "Ajouter une Transaction Manuelle"
   • Nécessite la permission canFacilitatePickups
2. Activer le Mode Lot (Optionnel mais Recommandé)
   • Basculer le commutateur "Mode Lot" en haut du formulaire
   • Permet de scanner et saisir plusieurs articles avant la soumission finale
   • Économise du temps quand l'expédition contient 5+ articles différents
3. Scanner le Code QR de Ressource
   • Cliquer sur le bouton de scan (📷 icône) à côté du champ Nom de Ressource
   • La caméra s'ouvre sur l'appareil mobile
   • Pointer la caméra vers le code QR du livre de référence
   • Les données QR se remplissent automatiquement : Nom de Ressource, ID de Ressource, UOM par Défaut
4. Saisir les Détails de Quantité
   • Champ Volume : Saisir la quantité reçue (par exemple, "50")
   • Champ UOM : Pré-rempli à partir du QR, ajuster si nécessaire (par exemple, "m" pour mètres)
   • Site : Glisser-déposer le site de destination ou utiliser l'emplacement actuel
5. Ajouter au Lot (Si Mode Lot Activé)
   • Cliquer sur le bouton "Ajouter au Lot"
   • L'article apparaît dans la liste de lot ci-dessous
   • Le formulaire se vide pour l'article suivant
   • Répéter les étapes 3-5 pour chaque article de l'expédition
6. Soumettre les Transaction(s)
   • Mode unique : Cliquer sur "Soumettre" (crée une transaction)
   • Mode lot : Cliquer sur "Soumettre Lot (N articles)" (crée N transactions atomiquement)
   • Notification de succès montre combien d'articles ont été acceptés
   • Si certains articles échouent, le système rapporte le nombre mais ne rollback pas les autres

Exemple de Workflow Lot :

Une expédition arrive avec 5 matériaux différents :
1. Scanner "Câble Cat6" QR → Saisir 50m → Ajouter au Lot
2. Scanner "Conduit 1in" QR → Saisir 20 unités → Ajouter au Lot
3. Scanner "Boîte de Jonction" QR → Saisir 15 unités → Ajouter au Lot
4. Scanner "Collier de Câble" QR → Saisir 500 unités → Ajouter au Lot
5. Scanner "Fil de Terre" QR → Saisir 100m → Ajouter au Lot
6. Soumettre Lot (5 articles)
→ Crée 5 articles de stock + 5 transactions de réception instantanément

Gestion des Ressources Inconnues

Si l'expédition contient des articles pas dans le livre de référence :

1. Taper le Nom de Ressource Manuellement
   • Saisir le nom dans le champ Nom de Ressource (pas de scan QR)
   • Le système recherche une ressource existante par nom
   • Si non trouvée → place automatiquement dans la ressource "Holding/Staging"
2. Workflow Holding/Staging
   • Les propriétés de transaction incluent originalResourceName (ce que vous avez tapé)
   • Toast d'avertissement : "Ressource non trouvée. Placée dans Holding/Staging"
   • Article de stock créé avec ressource Holding/Staging
   • Plus tard : Le personnel de bureau alloue à la ressource appropriée (voir Allocation d'Inventaire Mis en Attente ci-dessous)
3. Avantages de l'Auto-Mise en Attente
   • L'acceptation du personnel de terrain n'est jamais bloquée
   • L'inventaire est physiquement accepté et suivi immédiatement
   • La catégorisation des ressources se produit de manière asynchrone
   • Pas de délais bloquants pour les expéditions urgentes

Fonctionnalités du Mode Lot

Table des Articles en Ligne :

• Montre tous les articles scannés avant soumission
• Affiche : Nom de Ressource, Volume, UOM
• Supprimer des articles individuels avec le bouton X
• Vue visuelle claire de ce qui sera engagé

Soumission :

• Traitement de lot atomique (tout-ou-rien où possible)
• Échecs d'articles individuels rapportés mais n'empêchent pas les autres
• Nombre de succès : "5 transactions créées avec succès"
• Gestion des échecs partiels : "2 articles n'ont pas pu être traités"

Optimisation Mobile :

• Grand bouton de scan tactile
• Accès caméra avec basculement du flash
• Fonctionne hors ligne avec mise en cache PWA
• Sauvegarde automatique du lot dans localStorage (survit au rafraîchissement de page)

Allocation d'Inventaire Mis en Attente

Après que le personnel de terrain ait accepté des ressources inconnues dans Holding/Staging :

1. Naviguer vers les Articles de Stock
   • Filtrer par "Site : Holding/Staging" (si implémenté)
   • Chercher des articles avec isHoldingResource: true
2. Ouvrir le Modal d'Allocation
   • Cliquer sur le bouton "Allouer l'Inventaire Mis en Attente" sur l'article de stock
   • Montre : Volume actuel, Nom original saisi par le personnel de terrain
3. Sélectionner la Ressource Appropriée
   • Option A : Glisser une ressource existante depuis la table des ressources
   • Option B : Basculer "Créer une Nouvelle Ressource" et saisir les détails
   • Saisir la raison d'allocation (par exemple, "Identifié comme câble Cat6A, pas Cat6")
4. Soumettre l'Allocation
   • Met à jour atomiquement :
     • Champ ressource de l'article de stock (Holding → Approprié)
     • Crée une transaction d'ajustement avec la raison d'allocation
     • Préserve originalResourceName dans la transaction

Avantages :

• L'acceptation sur le terrain n'est jamais bloquée
• La catégorisation du bureau préserve la piste d'audit
• Aucun inventaire "disparaît" pendant la transition
• Les notes du travailleur de terrain original sont préservées

Visualisation des Transactions

Journal Global des Transactions :

• Naviguer vers Inventaire → Transactions
• Filtrer par type, plage de dates, site, ressource
• Exporter pour réconciliation ou conformité

Historique d'Article de Stock :

• Naviguer vers un article de stock spécifique
• "Historique des Transactions" montre tous les mouvements affectant cet article
• Tracer la lignée (d'où viennent les matériaux, où vont-ils)

Consommation de Rapport :

• Naviguer vers le rapport de travail
• Section "Matériaux Utilisés" lie aux transactions de consommation
• Vérifier ce qui a été réellement dépensé de l'inventaire

Activité du Site :

• Naviguer vers le site
• "Transactions Récentes" montre réceptions, transferts, consommations
• Surveiller le débit d'entrepôt

Cas d'Usage

Audit de Conformité

• Montrer tous les mouvements de matériaux contrôlés
• Prouver la chaîne de responsabilité (réception → transfert → consommation)
• Exporter le journal des transactions pour reporting réglementaire

Prévention de Perte

• Comparer réceptions à consommations au fil du temps
• Identifier des écarts nécessitant investigation
• Créer des ajustements pour corriger les écarts

Calcul de Paiement

• Consommations liées à des rapports via reportId
• Calculer les coûts de matériaux pour le travail terminé
• Vérifier que le travailleur a utilisé les matériaux assignés (pas le stock personnel)

Réconciliation d'Inventaire

• Comparer les soldes basés sur transactions aux comptages physiques
• Identifier contraction ou erreurs de comptage
• Créer des ajustements pour corriger les écarts

Responsabilité du Travailleur

• Voir l'historique de retrait et consommation individuel du travailleur
• Identifier qui a scanné l'inventaire protégé
• Validation GPS montre où les matériaux ont été transférés

Meilleures Pratiques

Toujours Inclure une Raison pour les Ajustements :

• "Correction de comptage physique" est mieux qu'aucune raison
• "Matériaux endommagés jetés - événement tempête 2026-02-08" encore mieux
• Aide les auditeurs futurs à comprendre les corrections

Utiliser les Plus Petits Types de Transaction :

• Ne pas utiliser d'ajustements quand réception/transfert approprié
• Les ajustements devraient être exception, pas routine
• Réceptions/transferts préservent un contexte plus riche

Réconciliation Régulière :

• Hebdomadaire : Examiner les ajustements (devraient être rares)
• Mensuel : Comptage de cycle des articles de stock majeurs
• Trimestriel : Réconciliation complète d'entrepôt

Tirer Partie du GPS pour les Transferts :

• Examiner scanLocation pour l'inventaire protégé
• Détecter des anomalies (scan 100km de l'entrepôt)
• Validation de géofence empêche le partage QR distant

Surveiller le Volume de Transaction :

• Volume d'ajustement élevé = problèmes de processus
• Consommation faible avec retraits élevés = accumulation ou vol
• Écart réception/consommation = problèmes de prévision de demande

Permissions de Transaction

Créer des Transactions :

• transactionsCreate - Peut créer des réceptions, ajustements
• Les transactions auto-créées (depuis rapports, scans QR) ne nécessitent pas de permission
• Les permissions spécifiques au site peuvent limiter qui crée des réceptions à quels sites

Voir les Transactions :

• Tous les utilisateurs peuvent voir les transactions pour leurs propres éléments de stock
• Les restrictions de rôle peuvent masquer les transactions pour certaines ressources/sites
• viewDeleted permet de voir les transactions supprimées logiquement (si jamais implémenté)

Pas de Permission de Suppression :

• Les transactions ne peuvent pas être supprimées par quiconque
• Maintient l'intégrité de la piste d'audit
• Seulement l'administrateur de base de données pourrait supprimer (urgence opérationnelle seulement)