Zaloguj sięUmów spotkanie

Rozdział 2.24

Kompleksowe budowanie niestandardowego rozwiązania branżowego

Praktyczny przykład budowy pakietu domenowego Cold chain, od pierwszych założeń po wydanie działające w każdej jednostce, obejmujący model wiedzy, soczewki, umiejętność, wtyczkę full-service oraz dane przykładowe. Następnie omówienie sposobu rozszerzania istniejącego pakietu oraz dodawania soczewki do pakietu, który został już wdrożony.

Ta strona została przetłumaczona przez AI z angielskiego oryginału. W razie jakichkolwiek niejasności wersją wiążącą jest strona w języku angielskim. Przeczytaj tę stronę po angielsku

Czas czytania: 19 min

Nazywam się Mateo Ruiz i jestem programistą w Corrán Orbital. Większość tygodnia poświęcam naszemu własnemu oprogramowaniu ładunków użytecznych, ale ten rozdział dotyczy pracy, którą wykonaliśmy dla klienta. Larkfield & Vane ubezpiecza ładunki, a coraz większa ich część podróżuje w kontenerach chłodniczych. Gdy kontener chłodniczy (reefer) traci zasilanie z lądu przy nabrzeżu, temperatura rośnie, ładunek się psuje, a kilka tygodni później pojawia się roszczenie. Larkfield chciał, aby jego pracownicy widzieli ten łańcuch w Nexus jako jedną całość, od awarii zasilania do roszczenia, przy czym każda rola widzi tylko swoją część. Tak powstał pakiet Cold chain.

Poniżej opisuję budowę w kolejności, w jakiej ją prowadziliśmy, wraz z ekranami, plikami i poleceniami. Zostawiłem również błędy, ponieważ dwie odmowy, na które trafiliśmy, nauczyły nas o platformie więcej niż ścieżka bez przeszkód. Materiały referencyjne znajdują się w poprzednich rozdziałach i odsyłam do nich, zamiast je powtarzać. Najczęściej korzystałem z rozdziału 2.18, Model rozszerzeń, oraz rozdziału 2.23, Pakiety domenowe, mając obok otwarty rozdział 2.21, Plugin SDK, dotyczący samego zestawu narzędzi programistycznych.

Ścieżka od lewej do prawej złożona z ośmiu pól: „Założenia”, „Złota ścieżka”, „Model wiedzy”, „Soczewki”, „Umiejętność i wtyczka”, „Przykładowe dane i podgląd”, „Przegląd wydania”, „Promocja”. Pod ostatnim polem drugi rząd czterech mniejszych pól połączonych strzałkami przedstawia kroki promocji: „Przestrzeń deweloperska”, „Staging”, „Jednostka pilotażowa (Rotterdam)”, „Wszystkie jednostki”, z ikoną kłódki na każdej strzałce opisanej jako „bramka”. Przerywana strzałka z „Przestrzeń deweloperska” bezpośrednio do „Wszystkie jednostki” jest przekreślona i opisana jako GATE_CANNOT_BE_SKIPPED.
Budowa pakietu Cold chain: od założeń do każdej jednostki.

Założenia i podział zadań

Na czas projektu Larkfield przydzielił mi stanowisko programisty w swojej organizacji. Ma to znaczenie, ponieważ prywatny pakiet dla jednego klienta buduje się w instalacji tego klienta, w jego przestrzeniach deweloperskich i gałęziach danych, z zatwierdzeniami jego pracowników. Pakiet przeznaczony dla wielu klientów buduje się inaczej, w klastrze wydawcy i wyłącznie na danych przykładowych; ten przypadek opisuje rozdział 2.25, Budowanie dla każdej edycji.

Założenia zmieściły się na jednej stronie:

  • Kontenery chłodnicze przy nabrzeżu i na statkach: ich zasilanie, przekroczenia temperatury oraz wynikające z nich roszczenia.
  • Na początek dwie role: technik kontenerów chłodniczych na nabrzeżu oraz kontroler łańcucha chłodniczego w biurze.
  • Pilotaż uruchamiany najpierw w jednostce Rotterdam, a następnie przenoszony do Felixstowe.
  • Dowody dla trzech zbiorów przepisów: umowy ATP dotyczącej szybko psujących się artykułów żywnościowych, unijnej dobrej praktyki dystrybucyjnej dla produktów leczniczych oraz dokumentacji bezpieczeństwa żywności w ramach HACCP (analiza zagrożeń i krytyczne punkty kontroli). Roszczenia na podstawie reguł hasko-visbijskich korzystają z tych samych zapisów przekroczeń, więc odnotowaliśmy je na okres po pilotażu.

