## 1. Activation du mode coffee

Les fonctionnalites coffee sont optionnelles. Elles n'apparaissent que si l'option est activee dans la configuration trade.

1. Ouvrir la configuration du module trade.
2. Aller dans le bloc Trade options.
3. Cocher `Active coffee compatibility`.
4. Enregistrer.

Quand l'option est activee, les menus suivants deviennent disponibles sous Purchase et Sale :

Coffee / Samples Coffee / Lab Analyses Coffee / Cupping Sessions Coffee / Cupping Criteria

Quand l'option est desactivee, les menus Coffee et l'onglet Coffee Quality des lignes purchase/sale sont retires de la vue. Les clients non coffee ne voient donc pas les champs coffee.

## 2. Onglet Coffee Quality sur les lignes purchase/sale

Sur une ligne d'achat ou une ligne de vente, l'onglet Coffee Quality sert a definir le profil attendu du cafe et les seuils de controle.

Zone | Champs principaux | Utilisation
--- | --- | ---
Resume qualite | Coffee quality, Coffee origin, Coffee type, Coffee process | Identifier l'origine et le type de cafe visibles dans les process d'echantillon et de cupping.
Identite cafe | Variety, Crop year, Screen size | Completer les caracteristiques commerciales ou physiques du cafe cible.
Objectifs qualite | Moisture max %, Defects max, Cup score min | Definir les seuils utilises pour evaluer l'echantillon ou l'analyse labo.
Coffee samples | Liste des echantillons lies a la ligne | Creer ou consulter les echantillons rattaches au contrat d'achat ou de vente.

Le champ `Coffee quality` est calcule a partir des echantillons rattaches a la ligne. Il peut indiquer notamment : aucun echantillon, en attente, approuve, rejete, expire ou warning.

## 3. Gestion des echantillons

Un echantillon peut etre cree depuis l'onglet Coffee Quality d'une ligne, ou depuis le menu Coffee / Samples. Il peut etre lie a une ligne purchase ou sale, a un lot, a un labo et a des resultats de cupping.

### Informations a saisir

Champ | Role
--- | ---
Reference | Identifiant interne ou externe de l'echantillon.
Direction | Purchase ou Sale. Si l'echantillon est cree depuis une ligne, la direction est deduite.
Sample Type | Offer, Pre-shipment, Shipment, Arrival, Stock, Customer ou Retained.
Requested Date / Received Date | Suivi du cycle de vie. La date de demande est renseignee par defaut avec la date du jour.
Shelf life / Expiry Date | Duree de vie de l'echantillon. Par defaut : 90 jours. La date d'expiration est calculee automatiquement si elle n'est pas saisie.
Delegated to lab, Lab, Lab Due Date | Permet d'envoyer l'echantillon a un laboratoire et de suivre son delai.
Moisture, Screen size, Defects count | Resultats qualite saisis directement sur l'echantillon si l'analyse n'est pas deleguee.

### Cycle de vie de l'echantillon

Les boutons de workflow permettent de faire avancer l'echantillon :

Receive Send to lab Review Approve Reject Evaluate quality Expire Archive Reset

- `Receive` passe l'echantillon en recu et renseigne la date de reception si elle est vide.
- `Send to lab` marque l'echantillon comme delegue au labo et cree une analyse labo si un laboratoire est renseigne.
- `Review` passe l'echantillon en revue qualite.
- `Approve` ou `Reject` enregistrent la decision et la date de decision.
- `Evaluate quality` applique automatiquement la decision recommandee selon les seuils et resultats disponibles.
- `Expire` force l'etat expire, puis `Archive` permet de sortir l'echantillon du suivi actif.

### Filtres utiles

La liste des echantillons contient des domaines prets a l'emploi :

Pending Expiring soon Expired Approved All

Un echantillon est considere comme arrivant a expiration lorsque son expiry date est dans les 14 prochains jours. Un echantillon expire reste signale tant qu'il n'est pas archive ou rejete.

## 4. Analyses laboratoire

Les analyses labo servent a deleguer le controle d'un echantillon a un laboratoire externe ou interne. Elles sont accessibles depuis Coffee / Lab Analyses ou depuis l'echantillon.

### Creation

1. Ouvrir l'echantillon.
2. Renseigner le champ `Lab` et, si necessaire, `Lab Due Date`.
3. Cliquer sur `Send to lab`.

Le systeme cree une analyse labo active si aucune analyse active n'existe deja pour cet echantillon.

### Suivi de l'analyse

