Wersja 1.0.0-alpha.1najnowsza
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

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.
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ć.
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 |
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 |
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-noteDwukrotne 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-testSDK 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.
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 |
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.
- 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.
- Autor nie może zatwierdzić własnego wydania, a wnioski wygasają po 3 dniach. Jeśli Państwa recenzenci są zajęci, wydanie czeka.
- 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.
- 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.