Pakiety domenowe są funkcją wersji Enterprise. Larkfield korzysta z wersji Enterprise, więc ścieżka pakietu domenowego była dla mnie dostępna. W wersji Community złota ścieżka dla pakietu w ogóle nie jest oferowana.

Rozpoczęcie od wzorcowej ścieżki

Wszystko zaczyna się na stronie Rozpocznij coś nowego. Oferuje ona sześć złotych ścieżek: wtyczka, pakiet domenowy, soczewka, platforma, umiejętność i przepływ pracy. Każda z nich tworzy repozytorium z wersjonowanego szablonu, manifest deklarujący, czego dany element potrzebuje, testy, przestrzeń deweloperską i gałęzie danych. Te same ścieżki działają w konsoli, w wierszu poleceń oraz w Państwa IDE (zintegrowanym środowisku programistycznym), gdzie narzędzie Workbench nexus.create wykonuje to samo zadanie na podstawie planu, który należy najpierw potwierdzić.

Rozpocznij coś nowego
Rozpocznij coś nowego
Sześć złotych ścieżek, każda z opisem tego, co tworzy, poleceniem nexus create i przypiętym szablonem. Proszę zwrócić uwagę na tabliczkę u dołu: manifest jest egzekwowany, a nie doradczy, a wydanie, które wymaga więcej, jest wstrzymywane do czasu przeglądu przez dwie osoby.

Z tej strony wybraliśmy ścieżkę pakietu domenowego, nadając pakietowi nazwę cold-chain, a jego pierwszej jednostce nazwę Rotterdam. Wynik podaje przypięty szablon, domain-pack@1.6.0, i wymienia, co zostało utworzone: repozytorium, manifest deklarujący cztery zakresy, dwa magazyny i brak adresów wychodzących, 66 testów z szablonu, przestrzeń deweloperską w Rotterdamie, trzy syntetyczne gałęzie danych oraz roboczy wpis we własnym katalogu Larkfield, widoczny tylko dla mnie. Wersja szablonu jest przypięta, a jej późniejsza aktualizacja przychodzi jako zmiana podlegająca przeglądowi, jak każda inna, więc niczyj pakiet nie zmienia się nagle tylko dlatego, że zmienił się szablon. Mimo to przy naszym pierwszym pakiecie użyłem kreatora w konsoli, ponieważ pokazuje on plan, zanim cokolwiek utworzy.

Krok 1: określenie przeznaczenia pakietu

Kreator Nowy pakiet domenowy ma trzy kroki: informacje, model wiedzy oraz przegląd i utworzenie. Krok 1 zadaje kilka pytań, które kształtują wszystko, co następuje później.

Pole Co wpisaliśmy Uwaga
Nazwa Cold chain Używana dla repozytorium i katalogu
Przeznaczenie Kontenery chłodnicze przy nabrzeżu i na statkach: zasilanie, przekroczenia temperatury i wynikające z nich roszczenia
Branża Logistyka i gospodarka morska Opiera się na pakiecie Logistyka i transport morski
Właściciel (Owner) Osoba tworząca Zablokowane w kreatorze
Jednostki Rotterdam (pilotaż) Felixstowe po pilotażu
Szablon domain-pack@1.6.0 Zablokowany; aktualizacje przychodzą jako zmiany podlegające przeglądowi
Mapowane przepisy Umowa ATP, unijna dobra praktyka dystrybucyjna, dokumentacja bezpieczeństwa żywności Każdy przepis staje się stroną w mapie dowodów pakietu

Asystent w panelu bocznym zaproponował ostatni wiersz, łącznie z uwagą, że roszczenia ładunkowe wykorzystują te same zapisy przekroczeń. Tabliczka u dołu strony informuje, że nic nie zostało jeszcze utworzone. Repozytorium, przestrzeń deweloperska i gałęzie danych powstają dopiero po naciśnięciu przycisku Utwórz w kroku 3, gdy zapoznają się Państwo z planem. Mogą Państwo zapisać wersję roboczą i wrócić do niej później.

