Iniciar sessãoAgendar apresentação

Capítulo 2.24

Construir uma solução vertical personalizada de ponta a ponta

Uma construção prática do pacote de domínio Cold chain, desde o primeiro caderno de encargos até uma versão em execução para todas as unidades, com o seu modelo de conhecimento, lentes, uma competência, um plugin de serviço completo e dados de exemplo. Depois, como estender um pacote já existente e como adicionar uma lente a um pacote que já foi lançado.

Esta página foi traduzida por IA a partir do original em inglês. Em caso de dúvida, a página em inglês serve de referência. Ler esta página em inglês

19 minutos de leitura

Chamo-me Mateo Ruiz e sou programador na Corrán Orbital. A maior parte da minha semana é dedicada ao nosso próprio software de carga útil, mas este capítulo é sobre um trabalho que fizemos para um cliente. A Larkfield & Vane assegura carga, e uma parte crescente da mesma viaja em contentores refrigerados. Quando um contentor refrigerado perde a energia de terra no cais, a temperatura sobe, a carga estraga-se e uma reclamação surge semanas depois. A Larkfield queria que as suas pessoas vissem essa cadeia como uma única coisa no Nexus, desde a falha de energia até à reclamação, em que cada função vê apenas a sua parte. Isso tornou-se o pacote Cold chain.

O que se segue é a construção pela ordem em que a fizemos, com os ecrãs, os ficheiros e os comandos. Mantive os erros, porque duas das recusas com que nos deparámos ensinaram-nos mais sobre a plataforma do que o caminho ideal. O material de referência encontra-se nos capítulos anteriores a este, e aponto para eles em vez de os repetir. Aqueles em que mais me apoiei foram o capítulo 2.18, O modelo de extensão, e o capítulo 2.23, Pacotes de domínio, com o capítulo 2.21, O SDK de Plugins, aberto ao lado deles para o próprio kit de desenvolvimento de software.

Um percurso da esquerda para a direita com oito caixas: "Brief", "Golden path", "Knowledge model", "Lenses", "Skill and plugin", "Sample data and preview", "Release review", "Promotion". Sob a última caixa, uma segunda linha de quatro caixas mais pequenas unidas por setas mostra os passos de promoção: "Dev space", "Staging", "Pilot unit (Rotterdam)", "All units", com um ícone de cadeado em cada seta identificado como "gate". Uma seta tracejada desde "Dev space" diretamente para "All units" está riscada e identificada como GATE_CANNOT_BE_SKIPPED.
A construção do Cold chain, desde o resumo até a cada unidade.

O caderno de encargos e quem faz o quê

A Larkfield deu-me um lugar de programador na sua organização durante a duração do projeto. Isso é importante, porque um pacote privado para um cliente é construído dentro da instalação desse cliente, nos seus espaços de desenvolvimento e ramos de dados, sob as aprovações das suas pessoas. Um pacote destinado a muitos clientes é construído de forma diferente, num cluster de editor apenas com dados de amostra, e o capítulo 2.25, Construir para cada edição, aborda esse caso.

O resumo cabia numa página:

  • Contentores refrigerados no cais e em navios: a sua energia, os seus desvios de temperatura e as reclamações que se seguem.
  • Duas funções para começar: um técnico de contentores refrigerados no cais e um controlador da cadeia de frio no escritório.
  • Um piloto que é executado primeiro na unidade de Roterdão e passa para Felixstowe depois.
  • Evidências para três conjuntos de regras: o acordo ATP para alimentos perecíveis, as boas práticas de distribuição da UE para medicamentos e os registos de segurança alimentar ao abrigo do HACCP (análise de perigos e pontos críticos de controlo). As reclamações ao abrigo das regras de Haia-Visby utilizam os mesmos registos de desvios, pelo que as anotámos para depois do piloto.

Os pacotes de domínio são uma capacidade Enterprise. A Larkfield executa o Enterprise, pelo que o caminho do pacote de domínio estava aberto para mim. Na edição Community, o caminho padrão para um pacote não é de todo oferecido.

