BejelentkezésBemutató kérése

2.24. fejezet

Egyedi iparági megoldás felépítése az elejétől a végéig

A Cold chain szakterületi csomag kidolgozott felépítése az első igényfelméréstől a minden egységnél futó kiadásig, a hozzá tartozó tudásmodellel, nézetekkel, egy képességgel (skill), egy teljes szolgáltatást nyújtó beépülő modullal és mintaadatokkal. Ezt követően bemutatjuk, hogyan bővíthető egy már meglévő csomag, és hogyan adható hozzá egy új nézet egy már kiadott csomaghoz.

Ezt az oldalt AI fordította az eredeti angol szövegből. Ha bármi nem egyértelmű, az angol nyelvű oldal az irányadó. Oldal olvasása angolul

19 perc olvasási idő

Mateo Ruiz vagyok, a Corrán Orbital fejlesztője. A hetem nagy részét saját hasznos teher szoftverünkkel töltöm, ez a fejezet azonban egy ügyfélnek végzett munkánkról szól. A Larkfield & Vane rakományt biztosít, és ennek egyre nagyobb része hűtőkonténerekben utazik. Ha egy hűtőkonténer a rakparton elveszíti a parti áramellátást, a hőmérséklet emelkedik, a rakomány megromlik, és hetekkel később kárigény érkezik. A Larkfield azt szerette volna, hogy munkatársai ezt a láncot egyetlen egészként lássák a Nexusban, az áramkimaradástól a kárigényig, és minden szerepkör csak a saját részét lássa. Ebből lett a Cold chain csomag.

Az alábbiakban a fejlesztést abban a sorrendben mutatom be, ahogyan elvégeztük, a képernyőkkel, a fájlokkal és a parancsokkal együtt. A hibákat is benne hagytam, mert a két elutasítás, amelybe belefutottunk, többet tanított nekünk a platformról, mint a zökkenőmentes út. A referenciaanyag az ezt megelőző fejezetekben található, és inkább azokra hivatkozom, mintsem megismételjem őket. Leginkább a 2.18. fejezetre (A bővítési modell) és a 2.23. fejezetre (Szakterületi csomagok) támaszkodtam, mellettük pedig nyitva tartottam a 2.21. fejezetet (A Plugin SDK) magához a szoftverfejlesztői készlethez.

Nyolc dobozból álló, balról jobbra haladó útvonal: „Feladatleírás”, „Golden path”, „Tudásmodell”, „Lencsék”, „Képesség és bővítmény”, „Mintaadatok és előnézet”, „Kiadási felülvizsgálat”, „Léptetés”. Az utolsó doboz alatt egy második sor, négy kisebb, nyilakkal összekötött dobozzal, a léptetés lépéseit mutatja: „Fejlesztői tér”, „Staging”, „Pilot egység (Rotterdam)”, „Összes egység”, és minden nyílon egy „kapu” feliratú lakat ikon látható. A „Fejlesztői tér” dobozból közvetlenül az „Összes egység” dobozba mutató szaggatott nyíl át van húzva, és GATE_CANNOT_BE_SKIPPED felirat tartozik hozzá.
A Cold chain fejlesztése a megbízástól az összes egységig.

Az igényfelmérés, és hogy ki mit csinál

A Larkfield a projekt idejére fejlesztői helyet biztosított számomra a szervezetében. Ennek jelentősége van, mert egy egyetlen ügyfélnek szóló privát csomag az adott ügyfél telepítésén belül készül, annak fejlesztői terein és adatágain, a munkatársai jóváhagyásával. A több ügyfélnek szánt csomag másként készül, egy kiadói fürtön, kizárólag mintaadatokkal; ezt az esetet a 2.25. fejezet (Fejlesztés az egyes kiadásokhoz) tárgyalja.

A megbízás elfért egy oldalon:

  • Hűtőkonténerek a rakparton és a hajókon: áramellátásuk, hőmérséklet-eltéréseik és az ezeket követő kárigények.
  • Kezdetben két szerepkör: egy hűtőkonténer-technikus a rakparton és egy hűtőlánc-irányító az irodában.
  • Egy kísérleti üzem, amely először a rotterdami egységben fut, majd ezt követően Felixstowe-ba kerül át.
  • Bizonyítékok három szabályrendszerhez: a romlandó élelmiszerekre vonatkozó ATP-megállapodáshoz, a gyógyszerekre vonatkozó uniós helyes forgalmazási gyakorlathoz, valamint a HACCP (veszélyelemzés és kritikus szabályozási pontok) szerinti élelmiszer-biztonsági nyilvántartásokhoz. A Hága–Visby-szabályok szerinti kárigények ugyanazokat az eltérési nyilvántartásokat használják, ezért ezeket a kísérleti üzem utánra jegyeztük fel.