Bouton | Effet
--- | ---
Send | Renseigne la date d'envoi et marque l'echantillon comme delegue au laboratoire.
Receive | Renseigne la date de reception, puis place l'echantillon en revue qualite.
Accept / Reject | Valide ou rejette l'analyse labo.
Cancel / Draft | Annule ou remet l'analyse en brouillon.

Le champ `Compliant` est calcule en comparant les resultats labo aux seuils de la ligne coffee : moisture max, defects max et cup score min.

## 5. Sessions de cupping

Une session de cupping permet de preparer une degustation en aveugle avec plusieurs echantillons, plusieurs tasses par echantillon et plusieurs personnes degustatrices.

### Parametrer les criteres de cupping

Dans Coffee / Cupping Criteria, creer les criteres a noter : nom, sequence, type de critere, score maximum et indication si le score doit etre soustrait. Ces criteres sont utilises dans les lignes de resultat de cupping.

### Creer une session

1. Ouvrir Coffee / Cupping Sessions.
2. Creer une nouvelle session avec un nom, une date, un responsable et une salle.
3. Renseigner la capacite de la salle en nombre de tasses. Par defaut : 24.
4. Renseigner le nombre de tasses par echantillon. Par defaut : 3.
5. Ajouter les echantillons a deguster dans les lignes de session.

Les compteurs `Total cups` et `Remaining cups` indiquent le nombre de tasses prevues et la capacite restante.

### Preparer l'ordre et les codes aveugles

Le bouton `Prepare` controle la capacite de la salle, trie les echantillons et genere les tasses manquantes.

- L'ordre propose commence par les cafes les plus doux : arabica, puis blend/other, puis robusta.
- Le tri tient aussi compte de l'origine et de la reference echantillon.
- Chaque tasse recoit un code aveugle de type `S01-C1`, `S01-C2`, etc.
- Les degustateurs voient l'origine et le type de cafe, mais pas le contrat ni le fournisseur.

Si le nombre total de tasses depasse la capacite de la salle, le bouton Prepare bloque la preparation et affiche une erreur.

### Saisir les resultats

1. Passer la session en `Start`.
2. Ouvrir chaque tasse generee.
3. Ajouter un resultat par cupper/personne degustatrice.
4. Dans chaque resultat, saisir les lignes de criteres, les notes et cocher `Defect found` si un defaut est detecte.
5. Lorsque la session est terminee, utiliser `Done`.

Les scores moyens, le nombre de resultats et le nombre de defauts sont consolides au niveau de la tasse puis de l'echantillon de session.

## 6. Decisions qualite

La decision finale reste une decision utilisateur, mais le systeme calcule des indicateurs pour aider le responsable qualite ou origine.

Indicateur | Calcul / logique
--- | ---
Quality status | Compare les resultats disponibles aux seuils de la ligne. Un rejet de cupping entraine un fail. Une demande de re-cup entraine un warning.
Recommended decision | Pass = approve, fail = reject, warning = re-cup, sinon pending.
Cupping average score | Moyenne des scores consolides sur les resultats de cupping de l'echantillon.
Lab analysis status | Aucun, pending, received, accepted ou rejected selon la derniere analyse labo active.

Sur une ligne purchase ou sale, le statut Coffee Quality remonte une synthese de tous les echantillons de la ligne. Un echantillon rejete ou expire remonte donc directement sur la ligne.

## 7. Routine quotidienne recommandee

1. Consulter Coffee / Samples / Expiring soon pour traiter les echantillons proches de l'expiration.
2. Consulter Coffee / Samples / Pending pour suivre les echantillons demandes, recus, envoyes au labo ou en revue.
3. Verifier les analyses labo en attente dans Coffee / Lab Analyses.
4. Preparer les prochaines sessions dans Coffee / Cupping Sessions en respectant la capacite de la salle.
5. Apres cupping ou retour labo, utiliser `Evaluate quality` sur les echantillons pour proposer l'approbation, le rejet ou la re-degustation.

Le flux le plus simple est : creer l'echantillon depuis la ligne, recevoir l'echantillon, envoyer au labo ou en cupping, saisir les resultats, evaluer la qualite, puis approuver ou rejeter.

## 8. Points d'attention

- Le mode coffee doit etre active dans la configuration pour afficher les menus et l'onglet ligne.
- Les seuils qualite sont portes par la ligne purchase/sale. Sans seuil renseigne, la decision automatique reste en attente.
- Le bouton `Send to lab` cree une analyse seulement si un laboratoire est renseigne sur l'echantillon.
- Les informations visibles en cupping sont limitees a l'origine et au type de cafe pour conserver la logique de degustation en aveugle.
- Le responsable peut forcer une decision manuelle via Approve, Reject ou la decision de ligne de session, meme si les indicateurs servent d'aide.