# Contrat d'interface LGO ↔ simulateur

Ce document est **le** contrat qu'un LGO doit respecter pour être testé dans Pharmacy Simulator. Un LGO est un **plugin** : un module ES qui exporte un objet par défaut. Il ne parle au reste du jeu que par l'objet `host` qu'on lui donne. Tous les montants sont en **centimes entiers**, les dates en `AAAA-MM-JJ`, les heures en `HH:MM`.

## 1. Le plugin

```js
// src/lgo/<id>/index.js
export default {
  id: 'reference',                 // identifiant court, sert dans l'export des mesures
  nom: 'LGO de référence',
  version: '1.0.0',
  /** Appelé une fois au démarrage de la partie. */
  create({ host, donnees, root }) { return instance; },
};
```

- `donnees` : `{ produits, prescripteurs, organismes, tarifs, config, patients, pharmacie }`. `patients` est la **reprise de données** de l'ancien logiciel : uniquement les patients `connuDuLGO`, avec leur historique, ordonnances en cours, vaccinations, entretiens et refus. Le LGO en fait sa base initiale.
- `root` : élément DOM plein écran (vide, caché) dans lequel le LGO dessine son interface. L'hôte l'affiche et le cache.
- Le plugin est enregistré dans `src/lgo/registry.js` ; on le choisit avec `?lgo=<id>`.

### Instance

```js
instance = {
  /** Affiche l'interface pour un poste. Appelé quand le joueur interagit avec un poste dans le jeu. */
  open(contexte),
  /** L'hôte ferme la superposition (rare : l'utilisateur ferme normalement via host.fermer()). */
  close(),
  /** Début de journée : ouvrir la caisse (fond de caisse), récupérer les rejets (host.teletrans.retours()). */
  async ouvrirJournee({ date, fondCaisseCents }),
  /** Actions faites par un collègue non joueur avec le même LGO, sans interface. */
  collegue: {
    async envoyerCommande({ creneau }),        // 'midi' | 'soir' : envoie la proposition automatique au grossiste principal (repli sur le secours en cas de rupture)
    async receptionner({ livraisonId }),       // valide la réception d'une livraison grossiste
    async vendre({ produitId, qte }),          // le second pharmacien vend des boîtes à ses patients (comptoir 2) : le stock du LGO diminue
  },
  /** Sauvegarde et reprise (JSON sérialisable). */
  getState(),
  loadState(etat),
};
```

### Contexte d'ouverture

```js
contexte = {
  poste: 'comptoir' | 'backoffice' | 'bacs' | 'reserve' | 'salle-entretien' | 'salle-vaccination',
  mode: 'facturation' | 'commandes' | 'reception' | 'gestion' | 'entretien' | 'vaccination' | 'cloture',
  visite: null | {
    visiteId: 'J1-03',
    motifAnnonce: 'Bonjour, je viens pour mon renouvellement.',   // ce que dit le patient en arrivant
    service: null | { type: 'aod' | 'bpm' | 'vaccination', etape: 'aod-1' | 'aod-2' | 'aod-3' | 'bpm-recueil' | 'bpm-transmission' | 'bpm-suivi' | null },
    dialogue: null | [ { question, reponse } ],                    // en salle : le mini-dialogue qui vient d'avoir lieu dans le jeu
  },
  date: '2026-03-02', heure: '09:35',
}
```

Correspondance poste → mode par défaut : comptoir → `facturation` ; backoffice → `commandes` ; bacs → `reception` ; reserve → `gestion` ; salle-entretien → `entretien` ; salle-vaccination → `vaccination`. Le mode `cloture` est ouvert par l'hôte à 19:00 (ou quand le joueur la demande depuis un poste). Le LGO peut proposer la navigation vers ses autres modules depuis n'importe quel poste (sauf la facturation, qui suppose un patient au comptoir).

## 2. L'objet `host`

Toutes les méthodes asynchrones renvoient des promesses. Une méthode appelée hors de son contexte (ex. `comptoir.*` sans patient au comptoir) renvoie `null` ou lève une erreur explicite.

### Général