A szakterületi csomagok Enterprise-funkciót jelentenek. A Larkfield Enterprise-t használ, így a szakterületi csomag útvonala nyitva állt előttem. Community kiadásban a csomagokhoz tartozó bevált útvonal egyáltalán nem érhető el.

Indulás a javasolt alapútvonalról

Minden a Valami új indítása oldalon kezdődik. Ez hat bevált útvonalat kínál: bővítmény, szakterületi csomag, nézet, platform, készség és munkafolyamat. Mindegyik egy verziózott sablonból hoz létre egy tárolót, egy manifesztet, amely deklarálja, mire van szüksége az adott elemnek, teszteket, egy fejlesztői teret és adatágakat. Ugyanezek az útvonalak működnek a konzolban, a parancssorban és az IDE-ben (integrált fejlesztői környezetben) is, ahol a Workbench eszköz, a nexus.create, ugyanezt a feladatot látja el egy olyan tervvel, amelyet Ön előbb jóváhagy.

Valami új indítása
Valami új indítása
A hat bevált útvonal, mindegyiknél azzal, amit létrehoz, a hozzá tartozó nexus create paranccsal és a rögzített sablonjával. Figyelje meg az alján lévő táblát: a manifeszt kötelező érvényű, nem csupán tájékoztató jellegű, és az a kiadás, amely többet kér, visszatartásra kerül, amíg két személy át nem vizsgálja.

Erről az oldalról a szakterületi csomag útvonalát választottuk, a csomagnak a cold-chain nevet, első egységének pedig a Rotterdam nevet adva. Az eredmény megnevezi a rögzített sablont (domain-pack@1.6.0), és felsorolja, mit hozott létre: a tárolót, egy négy hatókört, két tárat és nulla kimenő címet deklaráló manifesztet, 66 tesztet a sablonból, egy fejlesztői teret Rotterdamban, három szintetikus adatágat, valamint egy piszkozatbejegyzést a Larkfield saját katalógusában, amelyet csak én láthattam. A sablon verziója rögzített, és későbbi frissítése bármely más változtatáshoz hasonlóan átvizsgált módosításként érkezik, így senkinek a csomagja nem változik meg csak azért, mert egy sablon megváltozott. Első csomagunkhoz ennek ellenére a konzol varázslóját használtam, mert az még a létrehozás előtt megmutatja a tervet.

1. lépés: határozza meg a csomag célját

Az Új szakterületi csomag varázsló három lépésből áll: leírás, tudásmodell, valamint áttekintés és létrehozás. Az 1. lépés azt a néhány dolgot kérdezi meg, amely minden további lépést meghatároz.

Mező Amit megadtunk Megjegyzés
Név Cold chain A tárolóhoz és a katalógushoz használatos
Mire szolgál Hűtőkonténerek a rakparton és a hajókon: áramellátás, hőmérséklet-eltérések és az ezeket követő kárigények
Iparág Logisztika és tengeri szállítás A Logistics and maritime csomagra épül
Tulajdonos (Owner) A létrehozó személy A varázslóban zárolva
Egységek Rotterdam (kísérleti üzem) Felixstowe a kísérleti üzem után
Sablon domain-pack@1.6.0 Zárolva; a frissítések átvizsgált módosításként érkeznek
Leképezett szabályok ATP-megállapodás, uniós helyes forgalmazási gyakorlat, élelmiszer-biztonsági nyilvántartások Minden szabály egy oldallá válik a csomag bizonyítéktérképén

Az utolsó sort a dokkban lévő asszisztens javasolta, beleértve azt is, hogy a rakománnyal kapcsolatos kárigények ugyanazokat az eltérési nyilvántartásokat használják fel. Az oldal alján lévő tábla jelzi, hogy még semmi sem jött létre. A tároló, a fejlesztői tér és az adatágak csak akkor jönnek létre, amikor Ön a 3. lépésben megnyomja a Létrehozás gombot, miután megtekintette a tervet. Piszkozatot menthet, és később visszatérhet hozzá.

