AccediPrenota un briefing

Capitolo 2.24

Costruire una soluzione verticale personalizzata end-to-end

Un esempio pratico di creazione del pacchetto di dominio Catena del freddo, dal brief iniziale fino a una release attiva per ogni unità, con il relativo modello di conoscenza, le viste, una skill, un plugin full-service e dati di esempio. A seguire, come estendere un pacchetto già esistente e come aggiungere una vista a uno già rilasciato.

Questa pagina è stata tradotta dall'IA a partire dall'originale in inglese. In caso di dubbi, fa fede la pagina in inglese. Legga questa pagina in inglese

19 minuti di lettura

Mi chiamo Mateo Ruiz e sono uno sviluppatore presso Corrán Orbital. La maggior parte della mia settimana è dedicata al nostro software per il carico utile, ma questo capitolo riguarda un lavoro svolto per un cliente. Larkfield & Vane assicura merci, di cui una quota crescente viaggia in container refrigerati. Quando un container refrigerato perde l'alimentazione da terra in banchina, la temperatura sale, il carico si deteriora e settimane dopo segue una richiesta di risarcimento. Larkfield voleva che il proprio personale vedesse questa catena come un tutt'uno in Nexus, dal guasto elettrico alla richiesta di risarcimento, e che ogni ruolo visualizzasse solo la parte di propria competenza. Da qui è nato il pacchetto Cold chain.

Ciò che segue è la realizzazione nell'ordine in cui l'abbiamo eseguita, con le schermate, i file e i comandi. Ho mantenuto gli errori commessi, perché due dei rifiuti in cui siamo incappati ci hanno insegnato molto di più sulla piattaforma rispetto al percorso senza intoppi. Il materiale di riferimento si trova nei capitoli precedenti a questo, a cui rimando senza ripeterne il contenuto. Quelli su cui mi sono basato maggiormente sono stati il capitolo 2.18, Il modello di estensione, e il capitolo 2.23, Pacchetti di dominio, tenendo aperto accanto ad essi il capitolo 2.21, Il Plugin SDK, per il kit di sviluppo software vero e proprio.

Un percorso da sinistra a destra composto da otto riquadri: "Brief", "Percorso standard", "Modello di conoscenza", "Lenti", "Skill e plugin", "Dati di esempio e anteprima", "Revisione del rilascio", "Promozione". Sotto l'ultimo riquadro, una seconda riga di quattro riquadri più piccoli uniti da frecce mostra le fasi di promozione: "Spazio di sviluppo", "Staging", "Unità pilota (Rotterdam)", "Tutte le unità", con l'icona di un lucchetto su ciascuna freccia etichettata "gate". Una freccia tratteggiata che va direttamente da "Spazio di sviluppo" a "Tutte le unità" è barrata ed etichettata GATE_CANNOT_BE_SKIPPED.
La realizzazione di Cold chain, dalle specifiche a ogni singola unità.

Il brief e chi fa cosa

Larkfield mi ha assegnato una postazione da sviluppatore nella propria organizzazione per tutta la durata del progetto. Questo aspetto è importante, perché un pacchetto privato per un singolo cliente viene realizzato all'interno dell'installazione di quel cliente, nei suoi spazi di sviluppo e nei suoi rami di dati, con l'approvazione del suo personale. Un pacchetto destinato a molti clienti viene realizzato in modo diverso, su un cluster dell'editore con soli dati di esempio; il capitolo 2.25, Realizzare per ciascuna edizione, tratta proprio questo caso.

Le specifiche stavano in una sola pagina:

  • Container refrigerati in banchina e sulle navi: la loro alimentazione, le escursioni termiche e le richieste di risarcimento che ne conseguono.
  • Due ruoli per iniziare: un tecnico dei container refrigerati in banchina e un responsabile della catena del freddo in ufficio.
  • Un progetto pilota attivo prima nell'unità di Rotterdam e successivamente esteso a Felixstowe.
  • Prove di conformità per tre serie di normative: l'accordo ATP per le derrate deperibili, le buone pratiche di distribuzione dell'UE per i medicinali e i registri di sicurezza alimentare previsti dall'HACCP (analisi dei pericoli e punti critici di controllo). Le richieste di risarcimento ai sensi delle regole dell'Aia-Visby utilizzano gli stessi registri delle escursioni termiche, pertanto le abbiamo annotate per la fase successiva al progetto pilota.

I pacchetti di dominio sono una funzionalità dell'edizione Enterprise. Larkfield utilizza Enterprise, quindi il percorso per il pacchetto di dominio mi era accessibile. Sull'edizione Community, il percorso guidato per la creazione di un pacchetto non è previsto.

Partire dal percorso ottimale