| Méthode | Rôle |
| --- | --- |
| `host.horloge()` | `{ date, heure, jour (0-5), nomJour }` — heure du jeu |
| `host.signalerEcran(nom)` | **Obligatoire** à chaque changement d'écran ou de module (`'facturation/identification'`, `'commandes/proposition'`…). Sert à compter les écrans traversés |
| `host.journal(type, details)` | Événements libres pour les mesures (ex. `'popup-affichee'`, `'controle-ignore'`) |
| `host.fermer()` | Ferme la superposition et rend la main au jeu |

### Comptoir (visite en cours)

| Méthode | Renvoie |
| --- | --- |
| `host.comptoir.lireCarteVitale()` | `CarteVitale` ou `null` si le patient n'a pas sa carte aujourd'hui (le jeu affiche sa réplique) |
| `host.comptoir.documents()` | `{ attestation: Attestation \| null, carteMutuelle: CarteMutuelle \| null, autres: [] }` : papiers posés sur le comptoir |
| `host.comptoir.scannerOrdonnance()` | `OrdonnanceScan` ou `null` si pas d'ordonnance |
| `host.comptoir.scannerProduits()` | `[ { produitId, cip13, qte } ]` : produits pris en rayon et posés sur le comptoir |
| `host.comptoir.demanderAuPatient(question)` | `Reponse` (déterminée par la graine) |
| `host.comptoir.encaisser({ montantCents })` | `{ mode: 'cb' \| 'especes', donneCents }` : le patient paie ; en espèces, `donneCents` est ce qu'il tend (billets) |
| `host.comptoir.soumettreFacture(facture)` | `{ ok }` : **chaque facture validée** (`FactureFinale`) doit être soumise ; l'hôte l'associe à la visite |
| `host.comptoir.terminerVisite(issue)` | Fin du passage au comptoir ; ferme la superposition. `issue = { resultat: 'servi' \| 'partiel' \| 'refuse' \| 'sans-achat', promis: [ { produitId, qte } ], serviceMaintenant: null \| { type, etape } }` |

`question` :
- `{ type: 'proposition', service: 'vaccin-capvaxive' | 'aod' | 'bpm' }` → `reponse` ∈ `'accepte' | 'plus-tard' | 'refuse' | 'refus-definitif'`, plus `dejaFaitAilleurs: { date } | null` pour un vaccin déjà fait ailleurs (le patient le déclare).
- `{ type: 'substitution', produitId, generiqueId }` → `'accepte' | 'refuse'`
- `{ type: 'promis', produitId, qte }` → `'accepte'` (repassera) | `'refuse'` (repart sans)
- `{ type: 'rendez-vous', service, propositions: [ { date, heure } ] }` → `'accepte'` + `choix: { date, heure }`

`Reponse = { reponse, texte, ...extras }` ; `texte` est la réplique du patient, affichée par le LGO.

### Salles

| Méthode | Renvoie |
| --- | --- |
| `host.salle.scannerVaccin()` | `{ produitId, cip13, lot, peremption }` du vaccin apporté par le joueur, ou `null` s'il ne l'a pas |
| `host.salle.terminer()` | Fin du service en salle ; le patient repart |

La facture d'un service est soumise avec `host.comptoir.soumettreFacture` (même méthode, la visite en cours est connue de l'hôte).

### Fournisseurs et livraisons

| Méthode | Renvoie |
| --- | --- |
| `host.pml.interroger(grossisteId, lignes)` | `ReponsePML` : disponibilités, à afficher avant validation |
| `host.pml.commander(grossisteId, lignes, { creneau })` | `{ commandeId, livraisonPrevue: { date, heure } }` ; les quantités livrées seront celles de la réponse PML |
| `host.direct.commander(fournisseurId, lignes)` | `{ commandeId, livraisonPrevue }` (A-Bas : J+2) |
| `host.livraisons.lister()` | `[ Livraison ]` arrivées et non réceptionnées |
| `host.livraisons.receptionner(livraisonId, lignesRecues)` | `{ ok }` : à appeler quand le LGO valide une réception (le rangement physique suit) |

`lignes = [ { produitId, qte } ]`.

### Télétransmission, agenda, caisse