2. lépés: a tudásmodell

A tudásmodell azon dolgok típusainak halmaza, amelyekről a csomag tud, valamint az, hogy ezek hogyan kapcsolódnak egymáshoz. A Cold chain a logisztikai alapmodellből (logistics-base 4.2) indult, amelyet az SDK-ból importáltunk, és amely öt alaptípust adott, amelyekre építhettünk (Hajó, Kikötő, Konténer, Fuvarozó és Szállítmány). Az alaptípusok a varázslóban csak olvashatók. Ha valamelyiket módosítani kell, azt az azt birtokló csomagban kell módosítani.

Öt saját típust adtunk hozzá:

Típus Mi ez Tulajdonságok
Hűtőkonténer-egység Egy hűtött konténer 9
Hajóérkezés Egy hajó egy kikötőhelyen 6
Eltérés A határértékein kívül eső hőmérséklet 8
Áramellátás Parti vagy hajó fedélzeti csatlakozási pont 4
Birtokbavétel (Claim) Megromlott rakományért igényelt összeg 7
Új szakterületi csomag: tudásmodell
Új tartománycsomag: tudásmodell
A tudásgráf öt alaptípussal és öt új típussal. Tekintse meg jobb oldalon az Eltérés tulajdonságait: minden tulajdonság már létrehozásakor megkapja a besorolását, a tábla pedig jelzi, hogy a kárigények összegei üzleti jellegűek, így a technikusi nézetek nem jeleníthetik meg őket.

Minden tulajdonság a létrehozásakor besorolást kap. Egy Eltérés „Bejelentő” tulajdonsága személyes. A „Kockázatnak kitett rakományérték”, valamint egy kárigény összege és rendezése üzleti jellegű. Ez az első napon papírmunkának tűnt, később azonban kétszer is megmentett minket, mert a besorolások határozzák meg, mit jeleníthet meg egy nézet, mit helyettesít egy maszkolt másolat, és mit rejt el egy naplósor.

Két kapcsolatunk az alapmodellbe nyúlik: egy Hűtőkonténer-egység egy Áramellátáshoz csatlakozik, egy Kárigény pedig egy Szállítmányra hivatkozik. Maga az alapmodell nem változik. A visszavont tulajdonság a modell 1.0-s verziójában megmarad, és csak egy későbbi verzióból kerül ki, így semmi, ami a régi rekordokra igaz volt, nem válik olvashatatlanná.

3. lépés: áttekintés és létrehozás

A 3. lépés a terv. Felsorolja, mi fog létrejönni, a manifeszt által deklarálandó hatóköröket, az adatágakat és a fejlesztői teret. A tervet a hozzáférési kulcsával hagyja jóvá, és a terv ujjlenyomatot kap. A létrehozás ezután pontosan ezt a tervet követi, lépésről lépésre, és Ön bármelyik lépésnél leállíthatja, megtartva az addig létrehozottakat.

A Cold chain terve négy hatókört deklarált:

Hatókör Miért van rá szüksége a csomagnak
Hűtőkonténer-telemetria olvasása Áramellátási és hőmérsékleti mérések
Eltérések írása Rögzíti az eltérést, ha a határértékek sérülnek
Szállítmányok olvasása Összekapcsolja a kárigényt a szállítmányával
Kárigény-feljegyzések piszkozata Csak piszkozatok; a küldést egy személy végzi

Tárai a gráf és a nyilvántartások voltak. Nem volt kimenő címe, és a Standard sandboxprofilt használta. A fejlesztői tér 4 maggal, 16 GiB memóriával és 50 GiB tárhellyel jött létre, a manifeszt által deklaráltakon kívül zárt hálózattal, kizárólag aláírt képfájlokkal, és 7 tétlen nap után megszűnik. Megszűnésekor a definíciója a tárolóban marad, így onnan újra létrehozhatja.

A három adatág a szintetikus generátorból származott. Ügyféladatot nem másoltunk. Rotterdam maszkolt másolatához az adatgazda hozzájárulása szükséges, aki a Larkfieldnél Priya Natarajan, és ezt külön kell kérelmezni.