Tutto inizia nella pagina Inizia qualcosa di nuovo. Offre sei percorsi guidati: plugin, pacchetto di dominio, vista, piattaforma, competenza e flusso di lavoro. Ciascuno crea un repository da un modello versionato, un manifesto che dichiara i requisiti dell'elemento, i test, uno spazio di sviluppo e i rami di dati. Gli stessi percorsi funzionano nella console, da riga di comando e dal proprio IDE (ambiente di sviluppo integrato), dove lo strumento Workbench nexus.create svolge lo stesso lavoro attraverso un piano da confermare preventivamente.

Inizia qualcosa di nuovo
Inizia qualcosa di nuovo
I sei percorsi guidati, ciascuno con ciò che genera, il relativo comando nexus create e il modello associato a versione fissa. Si noti l'avviso in calce: il manifesto è vincolante, non consultivo, e un rilascio che richiede autorizzazioni aggiuntive viene bloccato finché non viene esaminato da due persone.

Da quella pagina abbiamo scelto il percorso del pacchetto di dominio, chiamando il pacchetto cold-chain e la sua prima unità Rotterdam. Il risultato indica il modello a versione fissa, domain-pack@1.6.0, ed elenca ciò che ha generato: il repository, un manifesto che dichiara quattro ambiti, due archivi e nessun indirizzo in uscita, 66 test derivati dal modello, uno spazio di sviluppo a Rotterdam, tre rami di dati sintetici e una voce in bozza nel catalogo interno di Larkfield visibile solo a me. La versione del modello è bloccata e un suo eventuale aggiornamento successivo si presenta come una modifica soggetta a revisione al pari di qualsiasi altra, cosicché il pacchetto di nessuno subisca variazioni impreviste a causa della modifica di un modello. Per il nostro primo pacchetto ho comunque utilizzato la procedura guidata della console, poiché mostra il piano prima di generare qualsiasi elemento.

Passaggio 1: definire lo scopo del pacchetto

La procedura guidata Nuovo pacchetto di dominio si articola in tre passaggi: informazioni generali, modello di conoscenza, revisione e creazione. Il passaggio 1 richiede le poche informazioni che determineranno tutto il resto.

Campo Dati inseriti Nota
Nome Catena del freddo Utilizzato per il repository e il catalogo
Scopo Container refrigerati in banchina e sulle navi: alimentazione, escursioni termiche e richieste di risarcimento che ne conseguono
Settore Logistica e settore marittimo Si basa sul pacchetto Logistica e settore marittimo
Proprietario Autore della creazione Bloccato nella procedura guidata
Unità Rotterdam (pilota) Felixstowe dopo il progetto pilota
Modello domain-pack@1.6.0 Bloccato; gli aggiornamenti vengono ricevuti come modifiche soggette a revisione
Normative mappate Accordo ATP, buone pratiche di distribuzione dell'UE, registri di sicurezza alimentare Ogni normativa diventa una pagina nella mappa delle prove di conformità del pacchetto

L'assistente nel pannello laterale ha suggerito l'ultima riga, inclusa l'osservazione che le richieste di risarcimento merci riutilizzano gli stessi registri delle escursioni termiche. Un avviso in fondo alla pagina segnala che non è ancora stato creato nulla. Il repository, lo spazio di sviluppo e i rami di dati vengono generati solo quando si preme Crea al passaggio 3, dopo aver preso visione del piano. È possibile salvare una bozza e riprendere in seguito.

Passaggio 2: il modello di conoscenza

Il modello di conoscenza è l'insieme dei tipi di entità che il pacchetto conosce e del modo in cui sono collegati. Cold chain è partito dal modello di base per la logistica, logistics-base 4.2, importato dall'SDK, che ci ha fornito cinque tipi di base su cui lavorare (Vessel, Port, Container, Carrier e Shipment). I tipi di base sono di sola lettura nella procedura guidata. Se è necessario modificarne uno, la modifica avviene nel pacchetto che ne è proprietario.

Abbiamo aggiunto cinque tipi personalizzati:

Tipo Cos'è Proprietà
Unità reefer Un container refrigerato 9
Scalo della nave Una nave presso un ormeggio 6
Escursione termica Una temperatura fuori dai limiti consentiti 8
Alimentazione elettrica Un punto di alimentazione a terra o a bordo 4
Rivendicare Importo richiesto per merce deteriorata 7
Nuovo pacchetto di dominio: modello di conoscenza
Nuovo pacchetto di dominio: modello di conoscenza
Il grafo di conoscenza con cinque tipi di base e cinque nuovi. Si osservino le proprietà di Excursion sulla destra: a ogni proprietà viene associata la relativa classe al momento della creazione e l'avviso indica che gli importi delle richieste di risarcimento sono dati commerciali, pertanto le viste destinate ai tecnici non possono mostrarli.