Krok 2: model wiedzy

Model wiedzy to zbiór rodzajów obiektów, o których pakiet ma wiedzę, oraz powiązań między nimi. Cold chain wyszedł od bazowego modelu logistycznego, logistics-base 4.2, zaimportowanego z SDK, który dał nam pięć rodzajów bazowych do rozbudowy (Vessel, Port, Container, Carrier i Shipment). Rodzaje bazowe są w kreatorze tylko do odczytu. Jeśli któryś wymaga zmiany, zmienia się go w pakiecie, który jest jego właścicielem.

Dodaliśmy pięć własnych rodzajów:

Rodzaj Czym to jest Właściwości
Reefer unit Kontener chłodniczy 9
Vessel call Jeden statek przy jednym stanowisku cumowniczym 6
Excursion Temperatura poza dopuszczalnymi granicami 8
Power supply Punkt zasilania z lądu lub ze statku 4
Przypisywanie Kwota żądana za zepsuty ładunek 7
Nowy pakiet domenowy: model wiedzy
Nowy pakiet domenowy: model wiedzy
Graf wiedzy z pięcioma rodzajami bazowymi i pięcioma nowymi. Proszę spojrzeć na właściwości Excursion po prawej: każda właściwość otrzymuje klasę w chwili utworzenia, a tabliczka informuje, że kwoty roszczeń są danymi handlowymi, więc soczewki dla techników nie mogą ich pokazywać.

Każda właściwość otrzymuje klasę w chwili tworzenia. „Zgłoszone przez” w Excursion to dana osobowa. „Wartość zagrożonego ładunku” oraz kwota i rozliczenie roszczenia to dane handlowe. Pierwszego dnia wydawało się to biurokracją, ale później dwukrotnie nas uratowało, ponieważ klasy decydują o tym, co może pokazać soczewka, co zastępuje kopia zamaskowana i co ukrywa wiersz dziennika.

Dwie z naszych relacji sięgają do modelu bazowego: Reefer unit jest podłączony do Power supply, a Claim odnosi się do Shipment. Sam model bazowy nie ulega zmianie. Wycofana właściwość pozostaje w wersji 1.0 modelu i znika dopiero w późniejszej wersji, dzięki czemu nic, co było prawdziwe w odniesieniu do starych rekordów, nie przestaje być czytelne.

Krok 3: przegląd i utworzenie

Krok 3 to plan. Wymienia on, co zostanie utworzone, zakresy, które zadeklaruje manifest, gałęzie danych i przestrzeń deweloperską. Plan potwierdzają Państwo kluczem dostępu (passkey), a plan otrzymuje odcisk cyfrowy. Tworzenie przebiega następnie dokładnie według tego planu, krok po kroku, i można je zatrzymać na dowolnym kroku, zachowując to, co już utworzono.

Plan dla Cold chain deklarował cztery zakresy:

Zakres Dlaczego pakiet go potrzebuje
Odczyt telemetrii kontenerów chłodniczych Odczyty zasilania i temperatury
Zapis przekroczeń Rejestruje przekroczenie, gdy granice zostaną przekroczone
Odczyt przesyłek Łączy roszczenie z jego przesyłką
Szkice not dotyczących roszczeń Tylko szkice; wysyła człowiek

Jego magazynami były graf i rekordy. Nie miał adresów wychodzących i korzystał z profilu piaskownicy Standard. Przestrzeń deweloperska otrzymała 4 rdzenie, 16 GiB pamięci i 50 GiB przestrzeni dyskowej, sieć zamkniętą z wyjątkiem tego, co deklaruje manifest, wyłącznie podpisane obrazy oraz zakończenie po 7 dniach bezczynności. Po jej zakończeniu definicja pozostaje w repozytorium, więc można ją stamtąd utworzyć ponownie.

Trzy gałęzie danych pochodziły z generatora danych syntetycznych. Nie skopiowano żadnych danych klientów. Zamaskowana kopia jednostki Rotterdam wymaga zgody właściciela danych, którym w Larkfield jest Priya Natarajan, i o tę zgodę należy wystąpić osobno.