A csomag leírófájlja (manifest)

A tároló tartalmazza a csomag manifesztjét, a pack.json fájlt. Ez megnevezi a csomagot, annak verzióját, azt a csomagot, amelytől örököl (ha van ilyen), a fürtjeit és a szavait. Egy fürt vagy nézet, vagyis az, amit egy szerepkör a csomagon belül lát, vagy megosztott, amely minden nézeten átível. Íme a miénk magja:

{
  "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", ""]
    ]
  }
}

A szókészlet a csomag saját szavait tartalmazza, mindegyikhez egy egyszerű magyarázattal, amely elég rövid ahhoz, hogy telefonon is el lehessen olvasni.

A pack.json mellett a manifeszt azt is deklarálja, mihez férhet hozzá a csomag: hatóköreit, tárait, kimenő címeit és sandboxprofilját. A Nexus pontosan ezt biztosítja, és semmi többet. Minden eszközhívás ellenőrzésre kerül a deklarált hatókörökkel szemben, és a külső címek le vannak tiltva, kivéve, ha szerepelnek a listán. A deklarációt, valamint a legutóbbi kiadáshoz képesti változást a csomag Manifeszt és engedélyek oldalán tekintheti meg.

Nézetek: mit látnak az egyes szerepkörök

Egy nézet mindig csak szűkítheti azt, amit az alapja megjelenít, és ez az egyetlen szabály minden másnál jobban alakította a tervezésünket. Egy nézet annak egy részét jeleníti meg, amit az alapnézete mutat, az engedélyek pedig továbbra is a szerepkörökből származnak: a nézet azt határozza meg, mit lát egy szerepkör a csomagban, nem pedig azt, hogy mit tehet.

A Hűtőkonténer-technikus nézet a Műveleti irányító nézetet szűkíti, azt az alapnézetet, amelyet a Larkfield már használ a logisztikai munkához. A Nézetszerkesztőben bejelöli azokat a kártyákat, mezőket és műveleteket, amelyeket a nézet megjelenít. Azok az elemek, amelyeket az alap nem jelenít meg, zárolva vannak.

Rész A Hűtőkonténer-technikus megjeleníti Kihagyva
Kártyák Hűtőkonténer-egységek a rakparton, nyitott eltérések, csatlakozási pontok, mai hajóérkezések Bármi, ami kárigényekkel kapcsolatos
Mezők Áramellátási állapot, beállított érték, utolsó mérés, legmagasabb hőmérséklet Kárigény összege (nincs az alapnézetben), személyes mezők (alapértelmezés szerint kikapcsolva)
Műveletek Eltérés okának rögzítése, áramellátás-ellenőrzés kérése Beállított érték módosítása és eltérés lezárása (csak irányítók), kárigény-feljegyzés piszkozatának elkészítése
Lencseépítő
Lencseépítő
A Hűtőkonténer-technikus Nézetszerkesztője, az alapnézetével szemben bejelölve. A bal alsó sarokban lévő tábla azt az elutasítást mutatja, amelyet a kárigény összegének bejelölésekor kap: az alapnézet nem jeleníti meg, így ez a nézet sem teheti.

Ennek ellenére megpróbáltam hozzáadni a kárigény összegét a technikusi nézethez, mert egy technikus kérte. A szerkesztő LENS_CANNOT_WIDEN üzenettel elutasította, és semmit sem mentett. A nézeten belül nincs kerülőút: a továbblépés módja egy szélesebb alapra épülő nézet, ami egy másik kérelem, amelyről a szervezet rendszergazdája dönt. Kihagytuk.

Ha valamit elrejt egy nézetben, az nem távolítja el a Nexusból. Csupán azt jelenti, hogy az adott szerepkör nem látja. A szerkesztő megmutatja, hány személyt ér el egy nézet a kísérleti üzemben (esetünkben 29-et), és naplót vezet minden Hozzáadásról, Módosításról és Visszavonásról. Egy nézetet egyszer kell meghatározni a szervezet számára, és egységenként rendelhető hozzá egy platformszerepkörhöz, így ugyanaz a Hűtőkonténer-technikus nézet ebben a hónapban a rotterdami, a következőben pedig a felixstowe-i technikusoknak adható meg.

Képesség (skill) kárigény-feljegyzések vázlatának elkészítéséhez

