Etichette di tracciabilità

Quando un contenitore viene aperto o una preparazione viene fatta, il personale stampa un'etichetta e la applica: che cos'è, da dove viene, quando è stata aperta, entro quando va consumata. Sono le etichette secondarie di durata di conservazione, quelle che un ispettore rigira fra le mani, e questa collezione è il record di ciascuna di quelle stampate, con il file stampato stesso allegato.

Condivide l'involucro di snapshot: id, deleted, capturedAt, receivedAt, sequence e gli altri stanno attorno al data qui sotto.

traceability-labels

{
  "id": "0c6a4f2b-9e17-4d50-8b3c-1f7d5a2e9046",
  "collection": "traceability-labels",
  "deleted": false,
  "capturedAt": "1789786412903",
  "receivedAt": "1789786500117",
  "sequence": "2048",
  "data": {
    "timestamp": "1789786380000",
    "supplier": "Metro",
    "part": 1.5,
    "commentary": "Bac 3, ouvert ce matin",
    "groupId": "5e8b1c47-2a90-4f63-b1d8-6c04e7a3f215",
    "userId": "b3f7c1a0-5d42-4e88-9a16-7c0e2d4b9f31",
    "asset": {
      "objectKey": "restaurants/36eaa3fa/labels/c58d10b7e4a9",
      "status": "uploaded",
      "contentType": "image/jpeg",
      "byteLength": 48210,
      "sha256": "3c9e…"
    }
  }
}

supplier è un nome, non un riferimento. È testo, non l'id di un fornitore, e nulla tiene allineate le due cose: un fornitore rinominato nel catalogo non riscrive le etichette stampate il mese scorso. Lo usi pure per una corrispondenza se deve, ma consideri un riscontro una supposizione e un mancato riscontro la norma.

Il file

Ogni etichetta ne porta uno: data.asset dice che un file esiste, e i byte arrivano dall'endpoint degli asset.

GET /v1/restaurants/{restaurantId}/collections/traceability-labels/records/{recordId}/assets

Risponde con URL firmati validi per quindici minuti, ciascuno con la propria autorizzazione, così il download non richiede alcun header. Le regole complete (che aspetto ha la risposta, perché sha256 le permette di saltare un download, perché conserva i byte e non il collegamento) sono nella pagina sulle collezioni. Vale comunque la pena dire due cose qui.

asset descrive il file; solo l'endpoint glielo consegna. Porta objectKey, status, contentType, byteLength e sha256, ma nessun URL: un collegamento che non scadesse mai sarebbe una via d'accesso permanente e non autenticata ai record di un ristorante. Basi la logica su status: uploaded significa che i byte sono arrivati e sono stati verificati, pending significa che un dispositivo li sta ancora inviando, e un asset pending è assente dall'endpoint degli asset di proposito, non perché sia rotto.

Un'etichetta stampata non è necessariamente un'immagine. Legga il contentType che le dà l'endpoint degli asset anziché dare per scontata una fotografia, e non chiami tutto .jpg mentre lo acquisisce nel suo archivio.

Etichette stampate insieme

groupId è il campo che riporta un flusso di etichette a qualcosa che una persona riconoscerebbe. Quando il personale stampa un lotto (diverse etichette per diversi contenitori della stessa preparazione, in una volta sola), ogni etichetta di quel lotto porta lo stesso groupId. Ci raggruppi sopra prima di mostrare qualsiasi cosa: un lotto è un solo evento in una cronologia, non otto.

part è il campo di cui non possiamo ancora dirle il significato, e preferiamo dirlo apertamente piuttosto che farglielo indovinare male. È un numero decimale, non un contatore, il che esclude la lettura ovvia di «etichetta 3 di 8» e fa pensare a una porzione o a una quantità, ma niente nello schema lo afferma, quindi non faremo finta di saperlo. Lo porti avanti intatto, lo mostri grezzo se deve, e ce lo chieda se la sua integrazione ne dipende: la risposta è una conversazione con le persone che hanno costruito la schermata delle etichette.

Entrambi ammettono null. Un'etichetta stampata da sola può arrivare senza nessuno dei due, ed è un lotto di una sola etichetta anziché un record rotto: ripieghi sull'id dell'involucro e la mostri da sola.