Começar pelo caminho ideal

Tudo começa na página Começar algo novo. Oferece seis caminhos padrão: plugin, pacote de domínio, lente, plataforma, competência e fluxo de trabalho. Cada um cria um repositório a partir de um modelo versionado, um manifesto que declara o que o elemento precisa, testes, um espaço de desenvolvimento e ramos de dados. Os mesmos caminhos funcionam na consola, na linha de comandos e a partir do seu IDE (ambiente de desenvolvimento integrado), onde a ferramenta Workbench nexus.create faz o mesmo trabalho com um plano que confirma primeiro.

Começar algo novo
Começar algo novo
Os seis caminhos padrão, cada um com o que cria, o seu comando nexus create e o seu modelo fixado. Repare no aviso no rodapé: o manifesto é imposto, não consultivo, e um lançamento que peça mais é retido até que duas pessoas o revejam.

Seguimos o caminho do pacote de domínio a partir dessa página, dando ao pacote o nome cold-chain e à sua primeira unidade Roterdão. O resultado indica o modelo fixado, domain-pack@1.6.0, e lista o que criou: o repositório, um manifesto que declara quatro âmbitos, dois armazenamentos e nenhum endereço de saída, 66 testes a partir do modelo, um espaço de desenvolvimento em Roterdão, três ramos de dados sintéticos e uma entrada de rascunho no catálogo próprio da Larkfield que só eu podia ver. A versão do modelo é fixada e a sua atualização posterior chega como uma alteração revista como qualquer outra, para que o pacote de ninguém mude sem aviso porque um modelo mudou. De qualquer forma, utilizei o assistente da consola para o nosso primeiro pacote, porque mostra o plano antes de criar seja o que for.

Passo 1: indicar para que serve o pacote

O assistente Novo pacote de domínio tem três passos: sobre o pacote, modelo de conhecimento e rever e criar. O passo 1 pergunta as poucas coisas que moldam tudo o que se segue.

Campo O que introduzimos Nota
Nome Cadeia de frio Utilizado para o repositório e o catálogo
Para que serve Contentores refrigerados no cais e em navios: energia, desvios de temperatura e as reclamações que se seguem
Setor Logística e setor marítimo Baseia-se no pacote Logística e marítimo
Proprietário A pessoa que o cria Bloqueado no assistente
Unidades Roterdão (piloto) Felixstowe após o piloto
Modelo domain-pack@1.6.0 Bloqueado; as atualizações chegam como alterações revistas
Regras que mapeia Acordo ATP, boas práticas de distribuição da UE, registos de segurança alimentar Cada regra torna-se uma página no mapa de evidências do pacote

O assistente no painel sugeriu a última linha, incluindo o ponto de que as reclamações de carga reutilizam os mesmos registos de desvios. Um aviso no rodapé da página diz que ainda nada foi criado. O repositório, o espaço de desenvolvimento e os ramos de dados só são criados quando prime Criar no passo 3, depois de ter visto o plano. Pode guardar um rascunho e voltar mais tarde.

Passo 2: o modelo de conhecimento

O modelo de conhecimento é o conjunto de tipos de elementos que o pacote conhece e como se interligam. O Cold chain partiu do modelo base de logística, logistics-base 4.2, importado do SDK, que nos deu cinco tipos base sobre os quais construir (Navio, Porto, Contentor, Transportador e Expedição). Os tipos base são só de leitura no assistente. Se um precisar de mudar, muda no pacote que o detém.

Adicionámos cinco tipos nossos:

Tipo O que é Propriedades
Unidade refrigerada Um contentor refrigerado 9
Escala de navio Um navio num posto de acostagem 6
Desvio Uma temperatura fora dos seus limites 8
Fornecimento de energia Um ponto de energia em terra ou no navio 4
Associar Dinheiro pedido por carga estragada 7
Novo pacote de domínio: modelo de conhecimento
Novo pacote de domínio: modelo de conhecimento
O grafo de conhecimento com cinco tipos base e cinco novos. Observe as propriedades de Desvio à direita: cada propriedade recebe a sua classe à medida que é criada, e o aviso indica que os montantes de reclamação são comerciais, pelo que as lentes de técnico não os podem mostrar.