Az irányítók egy első piszkozatot szerettek volna arról a feljegyzésről, amely egy eltérés után a rakomány tulajdonosának megy. Ez nyelvi feladat, ezért modellen fut, és az volt a kérdés, hová kerüljön.

A Nexusban kétféle készség létezik, és itt a különbség lényeges. A manifeszt-készség egy bővítmény skills[] tömbjében lévő típusos sor, amelyet a platform hív meg. A Skills Engine-készség egy SKILL.md csomag a szervezet készségkönyvtárában, amelyet az ügynökök, az AI- (mesterséges intelligencia) gombok, a munkafolyamatok és a fejlesztői eszközök mind ugyanúgy futtatnak. Mindkettőt a 2.20. fejezet (Készségek) tárgyalja.

Bővítményünk megbízhatósági szintje community, és egy közösségi bővítmény csak olyan manifeszt-készségeket deklarálhat, amelyek nem érnek el modellt (host_callback és plugin_queue). Az AI Provider Routert elérő két szinthez, a tool_using és a llm_only szinthez, core vagy verified megbízhatósági szint szükséges. Így a kárigény-feljegyzések piszkozatának elkészítése Skills Engine-készség lett, és a router a Larkfield saját készletéből választja ki a modellt:

---
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.

A csomag a tároló skills/draft-claim-note/ mappájában található, a mappa neve megegyezik a készség nevével. A terminálból validáltuk és töltöttük fel:

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

Ugyanazon tartalom kétszeri feltöltése új verzió helyett a meglévő verziót adja vissza (CONTENT_HASH_ALREADY_PUBLISHED), így a feltöltés ismételt futtatása biztonságos. Mielőtt egy verzió kiadásra kerül, a Skills Engine lefuttatja a teszteseteit, árnyék módban egy próbafuttatást korábbi munkákon, valamint egy vak értékelést egy másik vállalat modelljével, minden futtatás idejével és költségével együtt.

A teljes szolgáltatást nyújtó beépülő modul

A csomagnak folyamatosan futó kódra is szüksége volt: egy olvasóra a hűtőkonténer-telemetria adatfolyamához, és egy íróra, amely eltérési rekordot nyit, ha egy mérés túllépi a határértékeit. Az ilyen kód egy teljes szolgáltatású bővítménybe tartozik, és ennek vázát az SDK saját parancsával hoztuk létre, amely a teljes referenciafát megírja, behelyettesítve a nevet:

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

Az SDK a https://registry.adverant.ai/npm/ helyről telepíthető az Adverant-fiókja Lekérési tokenek és telepítési parancsok oldalán található lekérési tokennel. Véglegesítse az első telepítés által írt package-lock.json fájlt; a képfájl buildelése a npm ci parancsot futtatja, és enélkül megtagadja a futást.

Íme a nexus.manifest.json azon része, amely eltér a sablontól. Ez nem a teljes fájl: a váz description, author, license, runtime, backend és frontend blokkjai változatlanok maradnak, és az ellenőrző elutasítja a teljes szolgáltatásra vonatkozó manifestet nélkülük. A három architecture mondat az a szabály, amelyet minden bővítmény megismétel, és az ellenőrző vizsgálja a megfogalmazást. Az elsőben szereplő UNO a munkafolyamat-motor:

{
  "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 }
  }
}

A excursion_open egy manifest-képesség host_callback szinttel: a platform a bemenetet a saját Service-ünknek küldi, a saját névterünkön belül, és soha nem egy általunk megnevezett gépnek. A fogadó útvonal auth: internal-ként van deklarálva, és az SDK serviceMiddleware védelme őrzi, amely a védelem Express-változata, és elutasítja a bármely más bővítményhez, szervezethez, képességhez vagy útvonalhoz kiállított hívási tokent. A classification értéke tenant, ami a közösségi bővítmények felső határa. A 2.27. fejezet (Build-forgatókönyvek) külön is bemutat egy host_callback képességet.

Ebből a szakaszból két szokást érdemes átvenni. Minden tábla az első migrációtól kezdve tartalmazza a organization_id, owner_user_id és business_unit_id mezőt, mert egy dimenzió későbbi hozzáadása élő sorokon végzett migrációt jelent. Továbbá minden push előtt helyben lefuttattuk a nexus-gates parancsot, mivel ugyanezt a parancsot futtatja a pipeline is; az a futás, amely semmit sem vizsgált, 2-es kóddal lép ki, és ezt jelzi is. A 2.19. fejezet (A szabályok, amelyeket minden bővítmény örököl) felsorolja a kapukat.