Ogni proprietà viene classificata al momento della creazione. "Reported by" (Segnalato da) su un elemento Excursion è un dato personale. "Cargo value at risk" (Valore del carico a rischio) così come l'importo e la liquidazione di una richiesta di risarcimento sono dati commerciali. Il primo giorno questa operazione ci è sembrata pura burocrazia, ma in seguito ci ha salvato in due occasioni, poiché le classi stabiliscono ciò che una vista può mostrare, ciò che una copia mascherata sostituisce e ciò che una riga di registro nasconde.

Due delle nostre relazioni si collegano al modello di base: un elemento Reefer unit è collegato a un elemento Power supply e un elemento Claim fa riferimento a un elemento Shipment. Il modello di base in sé non viene modificato. Una proprietà ritirata rimane nella versione 1.0 del modello e viene rimossa solo in una versione successiva, in modo che nessun dato valido nei vecchi record cessi di essere leggibile.

Passaggio 3: revisione e creazione

Il passaggio 3 rappresenta il piano. Elenca ciò che verrà creato, gli ambiti che il manifesto dichiarerà, i rami di dati e lo spazio di sviluppo. Una volta confermato il piano con la propria passkey, al piano viene associata un'impronta digitale. La creazione segue quindi il piano esattamente, un passaggio alla volta, ed è possibile interrompere il processo a qualsiasi passaggio mantenendo ciò che è già stato generato.

Il piano per Cold chain dichiarava quattro ambiti:

Ambito Perché è necessario al pacchetto
Lettura della telemetria dei container refrigerati Letture di alimentazione e temperatura
Scrittura delle escursioni termiche Registra un'escursione termica al superamento dei limiti
Lettura delle spedizioni Collega una richiesta di risarcimento alla relativa spedizione
Bozza delle note di richiesta di risarcimento Solo bozze; l'invio è effettuato da una persona

I suoi archivi erano il grafo e i record. Non aveva indirizzi in uscita e utilizzava il profilo sandbox Standard. Lo spazio di sviluppo era dotato di 4 core, 16 GiB di memoria e 50 GiB di spazio di archiviazione, una rete chiusa a eccezione di quanto dichiarato nel manifesto, solo immagini firmate e una scadenza fissata dopo 7 giorni di inattività. Alla scadenza, la sua definizione rimane nel repository, da cui è possibile ricrearlo.

I tre rami di dati provenivano dal generatore sintetico. Non è stato copiato alcun dato dei clienti. Una copia mascherata di Rotterdam richiede il consenso del proprietario dei dati, che in Larkfield è Priya Natarajan, da richiedere separatamente.

Il manifest del pacchetto

Il repository contiene il manifesto del pacchetto, pack.json. Indica il nome del pacchetto, la versione, l'eventuale pacchetto da cui eredita, i suoi cluster e i suoi termini. Un cluster può essere una vista, ovvero ciò che un singolo ruolo visualizza all'interno del pacchetto, oppure condiviso, attivo quindi su tutte le viste. Ecco il nucleo del nostro:

{
  "id": "cold-chain",
  "name": "Cold chain",
  "version": "0.4.0",
  "clusters": [
    {
      "id": "CC01",
      "kind": "lens",
      "name": "Reefer technician",
      "seats": "Technicians on the quay",
      "purpose": "Which reefers have lost power or warmed up, and what to do next.",
      "lexicon": ["cold"],
      "menu": [],
      "screens": []
    },
    {
      "id": "CC02",
      "kind": "lens",
      "name": "Cold-chain controller",
      "seats": "Controllers in the operations office",
      "purpose": "Every excursion from first reading to closed claim, with its evidence.",
      "lexicon": ["cold"],
      "menu": [],
      "screens": []
    }
  ],
  "lexicon": {
    "core": [],
    "cold": [
      ["excursion", "a time when the temperature left its limits", ""],
      ["set point", "the temperature a reefer is told to hold", ""],
      ["shore power", "electricity from the quay rather than the ship", ""]
    ]
  }
}

Il lessico contiene i termini specifici del pacchetto accompagnati da una spiegazione semplice per ciascuno, abbastanza breve da poter essere letta sullo schermo di un telefono.

Accanto a pack.json, il manifesto dichiara anche a cosa può accedere il pacchetto: ambiti, archivi, indirizzi in uscita e profilo sandbox. Nexus concede esattamente quanto indicato e nulla di più. Ogni chiamata agli strumenti viene verificata rispetto agli ambiti dichiarati e qualsiasi indirizzo esterno viene bloccato a meno che non sia in elenco. È possibile consultare la dichiarazione e le differenze rispetto all'ultimo rilascio nella pagina Manifesto e autorizzazioni del pacchetto.

Viste: cosa vede ciascun ruolo