| Méthode | Renvoie |
| --- | --- |
| `host.teletrans.envoyer(lots)` | `{ accuse: { nbLots, nbFactures, montantCents } }` |
| `host.teletrans.retours()` | `[ Rejet ]` nouveaux depuis le dernier appel (ils arrivent le lendemain matin) |
| `host.agenda.planifier({ visiteId?, patient: { nir, nom, prenom, naissance }, service, etape, date, heure })` | `{ ok, dateEffective, heureEffective }` : le monde fait revenir le patient (temps compressé) |
| `host.caisse.compterTiroir()` | `{ montantCents }` : comptage physique du tiroir-caisse |
| `host.cloture.terminerJournee({ caisse: { theoriqueCents, compteCents, ecartCents }, lotsEnvoyes })` | Fin de la clôture ; l'hôte affiche le bilan |

## 3. Types de données

```js
CarteVitale = { nir, nom, prenom, naissance, rang: 1, caisse, regime: 'standard' | 'ald', finDroitsAMO, amc: null | { numero, adherent, finDroits } }
Attestation = { type: 'attestation-droits', nir, nom, prenom, naissance, caisse, regime: 'standard' | 'ald' | 'aucun', ald: null | { libelle }, finDroitsAMO }
CarteMutuelle = { type: 'carte-mutuelle', numero, nomOrganisme, adherent, libelleContrat, finDroits, nom, prenom }

OrdonnanceScan = {
  scanId, imageSvg,                       // image de l'ordonnance (SVG en chaîne), à archiver avec la facture
  ocr: {                                  // pré-remplissage : peut contenir une erreur à repérer
    prescripteur: { texte, nom, prenom, profession, specialite, rpps, adresse },
    datePrescription,                     // ISO
    patient: { nom, prenom },
    renouvellements,                      // nombre lu (« à renouveler 2 fois » → 2)
    bizone,
    lignes: [ { texte, produitTexte, posologieTexte, unitesParJour, dureeJours, zone: 'ald' | 'hors', nonSubstituable, mentionNS } ],
  },
}

ReponsePML = { reponseId, grossisteId, lignes: [ { produitId, qteDemandee, qteDisponible, statut: 'ok' | 'partiel' | 'rupture' | 'non-reference' } ] }

Livraison = { livraisonId, source: 'grossiste-1' | 'grossiste-2' | 'a-bas', commandeId, arrivee: { date, heure },
              receptionManuelle: bool, bacs: [ { couleur: 'vert' | 'rouge', lignes: [ { produitId, qte } ] } ],
              lignes: [ { produitId, qteCommandee, qteLivree } ] }

Rejet = { rejetId, factureId, date, organisme: { type: 'AMO', code } | { type: 'AMC', numero },
          code, motif, montantTransmisCents }
// codes : 'NIR-INVALIDE', 'ASSURE-INCONNU', 'CAISSE-ERRONEE', 'MONTANT-AMO', 'DROITS-AMO-EXPIRES',
//         'AMC-INCONNUE', 'ADHERENT-INCONNU', 'MONTANT-AMC', 'DROITS-AMC-EXPIRES'
// Correction attendue : retransmettre la part avec le bon montant (ou 0 pour des droits expirés : la part passe à la charge du patient).

Lot = { lotId, date, destinataire: { type: 'AMO', code } | { type: 'AMC', numero },
        lignes: [ { factureId, nir, montantCents, correctionDe: null | rejetId } ], totalCents }
```

### `FactureFinale` (soumise à `host.comptoir.soumettreFacture`)

```js
{
  id: 'F-0001', date, heure, poste,
  type: 'ordonnance' | 'vente' | 'service',
  patient: null | { lgoId, nom, prenom, naissance, nir, caisse, regime: 'standard' | 'ald' | 'aucun',
                    amc: null | { numero, contrat: { PH7, PH4, PH2 } } },
  ordonnance: null | { prescripteurId, rpps, datePrescription, dateExecution, renouvellementsPrevus,
                       numeroDelivrance /* 1 = première délivrance */, ordonnanceRefId, scanId, bizone },
  lignes: [ { ligneId, produitId, cip13, qte /* boîtes facturées */, qtePromis /* dont promises */, prixUnitaireCents, montantCents,
              code /* PH7… */, zone: 'ald' | 'hors', tauxAMO, amoCents, tauxAMC, amcCents, patientCents, tva,
              substitution: null | { deProduitId, refusee }, nonSubstituable, origine: 'ordonnance' | 'rayon' } ],
  honoraires: [ { type: 'ordonnance' | 'conditionnement' | 'age', quantite, montantCents, amoCents, amcCents, patientCents } ],
  services: [ { type: 'vaccination-pharmacien' | 'vaccination-prescription' | 'entretien-aod' | 'bpm', etape, montantCents,
                amoCents, amcCents, patientCents, lot: null | string, produitId: null | string } ],
  totaux: { montantCents, amoCents, amcCents, patientCents, tva: [ { taux, baseHTCents, tvaCents } ] },
  tiersPayant: { amo: bool, amc: bool },
  paiement: { mode: 'cb' | 'especes' | 'aucun', montantCents, donneCents, renduCents },
  propositions: [ { type: 'vaccin-capvaxive' | 'aod' | 'bpm', reponse } ],      // pop-ups proposées pendant la visite
  controlesIgnores: [ code ],                                                   // contrôles affichés auxquels l'utilisateur est passé outre
}
```