Mintaadatok a teszteléshez

A Mintaadatok teszteléshez oldal háromféle ágat kínál:

Típus Mit tartalmaz Ki hagyja jóvá
Szintetikus Az Ön által megadott darabszámok és alakzatok alapján generált adatok; semmi sem származik valódi egységből Senki; az Öné
Maszkolt másolat Egy egység másolata, amelyben a személyes, érzékeny és üzleti mezők le vannak cserélve Az adatgazda (Rotterdam esetében Priya Natarajan)
Csak séma Az adattárak szerkezete, sorok nélkül Senki; migrációkhoz

Egy forgalmas hetet generáltunk: nagyjából 7 hőmérséklet-eltérést minden 100 hűtőkonténerre, ami egy forgalmas augusztusnak felel meg Rotterdamban. A szokatlan esetek többet számítottak, mint a mennyiség. Kértünk áramkimaradást kirakodás közben, nyitva hagyott ajtót, érzékelőkiesést, valamint két kárigényt egyetlen eltéréshez. Az oldal a tudásmodellben szereplő eltérési okok alapján tud szokatlan eseteket javasolni, valódi rekordok alapján soha.

A darabszámok és alakzatok minden készlete magként (seed) mentődik, például cold-chain-busy-01 néven, az ujjlenyomatával együtt. Ugyanaz a mag ugyanazokat az adatokat adja, így minden ágon minden tesztfuttatás ugyanazt a hetet látja. Ettől lett megismételhető a 66 tesztünk.

Egy ág alapértelmezés szerint 72 óráig, legfeljebb 14 napig él. Egy hosszú felülvizsgálat idejére kértem, hogy a forgalmas águnkat 30 napig megtarthassuk, és az oldal ezt BRANCH_LIFE_EXCEEDED hibával elutasította. A megoldás az, amit a hibaüzenet is javasol: tartsa meg a magot, és szükség esetén hozzon létre belőle új ágat. A maszkolt másolatra ugyanezek a korlátok vonatkoznak, és a kérelméhez indoklást és legfeljebb 14 napos időtartamot kell megadni.

Lencse előnézete egy adott személy szemszögéből

Mielőtt Rotterdamban bárki látta volna a Cold chain csomagot, úgy néztük meg, ahogy ők látnák. A Lencse előnézete egy személy szemével funkció pontosan úgy jeleníti meg a csomagot, ahogyan egy kiválasztott szerepkör látja, egy adatágon, szaggatott előnézeti keretben.

Lencse előnézete egy személy szemével
Lencse előnézete egy adott személy szemszögéből
A Cold chain úgy, ahogyan egy rotterdami hűtőkonténer-technikus látja, egy szintetikus ágon. Figyelje meg a „lencse által elrejtve” jelölésű kárigény-oszlopot minden nyitott eltérésnél, valamint az oldalpanelt, amely leírja, mit rejt el ez a lencse és miért.

Három szabály teszi biztonságossá az előnézetek szabad használatát. Az előnézet adatágat használ, soha nem az élő egységet. Az Ön saját jogosultságai nem szivárognak bele, így azt látja, amit a szerepkör lát, nem azt, amit Ön láthat. Végül 30 perc után véget ér. Ha az előnézetet élő egységre irányítja, a rendszer CONNECTION_SCOPE_EXCEEDED hibával elutasítja; ha valódi szerkezetekre van szüksége, kérjen maszkolt másolatot az adatgazdától, és azon készítsen előnézetet.

Az előnézetben fogtunk el egy valódi hibát. A technikusi nézet hőmérséklet-diagramja megjelenítette az alapjelet, az alapjel szerkesztése pedig csak az irányítóknak volt szánva. A diagrammal nem volt gond; az alatta lévő szerkesztés gombbal igen. A 0.3.2-es verzió elrejtette az alapjel szerkesztését a technikusok elől, és a hibát az előnézetben találtuk meg.

A tudásmodell módosítása a kiadás után