Una vista può solo restringere ciò che la sua vista di base mostra, e questa singola regola ha plasmato la nostra progettazione più di qualsiasi altra. Una vista mostra una parte di ciò che mostra la sua vista di base, mentre le autorizzazioni continuano a dipendere dai ruoli: una vista stabilisce ciò che un ruolo vede nel pacchetto, non ciò che è autorizzato a fare.

La vista Tecnico container refrigerati restringe la vista Responsabile operativo, ovvero la vista di base che Larkfield utilizza già per le attività logistiche. Nel Generatore di viste si selezionano le schede, i campi e le azioni che la vista deve mostrare. Gli elementi che la vista di base non mostra risultano bloccati.

Componente La vista Tecnico container refrigerati mostra Esclusi
Schede Unità refrigerate in banchina, escursioni termiche aperte, punti di alimentazione, scali navali odierni Qualsiasi informazione sulle richieste di risarcimento
Campi Stato dell'alimentazione, punto di regolazione, ultima lettura, temperatura massima Importo della richiesta di risarcimento (non presente nella vista di base), campi personali (disattivati per impostazione predefinita)
Azioni Registrare la causa di un'escursione termica, richiedere una verifica dell'alimentazione Modificare un punto di regolazione e chiudere un'escursione termica (solo responsabili), preparare la bozza di una nota di richiesta di risarcimento
Generatore di lenti
Generatore di lenti
Il Generatore di viste per Tecnico container refrigerati, con le selezioni effettuate rispetto alla vista di base. L'avviso in basso a sinistra mostra il rifiuto restituito quando si tenta di selezionare l'importo della richiesta di risarcimento: la vista di base non lo mostra, pertanto nemmeno questa vista può farlo.

Ho provato comunque ad aggiungere l'importo della richiesta di risarcimento alla vista del tecnico, perché me lo aveva chiesto un tecnico. Il generatore ha opposto un rifiuto restituendo LENS_CANNOT_WIDEN e non ha salvato nulla. Non esiste alcun espediente all'interno della vista: l'unica soluzione consiste nel creare una vista basata su una vista di base più ampia, il che comporta una richiesta diversa soggetta alla decisione dell'amministratore dell'organizzazione. Abbiamo deciso di omettere il dato.

Nascondere un elemento in una vista non lo rimuove da Nexus. Significa semplicemente che quel ruolo non lo visualizza. Il generatore indica quante persone saranno interessate dalla vista nel progetto pilota (29, nel nostro caso) e mantiene un registro di ogni operazione di Aggiunta, Modifica e Ritiro. Una vista viene definita una sola volta per l'organizzazione e assegnata per singola unità a un ruolo della piattaforma; in questo modo, la stessa vista Tecnico container refrigerati può essere assegnata ai tecnici di Rotterdam questo mese e a quelli di Felixstowe il mese prossimo.

Una skill per la stesura di note di reclamo

I responsabili desideravano una prima bozza della nota da inviare al proprietario del carico dopo un'escursione termica. Trattandosi di elaborazione del linguaggio, l'operazione viene eseguita da un modello; il punto era stabilire dove collocarla.

Esistono due tipi di competenze in Nexus, e in questo caso la differenza è sostanziale. Una competenza da manifesto è una riga tipizzata nel file skills[] di un plugin, smistata dalla piattaforma. Una competenza dello Skills Engine è un pacchetto SKILL.md presente nella libreria delle competenze dell'organizzazione, che agenti, pulsanti di IA (intelligenza artificiale), flussi di lavoro e strumenti per sviluppatori eseguono tutti allo stesso modo. Il capitolo 2.20, Competenze, tratta entrambi i tipi.

Il livello di attendibilità del nostro plugin è community e un plugin community può dichiarare solo competenze da manifesto che non accedono a un modello (host_callback e plugin_queue). I due livelli che accedono all'AI Provider Router, tool_using e llm_only, richiedono il livello di attendibilità core o verified. Pertanto, la stesura delle bozze per le note di richiesta di risarcimento è diventata una competenza dello Skills Engine, ed è il router a selezionare il modello dal pool interno di Larkfield:

---
name: draft-claim-note
description: Draft a note to a cargo owner about one reefer excursion, from the excursion record and its readings. Drafts only; a person reviews and sends.
allowed-tools: Read, Grep
triggers:
  - /draft-claim-note
capabilities:
  - name: draft_note
    description: Write a first draft for one excursion
version: 1.0.0
---

# Draft a claim note

Use this when a controller asks for a note about one excursion.

## Steps

1. Read the excursion: unit, start, length, highest temperature and cause.
2. Read the shipment it belongs to, for the cargo owner's name.
3. Write four short paragraphs: what happened, when, what the readings show, what happens next.
4. Never state a claim amount. Never send anything.

