Assets & Maintenance

Périmètre : cycle de vie des équipements de la grande distribution alimentaire (réfrigérateurs, vitrines, chambres froides, fours, climatisation…) — entrée en stock, installation client, maintenance préventive/curative, pièces détachées, transport, reconditionnement, revente/recyclage. Inclut le référentiel marques/modèles/familles, les dépôts, le SAV public via QR code et la facturation de stockage par prestataire.

Vocabulaire & entités

Le schéma complet est dans docs/04-data-model.md §6.

Écrans

Modèle de données (points clés)

• Asset.currentLocationId : référence vers l'AssetLocation courante — mise à jour atomiquement à chaque mouvement.
• AssetLocation : chaque emplacement reçoit arrivedAt à la création et leftAt à la sortie (historique immuable).
• Asset.serviceShortCode : code 8 chars aléatoire (collision check), porté directement sur l'asset, sert de jeton public.
• États physiques AssetCondition et fonctionnels AssetFunctional : deux enums indépendants.
• MaintenanceOperation.slaDueAt : calculé à la création selon la priorité du contrat (J+4h critique, J+24h normal, J+5j basse).
• SparePartInstance : décrémentée du stock à la complétion de l'OT (pas à l'ajout de la ligne pièce).
• MTBF/MTTR : recalculés chaque nuit par job maintenance:mtbf-refresh (vue matérialisée par modèle).
• StorageMovementRequest (PENDING → CONFIRMED → VERIFIED) : gère le workflow WARM'UP ; génère atomiquement les AssetMovement à la vérification.

API

Permissions de base : assets.catalog:{read,manage}, assets.asset:{read,manage}, maintenance.operation:{read,manage}.

Exemple de référence d'endpoint :

{
  "maintenanceOperationId": "mop_…",
  "publicCode": "SAV-2026-04217",
  "trackingUrl": "https://qr.pulsegroup.fr/public/maintenance/SAV-2026-04217"
}

Workflows

Cycle de vie d'un asset

ACQUISITION (état NEW, localisation dépôt)
     │
  EN STOCK
     │  affectation contrat LLD / vente
     │
CHEZ LE CLIENT
   ├──→ MAINTENANCE (OT)  ──→ retour dépôt
   └──→ DEFAILLANT        ──→ RETOUR SAV
                                  │
                        RECONDITIONNEMENT
                         ├──→ REVENTE
                         └──→ RECYCLAGE

À chaque transition : audit log asset.state_changed, AssetMovement créé, AssetLocation.currentLocationId mis à jour, notifications éventuelles.

OT préventif (job quotidien)

1. maintenance-preventive 1×/j scanne les LeaseContract actifs avec clause de maintenance.
2. Calcule la prochaine échéance ; si J−30 sans OT planifié → crée MaintenanceOperation PLANNED PREVENTIVE.
3. Notification responsable SAV pour affectation technicien.

OT curatif

1. Client via QR → POST /api/public/asset/[shortCode]/report-issue → OT PLANNED CURATIVE.
2. Portail client /client/maintenance/new → idem.
3. Interne → création depuis fiche asset.
4. Notification responsable SAV → affectation technicien.
5. Technicien : IN_PROGRESS à l'arrivée, diagnostic + résolution + pièces + photos + signature client → DONE.
6. Rapport PDF généré, envoyé au client, archivé.
7. Si coût OT > seuil configuré par org → devis exigé avant intervention.

SLA & escalade

• slaDueAt calculé à la création selon priorité contractuelle (J+4h / J+24h / J+5j).
• J−1 du SLA sans IN_PROGRESS → notification urgence responsable SAV.
• Dépassement SLA → escalade direction + email d'excuse client.

Mouvement / transfert

• Localisation CUSTOMER_ESTABLISHMENT : exige un Establishment lié à un LeaseContract actif (sinon warning).
• Transfert inter-dépôts → génère automatiquement une TransportRequest TRANSFER.
• AssetLocation précédente reçoit leftAt, nouvelle créée avec arrivedAt.

QR code / Lien de service

• AssetServiceLink créé automatiquement à la création de l'asset ; shortCode 8 chars (collision check).
• publicUrl = https://qr.pulsegroup.fr/{shortCode} — QR PNG généré à la demande (cache 30j).
• Étiquette PDF générée par buildAssetLabelPdf (N° inventaire + lien + QR code).

Reconditionnement

• Retour dépôt fin de contrat → OT INSPECTION.
• Décision : REFURBISHED (ré-allouable) · RECYCLED (bordereau DEEE) · SOLD (sortie stock).

Règles métier

• N° inventaire unique par organisation. N° série unique par org s'il est renseigné.
• LOST / RECYCLED → asset non sélectionnable pour de nouveaux contrats.
• SOLD → asset en lecture seule (non modifiable).
• Suppression hard interdite si asset lié à un contrat ou une facture.
• MaintenanceOperation IN_PROGRESS non supprimable — annulation avec raison obligatoire.
• Pièces décrémentées à la complétion de l'OT, pas à l'ajout de la ligne pièce.
• Job nocturne : recalcul MTBF/MTTR par modèle (vue matérialisée).
• Workflow WARM'UP : StorageMovementRequest PENDING → CONFIRMED → VERIFIED ; génération atomique des AssetMovement à la vérification.

KPIs

Nombre d'assets par état · taux d'occupation par dépôt · MTBF/MTTR par modèle et par famille · taux de respect SLA SAV (% OT clos dans SLA) · coût moyen d'intervention par modèle · top 10 modèles les plus problématiques · volume mouvements par mois.

Notifications