A 0.4.0-s verzióra szükségünk lett egy Inspection típusra az indulás előtti ellenőrzésekhez, és az „Excursion caused Claim” kapcsolat jobban hangzott „Excursion led to Claim” formában. A modell 1.3-ról 1.4-re léptetése tudásmodell-módosítás, és a Tudásmodell-módosítások oldal megmutatja a különbségeket, hogy mit érintene, és hol tart a folyamatban.

A módosítás gráfmódosítási kérelemként halad. A próbafuttatása Rotterdam maszkolt másolatán megszámolja, mit érintene, darabszámokként: nálunk 1284 átnevezett kapcsolat, törlés nélkül. Két felülvizsgáló jóváhagyja, a pipeline pedig alkalmazza előbb a staging környezetre, majd a pilotra. A közös gráfba senki sem ír kézzel; az ilyen kísérletet a rendszer elutasítja és rögzíti. Három mentett kérdés használta a „caused” szót, és a módosítás mindegyikhez automatikus átírást tartalmazott, amelyeket az oldal felsorolt. A lencseszűrők nem változtak, mert mindkét lencse továbbra is csak szűkített.

Élesítés

Minden kiadás egyetlen útvonalon halad: fejlesztői tér, staging, egy pilot egység, majd az összes egység. Minden lépésnek vannak kapui, és egyik sem hagyható ki.

Cél Kapuk
Staging Minden teszt sikeres; minőségi ellenőrzések; a manifest változatlan, vagy a bővítést elfogadták; aláírt image
Pilot (Rotterdam) A modellmódosítás próbafuttatása a maszkolt másolaton hiba nélkül; házirend-ellenőrzés a lencse- és hatóköri szabályokra; két, a szerzőtől különböző felülvizsgáló, akik közül az egyik az adatgazda
Összes egység 14 nap a pilotban; 1000-ből 1-nél kevesebb hiba a pilotban mérve; minden egységadminisztrátor jóváhagyja a saját egységére; két, a szerzőtől különböző felülvizsgáló
Környezetek és előléptetés
Környezetek és előléptetés
A Cold chain 0.3.2 a pilot kapunál várakozik a második felülvizsgálójára. A jobb oldali üzenet az elutasítás, amely akkor jelenik meg, ha valaki közvetlenül a fejlesztői térből próbál az összes egységre léptetni.

Egyszer, egy pénteken kipróbáltam a rövidítést egy egysoros javításnál: a 0.4.0-dev léptetését a fejlesztői teremből az összes egységre. A rendszer GATE_CANNOT_BE_SKIPPED hibával elutasította, és semmi sem lett léptetve. Az üzenet azt javasolja, hogy inkább a következő lépésre léptessen, és ez az egyetlen lehetséges válasz.

Magát a kiadási felülvizsgálatot, a második felülvizsgáló által olvasott bizonyítékokat és az egységek által választott csatornákat a 2.28. fejezet (A bővítmény kiadása) ismerteti. Két tény ide tartozik belőle, mert befolyásolják egy vertikális megoldás tervezését. A szerző soha nem számít felülvizsgálónak, így egy kétfős csapatnak minden kiadáshoz harmadik személyre van szüksége. Emellett minden környezet 30 napig megőrzi az előző verziót, így a visszaállítás egy felülvizsgált módosítás, amelyet a pipeline körülbelül egy perc alatt elvégez.

Már meglévő csomag bővítése

Nem minden vertikális megoldás indul a nulláról. Egy csomag örökölhet egy másiktól, és csak az eltéréseket adja hozzá. A Larchmont Bank által futtatott Banking and payments csomag a katalógus legszemléletesebb példája. A manifestje így kezdődik:

{
  "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", ""]
    ]
  }
}

A inherits megnevezi azt a csomagot, amelyre épül. A Banking and payments megtartja az Insurance csomag szerkezetét, közös beszélgetési klasztereit és alapszavait, és három saját lencsével bővíti: Lending decisions, Card disputes és My account. Minden szótárbejegyzés harmadik eleme exact az olyan kifejezéseknél, amelyeket a leírt formában kell megjeleníteni, például az APR (teljes hiteldíjmutató), és nem szabad átfogalmazni.