Cada propriedade é classificada à medida que a cria. "Comunicado por" num Desvio é pessoal. "Valor da carga em risco" e o montante e liquidação de uma reclamação são comerciais. Isto pareceu burocracia no primeiro dia e salvou-nos duas vezes mais tarde, porque as classes decidem o que uma lente pode mostrar, o que uma cópia mascarada substitui e o que uma linha de registo oculta.

Duas das nossas relações estendem-se ao modelo base: uma Unidade refrigerada está ligada a um Fornecimento de energia e uma Reclamação refere-se a uma Expedição. O próprio modelo base não é alterado. Uma propriedade que retire permanece na versão 1.0 do modelo e só sai numa versão posterior, para que nada do que era verdadeiro em registos antigos deixe de ser legível.

Passo 3: rever e criar

O passo 3 é o plano. Lista o que será criado, os âmbitos que o manifesto irá declarar, os ramos de dados e o espaço de desenvolvimento. Confirma o plano com a sua chave de acesso e o plano recebe uma impressão digital. A criação segue então esse plano exatamente, um passo de cada vez, e pode parar em qualquer passo e manter o que foi criado.

O plano para o Cold chain declarou quatro âmbitos:

Âmbito Porque é que o pacote precisa dele
Ler telemetria de contentores refrigerados Leituras de energia e temperatura
Escrever desvios Regista um desvio quando os limites são ultrapassados
Ler expedições Liga uma reclamação à sua expedição
Elaborar rascunhos de notas de reclamação Apenas rascunhos; uma pessoa envia

Os seus armazenamentos eram o grafo e os registos. Não tinha endereços de saída e tinha o perfil de sandbox Standard. O espaço de desenvolvimento vinha com 4 núcleos, 16 GiB de memória e 50 GiB de armazenamento, uma rede fechada exceto para o que o manifesto declara, apenas imagens assinadas e um fim após 7 dias de inatividade. Quando termina, a sua definição permanece no repositório, pelo que o cria novamente a partir daí.

Os três ramos de dados vieram do gerador sintético. Nenhum dado de cliente foi copiado. Uma cópia mascarada de Roterdão precisa do acordo do proprietário dos dados, que na Larkfield é Priya Natarajan, e pede-se separadamente.

O manifesto do pacote

O repositório guarda o manifesto do pacote, pack.json. Nomeia o pacote, a sua versão, o pacote de que herda (se existir), os seus agrupamentos e as suas palavras. Um agrupamento é ou uma lente, que é o que uma função vê dentro do pacote, ou partilhado, que é executado em todas as lentes. Aqui está o núcleo do nosso:

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

O léxico guarda as palavras próprias do pacote com uma explicação simples para cada uma, suficientemente curta para ser lida num telemóvel.

Ao lado de pack.json, o manifesto também declara o que o pacote pode alcançar: os seus âmbitos, armazenamentos, endereços de saída e perfil de sandbox. O Nexus concede exatamente isso e nada mais. Cada chamada de ferramenta é verificada em relação aos âmbitos declarados, e um endereço externo é bloqueado a menos que esteja listado. Pode ler a declaração, e a alteração em relação ao último lançamento, na página Manifesto e permissões do pacote.

Lentes: o que cada papel vê

Uma lente só pode restringir o que a sua base mostra, e essa única regra moldou mais o nosso desenho do que qualquer outra. Uma lente mostra uma parte do que a sua lente base mostra, e as permissões continuam a vir das funções: uma lente decide o que uma função vê no pacote, não o que tem permissão para fazer.

A lente Técnico de contentores refrigerados restringe Controlador de operações, a lente base que a Larkfield já executa para o trabalho de logística. No Construtor de lentes, assinala os cartões, campos e ações que a lente mostra. Os itens que a base não mostra estão bloqueados.