Manifest pakietu

Repozytorium zawiera manifest pakietu, pack.json. Podaje on nazwę pakietu, jego wersję, pakiet, z którego dziedziczy (jeśli taki istnieje), jego klastry i jego słownictwo. Klaster jest albo soczewką, czyli tym, co widzi jedna rola w pakiecie, albo klastrem współdzielonym, który obejmuje wszystkie soczewki. Oto rdzeń naszego manifestu:

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

Leksykon zawiera własne słownictwo pakietu wraz z prostym objaśnieniem każdego terminu, na tyle krótkim, aby można je było przeczytać na telefonie.

Oprócz pack.json manifest deklaruje również, do czego pakiet może sięgać: jego zakresy, magazyny, adresy wychodzące i profil piaskownicy. Nexus przyznaje dokładnie to i nic więcej. Każde wywołanie narzędzia jest sprawdzane względem zadeklarowanych zakresów, a adres zewnętrzny jest blokowany, chyba że znajduje się na liście. Deklarację oraz zmiany względem ostatniego wydania można przejrzeć na stronie Manifest i uprawnienia danego pakietu.

Soczewki: co widzi każda rola

Soczewka może jedynie zawężać to, co pokazuje jej baza, i ta jedna zasada ukształtowała nasz projekt bardziej niż jakakolwiek inna. Soczewka pokazuje część tego, co pokazuje jej soczewka bazowa, a uprawnienia nadal wynikają z ról: soczewka decyduje o tym, co rola widzi w pakiecie, a nie o tym, co wolno jej robić.

Soczewka Reefer technician zawęża soczewkę Operations controller, czyli soczewkę bazową, której Larkfield już używa do prac logistycznych. W Kreatorze soczewek zaznacza się karty, pola i działania, które pokazuje soczewka. Elementy, których nie pokazuje baza, są zablokowane.

Element Reefer technician pokazuje Pominięte
Karty Kontenery chłodnicze przy nabrzeżu, otwarte przekroczenia, punkty zasilania, dzisiejsze zawinięcia statków Wszystko, co dotyczy roszczeń
Pola Stan zasilania, temperatura zadana, ostatni odczyt, najwyższa temperatura Kwota roszczenia (nie występuje w soczewce bazowej), pola osobowe (domyślnie wyłączone)
Działania Zarejestrowanie przyczyny przekroczenia, zlecenie kontroli zasilania Zmiana temperatury zadanej i zamknięcie przekroczenia (tylko kontrolerzy), szkic noty dotyczącej roszczenia
Kreator soczewek
Kreator soczewek
Kreator soczewek dla Reefer technician z zaznaczeniami względem soczewki bazowej. Tabliczka w lewym dolnym rogu to odmowa, którą otrzymuje się po zaznaczeniu kwoty roszczenia: soczewka bazowa jej nie pokazuje, więc ta soczewka również nie może.

Mimo to próbowałem dodać kwotę roszczenia do soczewki technika, ponieważ prosił o to jeden z techników. Kreator odmówił z kodem LENS_CANNOT_WIDEN i niczego nie zapisał. W obrębie soczewki nie ma obejścia: rozwiązaniem jest soczewka na szerszej bazie, czyli odrębny wniosek, o którym decyduje administrator organizacji. Zrezygnowaliśmy z tego.

Ukrycie czegoś w soczewce nie usuwa tego z Nexus. Oznacza jedynie, że dana rola tego nie widzi. Kreator pokazuje, do ilu osób soczewka dotrze w pilotażu (w naszym przypadku 29), i prowadzi dziennik każdej operacji Dodaj, Zmień i Wycofaj. Soczewkę definiuje się raz dla całej organizacji i przyznaje dla każdej jednostki określonej roli platformy, więc tę samą soczewkę Reefer technician można w tym miesiącu przydzielić technikom w Rotterdamie, a w następnym technikom w Felixstowe.

Umiejętność sporządzania projektów notatek szkodowych

Kontrolerzy chcieli otrzymywać pierwszy szkic noty wysyłanej do właściciela ładunku po przekroczeniu. To praca językowa, więc działa na modelu, a pytanie brzmiało, gdzie ją umieścić.