Bizonyos dolgok örökléssel nem valósíthatók meg. Egy csomag soha nem módosítja a keretet, a komponenseket vagy az írási szabályokat, így egy gyermekcsomag nem alakíthatja át a konzol megjelenését. Egy olyan szabályozási rendszer, amelyre több csomagnak is szüksége van, egyetlen közös lencse, nem pedig mindegyikben egy-egy másolat: a kiszervezett technológiák nyilvántartása az Insurance és a Banking and payments csomagot is kiszolgálja. Ha a gyermekcsomagjának olyan lencsére van szüksége, amely már közös lencseként létezik, azt használja, ahelyett hogy sajátot készítene.

A licencelés követi az öröklést. Egy csomag az Enterprise-ra épülve licencelhető, és kiegészítőket igényelhet; ezeket a függőségeket a licencdokumentum tartalmazza. Az Insurance csomaghoz szükség van a Decision rooms and sealed records kiegészítőre, így az ezt öröklő csomagot licencelő ügyfélnek is szüksége van erre a kiegészítőre, és a konzol megtagadja az olyan licenc kiállítását, amelyből hiányzik. Egy csomag telefonos képernyőihez a Mobile apps kiegészítő is szükséges. Mielőtt dátumot ígérne egy ügyfélnek, ellenőrizze a követelmények láncát.

Lencse hozzáadása egy már kiadott csomaghoz

A legkisebb vertikális feladat egy új lencse egy olyan csomagon, amelyet nem Ön írt. Hat hónappal a pilot indulása után a Larkfield tengeri kárügyintézési csapata saját lencsét szeretett volna a Cold chain csomagon belül: eltérések és kárigények, áramcsatlakozók és alapjelek nélkül. A csomag kódjához nem nyúltunk. A lencse egy sor a szervezet lencsenyilvántartásában, amelynek a csomag a tulajdonosa, ezért az Új indítása oldalon a lencsékhez tartozó golden pathról indítottuk, és a Lens builderben alakítottuk ki, alapként a Cold-chain controller lencsét használva. Ugyanaz a szabály érvényes, mint korábban: az új lencse elrejtheti, amit az alapja mutat, de soha nem mutathat többet. Egyszer kerül meghatározásra a szervezet számára, és minden egységben egy platformszerepkörhöz rendelik hozzá. A hozzárendelést visszavonják, soha nem törlik, és a lencse ismételt kiosztása új hozzárendelést hoz létre, így olvasható marad, hogy ki mikor melyik lencsével rendelkezett. A nyilvántartás havonta azt számolja, hányan rendelkeztek egy lencsével, azt soha, hogy kik.

A Lencsék és akik látják őket oldal az eredményt lencse, valamint egység és szerepkör szerinti mátrixként jeleníti meg, minden cellában Hozzáadás, Módosítás és Visszavonás lehetőséggel. Mielőtt kiosztja az új lencsét, tekintse meg előnézetben egy személy szemével, pontosan a fentiek szerint.

Mibe került mindez, őszintén

Egy csomag az ügyfél rekordjaihoz nyúl, ezért a platform szándékosan lassít bizonyos dolgokat, és ezekkel az első naptól számolnia kell.

  1. A maszkolt másolathoz minden alkalommal az adatgazda jóváhagyása szükséges. Nálunk elsőre egy napig tartott, mert Priya előbb el akarta olvasni a tudásmodellt. Kezdjen szintetikus adatokkal, és kérjen időben.
  2. A szerző nem hagyhatja jóvá a saját kiadását, és a kérelmek 3 nap után lejárnak. Ha a felülvizsgálói elfoglaltak, a kiadása várakozik.
  3. Az a kiadás, amely többet kér az előzőnél, például levélküldést vagy egyetlen külső címet, addig vissza van tartva, amíg két felülvizsgáló el nem fogadja a bővített manifestet. A 2.28. fejezet (A bővítmény kiadása) bemutatja a Manifest és jogosultságok oldalt, amely ezt még a kérés előtt jelzi.
  4. Egy lencse nem mutathatja meg, amit az alaplencséje elrejt. Ha egy szerepkörnek valóban többre van szüksége, azt a szervezet adminisztrátorával kell megbeszélni; ez nem beállítás kérdése.

Ezek egyike sem akadályozott minket kétszer. A Cold chain második kiadása az első commit-tól a rotterdami pilotig egy hetet vett igénybe, aminek nagy részét a 66 teszt három ágon való futása és két ember bizonyítékolvasása tette ki.