Il pacchetto risiede in skills/draft-claim-note/ all'interno del repository, in una cartella il cui nome corrisponde al nome della competenza. Lo abbiamo convalidato e caricato dal terminale:

npm run skill:validate skills/draft-claim-note
npm run skill:upload skills/draft-claim-note --dry-run
npm run skill:upload skills/draft-claim-note

Il caricamento dello stesso contenuto per due volte restituisce la versione esistente anziché crearne una nuova (CONTENT_HASH_ALREADY_PUBLISHED), pertanto ripetere l'operazione di caricamento è sicuro. Prima che una versione venga pubblicata, lo Skills Engine esegue i relativi casi di test, una prova in modalità shadow su attività passate e una revisione cieca da parte di un modello di un'altra azienda, registrando tempi e costi di ciascuna esecuzione.

Il plugin full-service

Il pacchetto necessitava inoltre di codice sempre attivo: un lettore per il flusso di telemetria dei container refrigerati e uno scrittore che aprisse un record di escursione termica qualora una lettura superasse i limiti previsti. Un codice di questo tipo appartiene a un plugin a servizio completo; ne abbiamo generato la struttura di base con l'apposito comando dell'SDK, che crea l'intero albero di riferimento sostituendo il nome:

npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold cold-chain --tier full-service
cd cold-chain
npm install
npm ci
npm run typecheck && npm test && npm run build
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test

L'SDK si installa da https://registry.adverant.ai/npm/ utilizzando il token di pull reperibile nella pagina Token di pull e comandi di installazione del proprio account Adverant. È necessario eseguire il commit del file package-lock.json generato dalla prima installazione; la creazione dell'immagine esegue npm ci e viene rifiutata se tale file è assente.

Ecco la parte del nostro nexus.manifest.json che differisce dal modello. Non si tratta dell'intero file: i blocchi description, author, license, runtime, backend e frontend della struttura di base rimangono invariati, poiché il validatore rifiuta il manifesto di un servizio completo che ne sia privo. Le tre frasi architecture costituiscono la regola che ogni plugin deve ribadire, e il validatore ne controlla l'esatta formulazione. Nella prima frase, UNO indica il motore del flusso di lavoro:

{
  "manifestVersion": "2",
  "name": "cold-chain",
  "displayName": "Cold chain",
  "version": "0.4.0",
  "tier": "full-service",
  "trust": "community",
  "architecture": {
    "compute": "All compute runs via UNO dispatch (nexus-orchestrator /api/v1/dispatch + nexus-workflows). No direct engine, queue or model-provider calls from plugin code.",
    "ai": "All AI goes through the AI Provider Router, which alone owns the credential and the final provider/model decision. This plugin holds no model credentials.",
    "deploy": "Deploy is through the installation's release channels only."
  },
  "api": {
    "version": "1",
    "basePath": "/",
    "endpoints": [
      { "method": "GET", "path": "/health", "summary": "Liveness", "auth": "public", "allowAnonymous": true },
      { "method": "GET", "path": "/api/excursions", "summary": "List the unit's excursions", "auth": "scope", "right": "excursion.read", "needsUnit": true },
      { "method": "POST", "path": "/api/excursions", "summary": "Record an excursion", "auth": "scope", "right": "excursion.create", "needsUnit": true },
      { "method": "POST", "path": "/internal/skills/excursion_open", "summary": "host_callback receiver the platform POSTs to", "auth": "internal" }
    ]
  },
  "rights": {
    "excursion.read": { "summary": "Read the unit's excursions.", "roles": ["owner", "admin", "member", "viewer"] },
    "excursion.create": { "summary": "Record an excursion.", "roles": ["owner", "admin", "member"] }
  },
  "skills": [
    {
      "id": "excursion_open",
      "displayName": "Open an excursion",
      "description": "Open an excursion record when a reading breaks its set point limits. No model; runs in the plugin's own backend.",
      "tier": "host_callback",
      "classification": "tenant",
      "dataResidency": "eu",
      "inputSchema": { "type": "object", "properties": { "readingId": { "type": "string" } }, "required": ["readingId"] },
      "outputSchema": { "type": "object", "properties": { "opened": { "type": "boolean" } }, "required": ["opened"] },
      "hostCallback": {
        "service": "cold-chain",
        "port": 8080,
        "path": "/internal/skills/excursion_open",
        "maxRequestBytes": 65536,
        "maxResponseBytes": 16384,
        "tenantHeader": "X-Organization-ID"
      },
      "timeoutMs": 10000
    }
  ],
  "changePolicy": {
    "enabled": true,
    "classes": ["website", "bff", "migration"],
    "approvals": { "website": 1, "bff": 1, "migration": 2 }
  }
}