W Nexus istnieją dwa rodzaje umiejętności i różnica między nimi ma tu znaczenie. Umiejętność manifestu to typowany wiersz w pliku skills[] wtyczki, wywoływany przez platformę. Umiejętność Skills Engine to pakiet SKILL.md w bibliotece umiejętności organizacji, uruchamiany w ten sam sposób przez agentów, przyciski AI (sztucznej inteligencji), przepływy pracy i narzędzia programistyczne. Oba rodzaje opisuje rozdział 2.20, Umiejętności.

Poziom zaufania naszej wtyczki to community, a wtyczka społecznościowa może deklarować wyłącznie umiejętności manifestu, które nie sięgają do modelu (host_callback i plugin_queue). Dwa poziomy, które sięgają do AI Provider Router, tool_using i llm_only, wymagają zaufania core lub verified. Dlatego tworzenie szkiców not dotyczących roszczeń stało się umiejętnością Skills Engine, a router wybiera model z własnej puli 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.

Pakiet znajduje się w skills/draft-claim-note/ w repozytorium, a nazwa folderu jest równa nazwie umiejętności. Zweryfikowaliśmy go i przesłaliśmy z terminala:

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

Dwukrotne przesłanie tej samej zawartości zwraca istniejącą wersję zamiast nowej (CONTENT_HASH_ALREADY_PUBLISHED), więc ponowne uruchomienie przesyłania jest bezpieczne. Zanim wersja zostanie udostępniona, Skills Engine uruchamia jej przypadki testowe, przebieg próbny w trybie cienia na wcześniejszych zadaniach oraz ślepą ocenę przez model innej firmy, podając czas i koszt każdego przebiegu.

Wtyczka full-service

Pakiet potrzebował również kodu działającego bez przerwy: czytnika strumienia telemetrii kontenerów chłodniczych oraz modułu zapisującego, który otwiera rekord przekroczenia, gdy odczyt przekroczy granice. Taki kod należy do pełnej wtyczki usługowej, a jej szkielet utworzyliśmy własnym poleceniem SDK, które zapisuje całe drzewo referencyjne z podstawioną nazwą:

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

SDK instaluje się z https://registry.adverant.ai/npm/ przy użyciu tokenu pobierania ze strony Tokeny pobierania i polecenia instalacji w Państwa koncie Adverant. Proszę zatwierdzić (commit) plik package-lock.json zapisany przy pierwszej instalacji; budowanie obrazu uruchamia npm ci i bez niego kończy się odmową.

Oto ta część naszego nexus.manifest.json, która różni się od szablonu. Nie jest to cały plik: bloki description, author, license, runtime, backend i frontend z szablonu pozostają bez zmian, a walidator odrzuca manifest pełnej usługi bez nich. Trzy zdania architecture to zasada, którą powtarza każda wtyczka, a walidator sprawdza ich brzmienie. UNO w pierwszym z nich to silnik przepływów pracy:

{
  "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 to umiejętność manifestu z poziomem host_callback: platforma wysyła dane wejściowe do naszej własnej usługi Service, wewnątrz naszej przestrzeni nazw, i nigdy do hosta, który wskażemy. Trasa odbiorcza jest zadeklarowana jako auth: internal i chroniona przez serviceMiddleware z SDK, czyli wariant zabezpieczenia dla Express, który odrzuca token wywołania wystawiony dla innej wtyczki, organizacji, umiejętności lub trasy. Jej classification to tenant, co stanowi górną granicę dla wtyczki społecznościowej. Rozdział 2.27, Scenariusze budowania, omawia osobno umiejętność host_callback.

Warto przejąć dwa nawyki z tego etapu. Każda tabela zawiera organization_id, owner_user_id i business_unit_id od pierwszej migracji, ponieważ późniejsze dodanie osi oznacza migrację na żywych wierszach. Ponadto przed każdym wypchnięciem uruchamialiśmy lokalnie nexus-gates, ponieważ jest to to samo polecenie, które uruchamia potok; przebieg, który niczego nie zbadał, kończy się kodem 2 i to komunikuje. Rozdział 2.19, Zasady dziedziczone przez każde rozszerzenie, wymienia bramki.

Przykładowe dane do testów

Strona Przykładowe dane do testów oferuje trzy rodzaje gałęzi:

Rodzaj Co zawiera Kto wyraża zgodę
Syntetyczne Dane wygenerowane na podstawie ustawionych przez Państwa liczności i kształtów; nic nie pochodzi z rzeczywistej jednostki Nikt; należą do Państwa
Kopia zamaskowana Kopia jednostki z zastąpionymi polami osobowymi, wrażliwymi i handlowymi Właściciel danych (Priya Natarajan dla Rotterdamu)
Tylko schemat Kształt magazynów danych, bez wierszy Nikt; do migracji

Wygenerowaliśmy pracowity tydzień: około 7 odchyleń na każde 100 kontenerów chłodniczych, co odpowiada pracowitemu sierpniowi w Rotterdamie. Nietypowe przypadki miały większe znaczenie niż wolumen. Poprosiliśmy o utratę zasilania podczas rozładunku, pozostawione otwarte drzwi, lukę w danych z czujnika oraz dwa roszczenia dotyczące jednego odchylenia. Strona może proponować nietypowe przypadki na podstawie przyczyn odchyleń w modelu wiedzy, nigdy na podstawie rzeczywistych rekordów.

Każdy zestaw liczności i kształtów jest zapisywany jako ziarno, na przykład cold-chain-busy-01, wraz z odciskiem. To samo ziarno daje te same dane, więc każdy przebieg testów w każdej gałęzi widzi ten sam tydzień. Dzięki temu nasze 66 testów było powtarzalnych.

Gałąź istnieje domyślnie 72 godziny, a maksymalnie 14 dni. Poprosiłem o zachowanie naszej gałęzi z pracowitym tygodniem przez 30 dni na czas długiego przeglądu, a strona odmówiła z kodem BRANCH_LIFE_EXCEEDED. Rozwiązanie jest takie, jakie sugeruje komunikat: zachować ziarno i w razie potrzeby utworzyć z niego nową gałąź. Kopia zamaskowana podlega tym samym limitom, a jej wniosek zawiera uzasadnienie i okres do 14 dni.

Podgląd soczewki z perspektywy konkretnej osoby

Zanim ktokolwiek w Rotterdamie zobaczył Cold chain, przyjrzeliśmy się mu tak, jak oni by to zrobili. Funkcja Podgląd soczewki jako osoba renderuje pakiet dokładnie tak, jak widzi go wybrana rola, na gałęzi danych, wewnątrz przerywanej ramki podglądu.

Podgląd soczewki jako osoba
Podgląd soczewki z perspektywy konkretnej osoby
Cold chain z perspektywy technika kontenerów chłodniczych w Rotterdamie, na gałęzi syntetycznej. Proszę zwrócić uwagę na kolumnę roszczeń oznaczoną „ukryte przez soczewkę” przy każdym otwartym odchyleniu oraz na panel boczny, który informuje, co ta soczewka ukrywa i dlaczego.

Trzy zasady sprawiają, że z podglądów można swobodnie korzystać. Podgląd używa gałęzi danych, nigdy działającej jednostki. Państwa własne uprawnienia nie przenikają do niego, więc widzą Państwo to, co widzi rola, a nie to, co mogą zobaczyć Państwo. Ponadto podgląd kończy się po 30 minutach. Wskazanie działającej jednostki jako źródła podglądu jest odrzucane z kodem CONNECTION_SCOPE_EXCEEDED; jeśli potrzebują Państwo rzeczywistych kształtów danych, proszę poprosić właściciela danych o kopię zamaskowaną i wykonać podgląd na niej.

To właśnie w podglądzie wykryliśmy prawdziwy błąd. Wykres temperatury w widoku technika pokazywał wartość zadaną, a edycja wartości zadanej miała być dostępna wyłącznie dla kontrolerów. Wykres był w porządku; przycisk edycji pod nim już nie. Wersja 0.3.2 ukryła edycję wartości zadanej przed technikami, a błąd znaleźliśmy właśnie w podglądzie.

Zmiana modelu wiedzy po wdrożeniu

W wersji 0.4.0 potrzebowaliśmy rodzaju Inspection dla inspekcji przed transportem, a relacja „Excursion caused Claim” lepiej brzmiała jako „Excursion led to Claim”. Przejście modelu z 1.3 na 1.4 jest zmianą modelu wiedzy, a strona Zmiany modelu wiedzy pokazuje jej różnice, co by objęła i na jakim jest etapie.

Zmiana przechodzi jako wniosek o zmianę grafu. Jej przebieg próbny zlicza, co by objęła w kopii zamaskowanej Rotterdamu, w postaci liczb: w naszym przypadku 1,284 przemianowane powiązania i nic usuniętego. Dwóch recenzentów ją zatwierdza, a potok stosuje ją do środowiska staging, a następnie do pilota. Nikt nie zapisuje ręcznie do współdzielonego grafu; taka próba jest odrzucana i rejestrowana. Trzy zapisane pytania używały słowa „caused”, a zmiana zawierała automatyczne przepisanie każdego z nich, które strona wymieniła. Filtry soczewek się nie zmieniły, ponieważ obie soczewki nadal jedynie zawężały.

Promocja na środowisko produkcyjne

Każde wydanie przechodzi jedną ścieżką: przestrzeń deweloperska, staging, jednostka pilotażowa, a następnie wszystkie jednostki. Każdy krok ma bramki i żadnej nie można pominąć.

Do Bramki
Staging Wszystkie testy zaliczone; kontrole jakości; manifest bez zmian lub zaakceptowane rozszerzenie; podpisany obraz
Pilot (Rotterdam) Przebieg próbny zmiany modelu na kopii zamaskowanej bez błędów; kontrola zasad dotyczących soczewek i zakresu; dwóch recenzentów niebędących autorem, w tym właściciel danych
Wszystkie jednostki 14 dni w pilocie; błędy poniżej 1 na 1,000, liczone w pilocie; zgoda administratora każdej jednostki dla jego jednostki; dwóch recenzentów niebędących autorem
Środowiska i promocja
Środowiska i promocja
Cold chain 0.3.2 oczekuje przy bramce pilota na drugiego recenzenta. Komunikat po prawej to odmowa przy próbie promocji bezpośrednio z przestrzeni deweloperskiej do wszystkich jednostek.

Raz, w piątek, spróbowałem skrótu dla jednowierszowej poprawki: promować 0.4.0-dev z mojej przestrzeni deweloperskiej do wszystkich jednostek. Operacja została odrzucona z kodem GATE_CANNOT_BE_SKIPPED i nic nie zostało promowane. Komunikat zaleca zamiast tego promocję do następnego kroku i jest to jedyne dostępne rozwiązanie.

Sam przegląd wydania, dowody, które czyta drugi recenzent, oraz kanały wybierane przez jednostki opisano w rozdziale 2.28, Wydawanie rozszerzenia. Dwa fakty z niego należą jednak tutaj, ponieważ wpływają na planowanie branży. Autor nigdy nie jest liczony jako recenzent, więc dwuosobowy zespół potrzebuje trzeciej osoby przy każdym wydaniu. Ponadto każde środowisko przechowuje poprzednią wersję przez 30 dni, więc wycofanie jest zrecenzowaną zmianą, którą potok wykonuje w około minutę.

Rozszerzanie istniejącego pakietu

Nie każda branża zaczyna od zera. Pakiet może dziedziczyć po innym i dodawać tylko to, co się różni. Pakiet Bankowość i płatności, z którego korzysta Larchmont Bank, jest najwyraźniejszym przykładem w katalogu. Jego manifest zaczyna się tak:

{
  "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 wskazuje pakiet, na którym się opiera. Bankowość i płatności zachowuje kształt pakietu Ubezpieczenia, jego współdzielone klastry konwersacji i podstawowe słownictwo, a dodaje trzy własne soczewki: Decyzje kredytowe, Spory kartowe i Moje konto. Trzeci element każdego wpisu leksykonu to exact dla terminu, który musi być wyświetlany w niezmienionej postaci, na przykład APR (rzeczywista roczna stopa oprocentowania), a nie przeformułowany.

Niektórych rzeczy nie da się osiągnąć przez dziedziczenie. Pakiet nigdy nie zmienia powłoki, komponentów ani zasad redakcyjnych, więc pakiet potomny nie może zmienić stylu konsoli. Reżim regulacyjny potrzebny kilku pakietom to jedna współdzielona soczewka, a nie kopia w każdym z nich: rejestr outsourcowanych technologii obsługuje zarówno Ubezpieczenia, jak i Bankowość i płatności. Jeśli Państwa pakiet potomny potrzebuje soczewki, która już istnieje jako współdzielona, proszę jej użyć zamiast tworzyć własną.

Licencjonowanie podąża za dziedziczeniem. Pakiet jest licencjonowany na bazie Enterprise i może wymagać dodatków, a dokument licencji zawiera te zależności. Ubezpieczenia wymagają dodatku Pokoje decyzyjne i zapieczętowane rekordy, więc klient licencjonujący pakiet, który po nim dziedziczy, również potrzebuje tego dodatku, a konsola odmawia wystawienia licencji, która go pomija. Ekrany telefoniczne pakietu wymagają ponadto dodatku Aplikacje mobilne. Proszę sprawdzić łańcuch wymagań, zanim obiecają Państwo klientowi termin.

Dodawanie soczewki do wdrożonego pakietu

Najmniejszą pracą branżową jest nowa soczewka w pakiecie, którego nie napisali Państwo sami. Sześć miesięcy po rozpoczęciu pilota zespół ds. roszczeń morskich Larkfield chciał mieć własną soczewkę w Cold chain: odchylenia i roszczenia, bez punktów zasilania i bez wartości zadanych. Nie dotknęliśmy kodu pakietu. Soczewka to wiersz w rejestrze soczewek organizacji, należący do pakietu, więc zaczęliśmy od złotej ścieżki dla soczewek na stronie Rozpocznij coś nowego i ukształtowaliśmy ją w Kreatorze soczewek, przyjmując soczewkę kontrolera Cold-chain jako bazę. Obowiązuje ta sama zasada co wcześniej: nowa soczewka może ukrywać to, co pokazuje jej baza, i nigdy nie może pokazywać więcej. Jest definiowana raz dla organizacji i przyznawana roli platformy w każdej jednostce. Przyznanie jest wycofywane, nigdy usuwane, a ponowne nadanie soczewki tworzy nowe przyznanie, dzięki czemu informacja, kto i kiedy posiadał którą soczewkę, pozostaje czytelna. Rejestr zlicza, ile osób posiadało soczewkę w każdym miesiącu, nigdy kto.

Strona Soczewki i kto je widzi przedstawia wynik jako macierz soczewek według jednostki i roli, z opcjami Dodaj, Zmień i Wycofaj w każdej komórce. Przed przyznaniem nowej soczewki proszę wykonać jej podgląd jako osoba, dokładnie jak powyżej.

Rzeczywiste koszty

Pakiet ma dostęp do rekordów klienta, dlatego platforma celowo spowalnia niektóre działania i należy to uwzględnić w planach od pierwszego dnia.

  1. Kopia zamaskowana za każdym razem wymaga zgody właściciela danych. Za pierwszym razem na naszą czekaliśmy dzień, ponieważ Priya chciała najpierw zapoznać się z modelem wiedzy. Proszę zacząć od danych syntetycznych i wystąpić o zgodę wcześnie.
  2. Autor nie może zatwierdzić własnego wydania, a wnioski wygasają po 3 dniach. Jeśli Państwa recenzenci są zajęci, wydanie czeka.
  3. Wydanie, które wymaga więcej niż poprzednie, na przykład wysyłania poczty lub jednego adresu zewnętrznego, jest wstrzymywane, dopóki dwóch recenzentów nie zaakceptuje rozszerzonego manifestu. Rozdział 2.28, Wydawanie rozszerzenia, przedstawia stronę Manifest i uprawnienia, która informuje o tym, zanim złożą Państwo wniosek.
  4. Soczewka nie może pokazywać tego, co ukrywa jej soczewka bazowa. Jeśli rola rzeczywiście potrzebuje więcej, jest to kwestia do omówienia z administratorem organizacji, a nie ustawienie.

Żadne z tych ograniczeń nie przeszkodziło nam dwukrotnie. Drugie wydanie Cold chain zajęło tydzień od pierwszego commitu do pilota w Rotterdamie, głównie na uruchomienie 66 testów na trzech gałęziach i lekturę dowodów przez dwie osoby.