# Champs Personnalises - Diagnostic Et Recuperation

Date : 2026-03-23

---

## Contexte

Un bug sur la sauvegarde des categories (`ModelType`) pouvait recreer des definitions de champs personnalises avec de nouveaux IDs.

Effet de bord :
- les `CustomFieldValue` existants restaient lies aux anciens `CustomField`
- puis etaient supprimes en cascade
- resultat visible : apres modification d'une categorie, certaines valeurs de champs perso disparaissaient

Le correctif preventif a ete fait :
- conservation des `id/customFieldId` cote frontend pour `PIECE/PRODUCT`
- matching backend plus robuste sur `id`, puis `orderIndex`, puis nom

Ce document couvre uniquement :
- comment detecter ce qui manque
- comment lire le listing
- comment identifier ce qui est recuperable depuis l'audit
- comment restaurer proprement

---

## Commandes Disponibles

### 1. Lister tous les champs perso manquants ou vides

Dans le conteneur :

```bash
php bin/console app:check-missing-custom-field-values
```

Variantes utiles :

```bash
php bin/console app:check-missing-custom-field-values --entity=piece
php bin/console app:check-missing-custom-field-values --entity=composant
php bin/console app:check-missing-custom-field-values --max-rows=1000
php bin/console app:check-missing-custom-field-values --limit=500 --max-rows=1000
```

### 2. Afficher uniquement les cas recuperables depuis l'audit

```bash
php bin/console app:check-missing-custom-field-values --recoverable-only
```

Variantes :

```bash
php bin/console app:check-missing-custom-field-values --entity=piece --recoverable-only
php bin/console app:check-missing-custom-field-values --entity=composant --recoverable-only
php bin/console app:check-missing-custom-field-values --recoverable-only --max-rows=1000
```

### 3. Dry-run de restauration pour une piece

```bash
php bin/console app:restore-piece-custom-field-values <pieceId>
```

Exemple :

```bash
php bin/console app:restore-piece-custom-field-values cl731386df55fcb9e6a01e0a63
```

### 4. Appliquer la restauration pour une piece

```bash
php bin/console app:restore-piece-custom-field-values <pieceId> --apply
```

---

## Colonnes Du Listing

La commande `app:check-missing-custom-field-values` affiche :

- `Entity` : `piece` ou `composant`
- `ID` : identifiant de l'entite
- `Name` : nom de l'entite
- `Reference` : reference metier si presente
- `Category` : nom de la categorie (`ModelType`)
- `Field` : nom du champ personnalise attendu par la categorie
- `Issue` : `missing` ou `empty`
- `Recoverable` : `yes` ou `no`
- `Audit value` : derniere valeur non vide retrouvee dans l'audit si disponible

---

## Signification Des Statuts

### `missing`

Il n'existe actuellement **aucune** ligne `CustomFieldValue` pour ce champ sur l'entite.

Cela peut vouloir dire :
- la valeur n'a jamais ete saisie
- la valeur a ete perdue lors du bug
- le champ a ete ajoute plus tard sur la categorie sans initialisation des anciennes entites

### `empty`

La ligne `CustomFieldValue` existe, mais sa valeur est vide.

Cela est plus suspect qu'un `missing`, mais ne prouve pas a lui seul une perte.

### `Recoverable = yes`

L'audit contient au moins une ancienne valeur non vide pour ce champ.

En pratique :
- c'est le signal le plus utile
- ce sont les cas a traiter en priorite
- ces cas sont potentiellement restaurables automatiquement

### `Recoverable = no`

L'audit de cette entite ne contient pas de valeur non vide exploitable pour ce champ.

Cela ne veut **pas** forcement dire qu'il n'y a jamais eu de valeur.
Cela veut simplement dire :
- rien de recuperable n'a ete trouve dans les logs d'audit consultes

---

## Lecture Des Cas Typiques

### Cas 1

```text
piece ... Roulement ... Diametre ... missing ... no
```

Interpretation :
- le champ `Diametre` est attendu sur cette piece
- aucune valeur n'existe actuellement
- l'audit ne permet pas de retrouver une ancienne valeur

Conclusion :
- non recuperable automatiquement
- a verifier metierement si la valeur a deja existe ou non

### Cas 2

```text
piece ... Arbre ... Diametre ... empty ... yes ... 35 mm
```

Interpretation :
- une ligne de valeur existe mais elle est vide
- l'audit montre qu'une ancienne valeur `35 mm` existait

Conclusion :
- cas typique de restauration automatique possible

### Cas 3

```text
piece ... Joint ... Matiere ... missing ... yes ... NBR
```

Interpretation :
- la valeur n'existe plus du tout
- l'audit permet de retrouver `NBR`

Conclusion :
- forte probabilite de perte historique
- recuperable automatiquement

---

## Priorisation Recommandee

Ordre de traitement conseille :

1. `empty + yes`
2. `missing + yes`
3. `empty + no`
4. `missing + no`

Pourquoi :
- les `yes` sont les seuls cas recuperables automatiquement
- les `empty` indiquent souvent une valeur ecrasee
- les `missing no` sont nombreux mais souvent ambigus

---

## Procedure Recommandee

### Etape 1 - Scanner globalement

```bash
php bin/console app:check-missing-custom-field-values --recoverable-only --max-rows=1000
```

### Etape 2 - Identifier les pieces prioritaires

Chercher :
- les pieces les plus critiques metierement
- les categories fortement touchees (`Roulement`, `Joint`, `Arbre`, etc.)
- les cas avec valeur d'audit explicite

### Etape 3 - Faire un dry-run piece par piece

```bash
php bin/console app:restore-piece-custom-field-values <pieceId>
```

### Etape 4 - Appliquer uniquement apres verification

```bash
php bin/console app:restore-piece-custom-field-values <pieceId> --apply
```

---

## Limites Actuelles

### Ce qui est pris en charge

- diagnostic global sur les `pieces`
- diagnostic global sur les `composants`
- restauration automatique ciblee sur les `pieces`

### Ce qui n'est pas encore automatise

- restauration automatique en masse
- restauration automatique des `composants`
- reconstitution si l'audit ne contient aucune ancienne valeur exploitable

---

## Interpretation Metier

Le listing global ne doit pas etre lu comme :

> "866 valeurs ont ete perdues"

Il doit etre lu comme :

> "866 couples entite/champ sont actuellement manquants ou vides par rapport aux definitions de categories"

Parmi eux :
- certains n'ont jamais ete renseignes
- certains ont probablement ete perdus
- seuls les cas `Recoverable = yes` sont candidates a une recuperation automatique fiable

---

## Commandes Resumees

```bash
# Tout lister
php bin/console app:check-missing-custom-field-values

# Afficher uniquement les cas recuperables
php bin/console app:check-missing-custom-field-values --recoverable-only

# Scanner seulement les pieces
php bin/console app:check-missing-custom-field-values --entity=piece --recoverable-only

# Scanner seulement les composants
php bin/console app:check-missing-custom-field-values --entity=composant --recoverable-only

# Dry-run de restauration d'une piece
php bin/console app:restore-piece-custom-field-values <pieceId>

# Application reelle
php bin/console app:restore-piece-custom-field-values <pieceId> --apply
```