excursion_open è una competenza da manifesto con livello host_callback: la piattaforma invia l'input al nostro Service, all'interno del nostro namespace, e mai a un host da noi indicato. La rotta di ricezione è dichiarata auth: internal ed è protetta con serviceMiddleware dell'SDK, la variante Express della protezione, che rifiuta qualsiasi token di chiamata emesso per altri plugin, organizzazioni, competenze o rotte. Il suo classification è tenant, che rappresenta il limite massimo per un plugin community. Il capitolo 2.27, Scenari di realizzazione, illustra nel dettaglio una competenza host_callback a sé stante.

Due buone abitudini adottate in questa fase meritano di essere replicate. Ogni tabella include organization_id, owner_user_id e business_unit_id fin dalla prima migrazione, poiché l'aggiunta successiva di un asse comporta una migrazione su righe attive. Inoltre, abbiamo eseguito nexus-gates in locale prima di ogni push, trattandosi dello stesso comando eseguito dalla pipeline; un'esecuzione che non ha esaminato nulla termina con codice di uscita 2 e lo segnala esplicitamente. Il capitolo 2.19, Le regole che ogni estensione eredita, elenca i controlli di sbarramento.

Dati di esempio per i test

La pagina Dati di esempio per i test offre tre tipi di ramo:

Tipo Contenuto Chi deve approvare
Sintetico Dati generati in base a conteggi e strutture impostati dall'utente; nessun dato proviene da un'unità reale Nessuno; appartiene all'utente
Copia mascherata Una copia di un'unità in cui i campi personali, sensibili e commerciali sono stati sostituiti Il proprietario dei dati (Priya Natarajan per Rotterdam)
Solo schema La struttura degli archivi, senza alcuna riga Nessuno; destinato alle migrazioni

Abbiamo generato una settimana di intenso lavoro: circa 7 escursioni termiche ogni 100 container refrigerati, che corrisponde a un tipico mese di agosto ad alto traffico a Rotterdam. I casi anomali contavano più del volume. Abbiamo richiesto un'interruzione di corrente durante lo scarico, un portellone lasciato aperto, un'interruzione dei dati del sensore e due richieste di risarcimento per una singola escursione termica. La pagina può suggerire casi anomali attingendo alle cause di escursione termica presenti nel modello di conoscenza, mai da record reali.

Ogni serie di conteggi e strutture viene salvata come seed, ad esempio cold-chain-busy-01, con la relativa impronta digitale. Lo stesso seed produce gli stessi dati, cosicché ogni esecuzione di test su qualsiasi ramo analizza esattamente la medesima settimana. È questo che ha reso ripetibili i nostri 66 test.

Un ramo rimane attivo per 72 ore per impostazione predefinita e per un massimo di 14 giorni. Durante una lunga revisione ho chiesto di mantenere attivo il nostro ramo ad alto traffico per 30 giorni, ma la pagina ha opposto un rifiuto restituendo BRANCH_LIFE_EXCEEDED. La soluzione è quella suggerita dall'avviso stesso: conservare il seed e generare da esso un nuovo ramo quando necessario. Una copia mascherata rispetta gli stessi limiti e la relativa richiesta deve indicare una motivazione e una durata massima di 14 giorni.

Visualizzare l'anteprima di una vista come utente specifico

Prima che chiunque a Rotterdam vedesse Cold chain, lo abbiamo esaminato esattamente dal loro punto di vista. La funzione Anteprima di una vista come utente restituisce il pacchetto esattamente come lo visualizza il ruolo selezionato, su un ramo di dati, all'interno di una cornice di anteprima tratteggiata.

Anteprima di una vista come utente
Visualizzare l'anteprima di una vista come utente specifico
Cold chain come lo vede un tecnico dei container refrigerati di Rotterdam, su un ramo sintetico. Si noti la colonna delle richieste di risarcimento contrassegnata come "nascosto dalla vista" su ciascuna escursione termica aperta, nonché il pannello laterale che spiega cosa nasconde questa vista e perché.

Tre regole rendono le anteprime sicure da usare liberamente. Un'anteprima utilizza un ramo di dati, mai l'unità di produzione. Le autorizzazioni personali dell'utente non vi confluiscono, per cui si visualizza ciò che vede il ruolo e non ciò che si è autorizzati a vedere personalmente. Inoltre, la sessione termina dopo 30 minuti.Il tentativo di puntare un'anteprima a un'unità di produzione viene rifiutato con il codice CONNECTION_SCOPE_EXCEEDED; se occorrono strutture di dati reali, è necessario richiedere una copia mascherata al proprietario dei dati ed eseguire l'anteprima su quest'ultima.

È proprio durante l'anteprima che abbiamo individuato un vero errore. Il grafico della temperatura nella vista del tecnico mostrava il punto di regolazione, ma le modifiche al punto di regolazione dovevano essere riservate ai soli responsabili. Il grafico in sé andava bene; il pulsante di modifica posto sotto di esso, invece, no. La versione 0.3.2 ha nascosto le modifiche del punto di regolazione ai tecnici, ed è stato grazie all'anteprima che ce ne siamo accorti.