Componente Técnico de contentores refrigerados mostra Deixado de fora
Cartões Unidades refrigeradas no cais, desvios abertos, pontos de energia, escalas de navios hoje Qualquer coisa sobre reclamações
Campos Estado da energia, ponto de regulação, última leitura, temperatura mais alta Montante da reclamação (não está na lente base), campos pessoais (desativados por predefinição)
Ações Registar uma causa de desvio, pedir uma verificação de energia Alterar um ponto de regulação e fechar um desvio (apenas controladores), elaborar rascunho de uma nota de reclamação
Construtor de lentes
Construtor de lentes
O Construtor de lentes para Técnico de contentores refrigerados, assinalado em relação à sua lente base. O aviso no canto inferior esquerdo é a recusa que obtém por assinalar o montante da reclamação: a lente base não o mostra, pelo que esta lente não o pode fazer.

Tentei adicionar o montante da reclamação à lente de técnico de qualquer forma, porque um técnico o tinha pedido. O construtor recusou com LENS_CANNOT_WIDEN e não guardou nada. Não há solução alternativa dentro da lente: o caminho a seguir é uma lente numa base mais ampla, um pedido diferente que o administrador da organização decide. Deixámo-lo de fora.

Ocultar algo numa lente não o remove do Nexus. Significa que esta função não o vê. O construtor mostra quantas pessoas uma lente alcançará no piloto (29, no nosso caso) e mantém um registo de cada Adição, Alteração e Retirada. Uma lente é definida uma vez para a organização e concedida por unidade a uma função da plataforma, para que a mesma lente de Técnico de contentores refrigerados possa ser atribuída aos técnicos de Roterdão este mês e aos de Felixstowe no próximo.

Uma competência para redigir notas de reclamação

Os controladores queriam um primeiro rascunho da nota que vai para o proprietário da carga após um desvio. Isso é trabalho de linguagem, pelo que é executado num modelo, e a questão era onde o colocar.

Existem dois tipos de competência no Nexus, e a diferença é importante aqui. Uma competência de manifesto é uma linha tipada no skills[] de um plugin, despachada pela plataforma. Uma competência do Motor de Competências é um pacote SKILL.md na biblioteca de competências da organização, que agentes, botões de IA (inteligência artificial), fluxos de trabalho e ferramentas de programador executam todos da mesma forma. O Capítulo 2.20, Competências, aborda ambos.

A confiança do nosso plugin é community, e um plugin comunitário só pode declarar competências de manifesto que não alcancem um modelo (host_callback e plugin_queue). Os dois níveis que alcançam o Encaminhador de Fornecedores de IA, tool_using e llm_only, precisam de confiança core ou verified. Assim, a elaboração de rascunhos de notas de reclamação tornou-se uma competência do Motor de Competências, e o encaminhador escolhe o modelo do conjunto próprio da 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.

O pacote reside em skills/draft-claim-note/ no repositório, com o nome da pasta igual ao nome da competência. Validámo-lo e carregámo-lo a partir do terminal:

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

Carregar o mesmo conteúdo duas vezes devolve a versão existente em vez de uma nova (CONTENT_HASH_ALREADY_PUBLISHED), pelo que voltar a executar o carregamento é seguro. Antes de uma versão sair, o Motor de Competências executa os seus casos de teste, um ensaio em modo sombra sobre trabalho passado e uma revisão cega por um modelo de outra empresa, com o tempo e o custo de cada execução.

O plugin de serviço completo

O pacote também precisava de código que fosse executado a tempo inteiro: um leitor para o feed de telemetria dos contentores refrigerados e um escritor que abre um registo de desvio quando uma leitura ultrapassa os seus limites. Código como esse pertence a um plugin de serviço completo, e criámos a sua estrutura base com o comando próprio do SDK, que escreve toda a árvore de referência com o nome substituído:

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

O SDK instala-se a partir de https://registry.adverant.ai/npm/ com o token de extração da página Tokens de extração e comandos de instalação da sua conta Adverant. Registe no repositório o package-lock.json que a primeira instalação escreve; a construção da imagem executa npm ci e recusa sem um.