## 4. Règles du jeu à respecter par un LGO

- Soumettre chaque facture validée, appeler `terminerVisite` à la fin du passage.
- Signaler chaque écran. Ne pas compter soi-même les clics.
- Ne jamais bloquer définitivement l'utilisateur : un contrôle peut être ignoré (il sera compté par l'arbitre s'il fallait le respecter).
- Les rejets arrivent le lendemain matin : les récupérer à l'ouverture de journée.
- Tout l'état du LGO doit être restituable par `getState()` / `loadState()`.

## 5. Écarts et extensions (hôte, `src/app/host.js`)

Tout ce qui précède est respecté ; cette section précise le comportement de l'hôte (corrections de `docs/critiques/05-code.md` et `00-qa-e2e.md`).

| Méthode | Comportement |
| --- | --- |
| `cloture.terminerJournee` | Lève une erreur explicite (message lisible) pendant un passage, ou avant 19 h tant qu'un patient est attendu. Autorisée hors de la phase de clôture (plus aucun patient attendu, ou après 19 h) : l'horloge passe à 19 h et un patient encore attendu est évalué « non servi ». Renvoie `{ ok: true }`. À 19 h, sans patient attendu, l'hôte passe de lui-même en clôture (le comptoir ouvre le mode `cloture`). |
| `pml.interroger(grossisteId, lignes, opts?)` | `opts.creneau` facultatif. Le créneau est calculé une fois (règle `src/shared/creneau.js` : midi jusqu'à 12:00 inclus), et la commande passée dans la même session le reprend : la disponibilité annoncée est celle livrée. Un « midi » demandé après 12:00 part avec la tournée du soir. |
| `pml.commander`, `direct.commander` | Renvoient seulement `{ commandeId, livraisonPrevue }`. |
| `livraisons.receptionner` | L'heure du jeu est transmise au monde : une livraison pas encore arrivée ou déjà réceptionnée est refusée, `{ ok: false, erreurs: [{ champ, message }] }`, et rien n'est enregistré. **Un LGO doit appeler l'hôte avant de créditer son propre stock.** |
| `comptoir.encaisser` | Renvoie aussi `mode: 'aucun'` pour un montant nul. Les espèces réellement tendues entrent dans le tiroir physique. |
| `comptoir.soumettreFacture` | Renvoie `{ ok, factureId }` ; une facture déjà soumise (même `id`) est ignorée (`doublon: true`). La monnaie rendue déclarée sort du tiroir. |
| `caisse.compterTiroir` | Comptage physique tenu par le monde : fond + espèces réellement tendues − monnaie rendue. Un montant reçu mal saisi dans le LGO produit un écart de caisse. |
| `salle.scannerVaccin` | Lit le vaccin tenu en main sans le consommer ; on peut rescanner. Le vaccin n'est administré qu'à `salle.terminer`, si une vaccination a été facturée pendant le passage. |
| `agenda.planifier` | Le patient est retrouvé d'après l'identité transmise (NIR, sinon nom et date de naissance). Si ce n'est pas le patient de la visite, le rendez-vous est pris pour la fiche désignée, et l'écart est journalisé (entrée `rdv` avec `ecartIdentite`, événement de mesure `rdv-autre-patient`). |
| `teletrans.envoyer` | Attend la réponse du monde (oracle éventuellement asynchrone) ; l'accusé contient aussi `date` et `retoursLe`. |