Modificare il modello di conoscenza dopo il rilascio

Arrivati alla versione 0.4.0, avevamo bisogno di un tipo Inspection per le ispezioni pre-viaggio, mentre la relazione "Excursion caused Claim" (L'escursione ha causato la richiesta di risarcimento) risultava più chiara nella forma "Excursion led to Claim" (L'escursione ha portato alla richiesta di risarcimento). Il passaggio del modello dalla versione 1.3 alla 1.4 costituisce una modifica del modello di conoscenza, e la pagina Modifiche al modello di conoscenza ne mostra le differenze (diff), gli elementi interessati e lo stato di avanzamento.

La modifica viaggia sotto forma di richiesta di modifica del grafo. La relativa prova di esecuzione calcola gli elementi che verrebbero interessati sulla copia mascherata di Rotterdam, esprimendoli in conteggi: nel nostro caso, 1.284 collegamenti rinominati e nessun elemento rimosso. Due revisori la approvano e la pipeline la applica prima all'ambiente di staging, poi al progetto pilota. Nessuno scrive manualmente sul grafo condiviso; qualsiasi tentativo viene rifiutato e registrato. Tre domande salvate utilizzavano la parola "caused" e la modifica includeva una riscrittura automatica per ciascuna di esse, elencata nella pagina. I filtri delle viste non hanno subito variazioni, poiché entrambe le viste continuavano unicamente a restringere i dati.

Promuovere in produzione

Ogni rilascio segue un percorso unico: spazio di sviluppo, staging, unità pilota e infine tutte le unità. Ogni passaggio prevede controlli di sbarramento e nessuno di essi può essere saltato.

Verso Gate
Staging Superamento di tutti i test; controlli di qualità; manifesto invariato o ampliamento accettato; immagine firmata
Pilota (Rotterdam) Prova di modifica del modello sulla copia mascherata senza errori; verifica delle policy sulle regole di viste e ambiti; due revisori diversi dall'autore, di cui uno è il proprietario dei dati
Tutte le unità 14 giorni nel progetto pilota; tasso di errore inferiore a 1 su 1.000, misurato nel progetto pilota; approvazione dell'amministratore di ciascuna unità per la propria unità di competenza; due revisori diversi dall'autore
Ambienti e promozione
Ambienti e promozione
Cold chain 0.3.2 in attesa del secondo revisore al controllo di sbarramento del progetto pilota. L'avviso sulla destra mostra il rifiuto ricevuto per aver tentato di promuovere il rilascio direttamente da uno spazio di sviluppo a tutte le unità.

Una volta, di venerdì, ho tentato una scorciatoia per una correzione di una sola riga: promuovere la versione 0.4.0-dev dal mio spazio di sviluppo direttamente a tutte le unità. L'operazione è stata rifiutata con il codice GATE_CANNOT_BE_SKIPPED e non è stato promosso nulla. L'avviso invita invece a promuovere il rilascio al passaggio successivo, ed è l'unica via percorribile.

La revisione del rilascio in sé, le prove esaminate dal secondo revisore e i canali scelti dalle unità sono trattati nel capitolo 2.28, Rilasciare la propria estensione. Due aspetti di quel capitolo meritano di essere citati qui, poiché influenzano il modo in cui si pianifica una soluzione verticale. L'autore non può mai figurare come revisore, pertanto un team di due persone necessita di una terza persona per ogni rilascio. Inoltre, ciascun ambiente conserva la versione precedente per 30 giorni, perciò il ripristino (rollback) è una modifica soggetta a revisione che la pipeline esegue in circa un minuto.

Estendere un pacchetto già esistente

Non tutte le soluzioni verticali partono da zero. Un pacchetto può ereditare da un altro e aggiungere solo ciò che differisce. Il pacchetto Banking and payments, utilizzato da Larchmont Bank, rappresenta l'esempio più chiaro presente nel catalogo. Il suo manifesto inizia così:

{
  "id": "fintech",
  "name": "Banking and payments",
  "version": "0.1",
  "inherits": "insurance",
  "clusters": [
    {
      "id": "FL01",
      "kind": "lens",
      "name": "Lending decisions",
      "seats": "Credit analysts, underwriters of loans, credit committee",
      "purpose": "Whether to lend, how much, at what price, and writing down why.",
      "lexicon": ["fin"],
      "menu": [],
      "screens": []
    }
  ],
  "lexicon": {
    "core": [],
    "fin": [
      ["APR", "the yearly cost of borrowing, fees included", "exact"],
      ["mandate", "the most one person may lend alone", ""]
    ]
  }
}