Aqui está a parte do nosso nexus.manifest.json que difere do modelo. Não é o ficheiro inteiro: os blocos description, author, license, runtime, backend e frontend da estrutura base permanecem como estão, e o validador recusa um manifesto de serviço completo sem eles. As três frases architecture são a regra que cada plugin reafirma, e o validador verifica a redação. O UNO na primeira é o motor de fluxo de trabalho:

{
  "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 é uma competência de manifesto com o nível host_callback: a plataforma publica a entrada no nosso próprio Serviço, dentro do nosso espaço de nomes, e nunca num anfitrião que nomeemos. A rota recetora é declarada auth: internal e protegida com o serviceMiddleware do SDK, a forma Express da proteção, que recusa um token de chamada emitido para qualquer outro plugin, organização, competência ou rota. O seu classification é tenant, que é o limite máximo para um plugin comunitário. O Capítulo 2.27, Cenários de construção, percorre uma competência host_callback por si só.

Dois hábitos desta fase valem a pena copiar. Cada tabela transporta organization_id, owner_user_id e business_unit_id desde a primeira migração, porque adicionar um eixo mais tarde é uma migração sobre linhas ativas. E executámos nexus-gates localmente antes de cada envio, uma vez que é o mesmo comando que o pipeline executa; uma execução que não examinou nada termina com o código 2 e indica-o. O Capítulo 2.19, As regras que cada extensão herda, lista os portões de controlo.

Dados de exemplo para testes

A página Dados de amostra para testes oferece três tipos de ramo:

Tipo O que contém Quem concorda
Sintético Dados gerados a partir de contagens e formas que define; nada vem de uma unidade real Ninguém; é seu
Cópia mascarada Uma cópia de uma unidade com campos pessoais, sensíveis e comerciais substituídos O proprietário dos dados (Priya Natarajan para Roterdão)
Apenas esquema A forma dos armazenamentos, sem linhas Ninguém; para migrações

Gerámos uma semana movimentada: cerca de 7 desvios em cada 100 contentores refrigerados, que é como se parece um agosto movimentado em Roterdão. Os casos atípicos importavam mais do que o volume. Pedimos perda de energia durante a descarga, uma porta deixada aberta, uma falha no sensor e duas reclamações para um desvio. A página pode sugerir casos atípicos a partir das causas de desvio no modelo de conhecimento, nunca a partir de registos reais.

Cada conjunto de contagens e formas é guardado como uma semente, tal como cold-chain-busy-01, com a sua impressão digital. A mesma semente dá os mesmos dados, pelo que cada execução de teste em cada ramo vê a mesma semana. Foi isso que tornou os nossos 66 testes repetíveis.

Um ramo dura 72 horas por predefinição e 14 dias no máximo. Pedi para manter o nosso ramo movimentado durante 30 dias durante uma longa revisão, e a página recusou com BRANCH_LIFE_EXCEEDED. A solução é a que o aviso sugere: mantenha a semente e crie um novo ramo a partir dela quando precisar de um. Uma cópia mascarada segue os mesmos limites, e o seu pedido inclui um motivo e uma duração de até 14 dias.

Pré-visualizar uma lente como uma pessoa

Antes de alguém em Roterdão ver o Cold chain, olhámos para ele como eles olhariam. Pré-visualizar uma lente como uma pessoa apresenta o pacote exatamente como uma função escolhida o vê, num ramo de dados, dentro de uma moldura de pré-visualização tracejada.

Pré-visualizar uma lente como uma pessoa
Pré-visualizar uma lente como uma pessoa
O Cold chain como um técnico de contentores refrigerados de Roterdão o vê, num ramo sintético. Repare na coluna de reclamação marcada como "ocultado pela lente" em cada desvio aberto, e no painel lateral que diz o que esta lente oculta e porquê.

Três regras tornam as pré-visualizações seguras para utilizar livremente. Uma pré-visualização utiliza um ramo de dados, nunca a unidade ativa. As suas próprias permissões não passam para ela, pelo que vê o que a função vê e não o que você pode ver. E termina após 30 minutos. Apontar uma pré-visualização para uma unidade ativa é recusado com CONNECTION_SCOPE_EXCEEDED; se precisar de formas reais, peça ao proprietário dos dados uma cópia mascarada e faça a pré-visualização nessa cópia.

A pré-visualização foi onde detetámos um erro real. O gráfico de temperatura na vista do técnico mostrava o ponto de regulação, e as edições do ponto de regulação destinavam-se apenas aos controladores. O gráfico estava bem; o botão de edição por baixo dele não estava. A versão 0.3.2 ocultou as edições do ponto de regulação dos técnicos, e a pré-visualização foi onde o encontrámos.

Alterar o modelo de conhecimento após o lançamento

Na versão 0.4.0 precisávamos de um tipo Inspeção para inspeções pré-viagem, e a relação "Desvio causou Reclamação" lia-se melhor como "Desvio levou a Reclamação". Passar o modelo de 1.3 para 1.4 é uma alteração ao modelo de conhecimento, e a página Alterações ao modelo de conhecimento mostra as suas diferenças, o que afetaria e onde se encontra no seu percurso.

A alteração viaja como um pedido de alteração ao grafo. O seu ensaio conta o que afetaria na cópia mascarada de Roterdão, em forma de contagens: para nós, 1284 ligações renomeadas e nada removido. Dois revisores aprovam-na, e o pipeline aplica-a ao ambiente de preparação e, em seguida, ao piloto. Ninguém escreve no grafo partilhado manualmente; uma tentativa é recusada e registada. Três perguntas guardadas utilizavam a palavra "causou", e a alteração incluiu uma reescrita automática para cada uma delas, que a página listou. Os filtros das lentes não mudaram, porque ambas as lentes continuavam apenas a restringir.

Promover para produção

Cada lançamento move-se ao longo de um único caminho: espaço de desenvolvimento, preparação, uma unidade piloto e, em seguida, todas as unidades. Cada passo tem portões de controlo e nada salta nenhum.

Para Barreiras de controlo
Preparação Todos os testes passam; verificações de qualidade; manifesto inalterado ou o alargamento aceite; imagem assinada
Piloto (Roterdão) Ensaio de alteração ao modelo na cópia mascarada sem erros; verificação de políticas nas regras de lente e âmbito; dois revisores que não sejam o autor, sendo um deles o proprietário dos dados
Todas as unidades 14 dias no piloto; erros abaixo de 1 em 1.000, contados no piloto; cada administrador de unidade concorda para a sua unidade; dois revisores que não sejam o autor
Ambientes e promoção
Ambientes e promoção
O Cold chain 0.3.2 a aguardar no portão do piloto pelo seu segundo revisor. O aviso à direita é a recusa por tentar promover diretamente de um espaço de desenvolvimento para todas as unidades.

Tentei o atalho uma vez, numa sexta-feira, para uma correção de uma linha: promover a 0.4.0-dev do meu espaço de desenvolvimento para todas as unidades. Foi recusado com GATE_CANNOT_BE_SKIPPED, e nada foi promovido. O aviso diz-lhe para promover antes para o passo seguinte, e essa é a única resposta que existe.

A revisão do lançamento em si, as evidências que um segundo revisor lê e os canais que as unidades escolhem estão no capítulo 2.28, Lançar a sua extensão. Dois factos desse capítulo pertencem aqui, porque moldam a forma como planeia uma solução vertical. O autor nunca conta como revisor, pelo que uma equipa de duas pessoas precisa de uma terceira pessoa para cada lançamento. E cada ambiente mantém a versão anterior durante 30 dias, pelo que reverter é uma alteração revista que o pipeline faz em cerca de um minuto.

Estender um pacote já existente

Nem toda a solução vertical começa do zero. Um pacote pode herdar de outro e adicionar apenas o que é diferente. O pacote Banca e pagamentos, que o Larchmont Bank executa, é o exemplo mais claro no catálogo. O seu manifesto começa assim:

{
  "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 nomeia o pacote sobre o qual se baseia. O pacote Banca e pagamentos mantém a forma do pacote Seguros, os seus agrupamentos de conversação partilhados e as suas palavras principais, e adiciona três lentes próprias: Decisões de crédito, Disputas de cartões e A minha conta. O terceiro elemento de cada entrada do léxico é exact para um termo que deve ser mostrado como está escrito, tal como APR (taxa anual de encargos efetiva global), em vez de ser reformulado.

Há algumas coisas que não pode fazer por herança. Um pacote nunca altera a interface base, os componentes ou as regras de escrita, pelo que um pacote derivado não pode mudar o estilo da consola. Um regime de que vários pacotes precisam é uma lente partilhada em vez de uma cópia em cada um: o registo de tecnologia subcontratada serve tanto Seguros como Banca e pagamentos. Se o seu pacote derivado precisar de uma lente que já exista como uma lente partilhada, utilize-a em vez de desenhar a sua própria.

O licenciamento segue a herança. Um pacote é licenciado sobre o Enterprise e pode precisar de suplementos, e o documento de licença inclui essas dependências. O pacote Seguros precisa de Salas de decisão e registos selados, pelo que um cliente que licencie um pacote que o herde também precisa desse suplemento, e a consola recusa emitir uma licença que o deixe de fora. Os ecrãs de telemóvel de um pacote também precisam do suplemento Aplicações móveis. Verifique a cadeia de requisitos antes de prometer uma data a um cliente.

Adicionar uma lente a um pacote que já foi lançado

O menor trabalho vertical é uma nova lente num pacote que não escreveu. Seis meses após o início do piloto, a equipa de sinistros marítimos da Larkfield queria uma lente própria dentro do Cold chain: excursões e sinistros, sem tomadas de energia, sem pontos de regulação. Não tocámos no código do pacote. Uma lente é uma linha no registo de lentes da organização, propriedade do pacote, pelo que a iniciámos a partir do caminho padrão de lentes em Start something new e a moldámos no Lens builder tendo a lente Cold-chain controller como base. Aplica-se a mesma regra que anteriormente: a nova lente pode ocultar o que a sua base mostra e nunca pode mostrar mais. É definida uma vez para a organização e atribuída a uma função da plataforma em cada unidade. Uma atribuição é revogada, nunca eliminada, e voltar a atribuir a lente cria uma nova atribuição, para que o histórico de quem deteve que lente e quando permaneça legível. O registo contabiliza quantas pessoas detiveram uma lente em cada mês, nunca quem.

A página Lenses and who sees them mostra o resultado como uma matriz de lente por unidade e função, com Add, Change e Withdraw em cada célula. Pré-visualize a nova lente como uma pessoa antes de a atribuir, exatamente como acima.

Quanto custou, honestamente

Um pacote acede aos registos de um cliente, pelo que a plataforma torna algumas coisas lentas de propósito, devendo planear para tal desde o primeiro dia.

  1. Uma cópia mascarada requer sempre a concordância do proprietário dos dados. A nossa demorou um dia a chegar da primeira vez, porque a Priya quis ler primeiro o modelo de conhecimento. Comece com dados sintéticos e faça o pedido atempadamente.
  2. O autor não pode aprovar o seu próprio lançamento e os pedidos prescrevem após 3 dias. Se os seus revisores estiverem ocupados, o seu lançamento aguarda.
  3. Um lançamento que solicite mais permissões do que o anterior, como o envio de correio ou um endereço externo, fica retido até que dois revisores aceitem o manifesto alargado. O Capítulo 2.28, Releasing your extension, mostra a página Manifest and permissions que o informa antes de fazer o pedido.
  4. Uma lente não pode mostrar o que a sua lente base oculta. Se uma função precisar realmente de mais, trata-se de uma conversa com o administrador da organização, não de uma definição.

Nenhum destes aspetos nos atrasou duas vezes. O segundo lançamento do Cold chain demorou uma semana desde o primeiro commit até ao piloto de Roterdão, sendo a maior parte do tempo dedicada aos 66 testes executados em três ramos e a duas pessoas a ler as evidências.