inherits indica il nome del pacchetto su cui si basa. Banking and payments mantiene la struttura del pacchetto Insurance, i suoi cluster di conversazione condivisi e i suoi termini fondamentali, aggiungendo tre viste proprie: Lending decisions, Card disputes e My account. Il terzo elemento di ciascuna voce del lessico è impostato su exact per i termini che devono essere mostrati esattamente come sono scritti, ad esempio APR (annual percentage rate, tasso annuo effettivo globale), anziché essere riformulati.

Alcune operazioni non sono consentite tramite l'ereditarietà. Un pacchetto non modifica mai la shell, i componenti o le regole di scrittura, pertanto un pacchetto derivato non può alterare lo stile grafico della console. Un regime normativo necessario a più pacchetti viene gestito tramite un'unica vista condivisa anziché creare una copia in ciascuno di essi: il registro delle tecnologie esternalizzate serve sia Insurance sia Banking and payments. Se il proprio pacchetto derivato necessita di una vista già esistente come vista condivisa, è opportuno utilizzare quest'ultima anziché crearne una nuova.

L'assegnazione delle licenze segue la catena di ereditarietà. Un pacchetto viene concesso in licenza sull'edizione Enterprise e può richiedere componenti aggiuntivi; il documento di licenza riporta tali dipendenze. Il pacchetto Insurance richiede il componente Decision rooms and sealed records, pertanto un cliente che acquisisce in licenza un pacchetto che eredita da Insurance avrà bisogno anche di tale componente aggiuntivo, e la console si rifiuterà di emettere una licenza che lo ometta. Anche le schermate per telefono di un pacchetto richiedono il componente aggiuntivo Mobile apps. È quindi opportuno verificare l'intera catena dei requisiti prima di promettere una data di consegna a un cliente.

Aggiungere una vista a un pacchetto già rilasciato

Il lavoro verticale più piccolo è una nuova lente su un pacchetto che non avete scritto voi. A sei mesi dall'inizio del progetto pilota, il team dei sinistri marittimi di Larkfield voleva una propria lente all'interno di Catena del freddo: escursioni e richieste di risarcimento, nessun punto di alimentazione, nessun setpoint. Non abbiamo toccato il codice del pacchetto. Una lente è una riga nel registro delle lenti dell'organizzazione, di proprietà del pacchetto, quindi l'abbiamo avviata dal percorso standard per le lenti su Inizia qualcosa di nuovo e l'abbiamo modellata nel Generatore di lenti prendendo come base la lente del controllore della catena del freddo. Si applica la stessa regola di prima: la nuova lente può nascondere ciò che la sua base mostra, ma non può mai mostrare di più. Viene definita una sola volta per l'organizzazione e concessa a un ruolo della piattaforma in ciascuna unità. Una concessione viene revocata, mai eliminata, e assegnare nuovamente la lente crea una nuova concessione, in modo che resti leggibile chi ha detenuto quale lente e quando. Il registro conta quante persone hanno detenuto una lente ogni mese, mai chi.

La pagina Lenti e chi le vede mostra il risultato come una matrice di lenti per unità e ruolo, con Aggiungi, Modifica e Revoca su ciascuna cella. Visualizzi in anteprima la nuova lente nei panni di una persona prima di concederla, esattamente come indicato sopra.

Quanto è costato, in tutta onestà

Un pacchetto tocca i record di un cliente, quindi la piattaforma rallenta intenzionalmente alcune operazioni, ed è opportuno pianificarle fin dal primo giorno.

  1. Una copia mascherata richiede ogni volta il consenso del proprietario dei dati. Il nostro ha impiegato un giorno per arrivare la prima volta, perché Priya voleva leggere prima il modello di conoscenza. Inizi con dati sintetici e chieda in anticipo.
  2. L'autore non può approvare il proprio rilascio e le richieste scadono dopo 3 giorni. Se i suoi revisori sono impegnati, il suo rilascio resta in attesa.
  3. Un rilascio che richiede più autorizzazioni rispetto al precedente, come l'invio di posta o un indirizzo esterno, viene trattenuto finché due revisori non accettano il manifesto più ampio. Il Capitolo 2.28, Rilasciare la propria estensione, mostra la pagina Manifesto e autorizzazioni che la informa prima ancora di chiedere.
  4. Una lente non può mostrare ciò che la sua lente di base nasconde. Se un ruolo ha davvero bisogno di vedere di più, si tratta di una conversazione con l'amministratore dell'organizzazione, non di un'impostazione.

Nessuno di questi aspetti ci ha ostacolato due volte. Il secondo rilascio di Catena del freddo ha richiesto una settimana dal primo commit al progetto pilota di Rotterdam, gran parte della quale dedicata all'esecuzione dei 66 test su tre branch e alla lettura delle prove da parte di due persone.