Várias modelagens, e federação

Uma modelagem é uma realidade inteira: propósito, público, glossário e convenções próprios. Um repositório pode ter uma só — o caso comum — ou várias.

O registro

cfour.yaml, na raiz do repositório, é o único caminho que a ferramenta procura subindo a árvore de diretórios. Tudo o mais é derivado dele.

cfour.yaml

version: 1
id: d8525e0d
active: reservas

modelagens:
  - id: reservas
    name: Reserva de Salas
    path: ./reservas

  - id: portaria
    name: Controle de Portaria
    path: ./portaria

Campo	O que faz
version	a versão do formato do registro
id	o identificador deste registro, e não de uma modelagem. Serve para uma máquina com várias chaves de publicação saber qual é a deste repositório. É opaco de propósito
active	qual modelagem abre quando ninguém diz qual
modelagens	a lista, cada uma com id, name e path
federacoes	leituras conjuntas nomeadas — mais abaixo

O path aceita caminho relativo e ~, então uma modelagem pode morar fora deste repositório.

A identidade de uma modelagem

portaria/modelagem.yaml

version: 1
id: portaria
name: Controle de Portaria
status: active
federacao: predio

Campo	O que faz
id	tem de bater com o do registro
name	o nome legível
description	para que ela existe
status	active, reference ou archived. É o único campo daqui que muda o comportamento de um comando: só active é publicado
federacao	a leitura conjunta de que ela participa

Quando criar a segunda modelagem

A pergunta certa não é de tamanho, é de realidade.

Crie um projeto novo quando:

• é o mesmo vocabulário e o mesmo público;
• as duas partes se leem juntas, no mesmo desenho;
• a configuração de aparência é a mesma.

Crie uma modelagem nova quando:

• os glossários são diferentes, e a mesma palavra significa duas coisas;
• os públicos são diferentes, e ninguém lê as duas ao mesmo tempo por padrão;
• as duas devem ser publicadas separadamente, com controle de acesso próprio;
• uma delas mora em outro repositório.

A seta que atravessa duas modelagens

Não existe referência direta entre modelagens, e nunca vai existir: cada uma é compilada e validada sozinha, então um identificador da outra seria uma referência solta exatamente no único momento em que daria para conferi-la.

O que atravessa é um espelho: uma caixa local comum — quase sempre shape: external — que declara de quem ela é o reflexo.

portaria/model/portaria/elements.yaml

elements:
  - id: portaria
    name: Controle de Portaria
    shape: system
    description: Libera a catraca de quem tem reuniao marcada no predio.

  # O ESPELHO. Lido sozinho, e uma caixa externa comum. Lido junto da modelagem
  # `reservas`, ele se dissolve no elemento real de la — e a seta abaixo passa a
  # chegar naquele sistema, que o leitor pode entao abrir por dentro.
  - id: reserva-de-salas
    name: Reserva de Salas
    shape: external
    description: Sistema de outra equipe. Modelado por ela, nao por nos.
    bind:
      modelagem: reservas
      ref: reservas/reservas

relations:
  - from: portaria
    to: reserva-de-salas
    kind: sync
    label: Confere a reserva do dia

Lida sozinha, a modelagem portaria desenha uma caixa externa tracejada, como qualquer sistema de fora. Lida junto com reservas, o espelho se dissolve no elemento real de lá — e a seta que apontava para a caixa local passa a chegar naquele sistema, que o leitor pode então abrir por dentro.

O mesmo arquivo serve as duas leituras, sem ninguém escrever a integração duas vezes.

Os campos de bind

Campo	Obrigatório	O que é
modelagem	sim	o identificador da modelagem que declara o elemento real
ref	sim	o identificador qualificado (<projeto>/<id>) daquele elemento

ref tem de ser qualificado. Um identificador solto resolveria contra o projeto que o declara — e esse projeto é um fato desta árvore, não da outra.

Um espelho não tem interior

Uma caixa com bind não deve ter filhos. Numa leitura conjunta ela se dissolve no elemento real, e os filhos ficariam sem pai. O cfour check avisa quando isso acontece.

O que é validado, e quando

A forma de bind é validada sempre. A existência do alvo, não: a modelagem apontada, por definição, não está na árvore que está sendo carregada.

Quem confere as duas pontas é:

cfour check --all

Ele carrega todas as modelagens do registro e confere os espelhos — como aviso, e não erro, porque a outra modelagem tem outro dono e pode ter mudado sem avisar esta.

Declarar uma leitura conjunta

Uma federação é um apelido para o que o leitor também poderia marcar à mão. Ela é declarada nos dois lados:

cfour.yaml

federacoes:
  - id: predio
    name: Reservas + Portaria
    modelagens: [reservas, portaria]
    curador: reservas

portaria/modelagem.yaml

federacao: predio

Campo	O que faz
id	o identificador da leitura conjunta
name	o rótulo exibido
modelagens	os membros
curador	de quem vale a configuração de aparência quando os membros discordam. Sem ele, vale a do primeiro

Os dois lados precisam concordar. Sem o par, a leitura conjunta aparece na plataforma e não na sua máquina, ou o contrário.

Por comando:

cfour federacao add predio --modelagem reservas --modelagem portaria --curador reservas
cfour federacao list     # diz se os dois lados concordam
cfour federacao rm predio

A razão de a federação ser declarada em modelagem.yaml, e não só no registro, é que um registro conhece apenas o próprio repositório — e uma leitura conjunta pode atravessar repositórios. Do lado da plataforma, é esse campo que faz duas modelagens publicadas separadamente serem lidas juntas.

Trabalhar com várias

cfour modelagem list                 # as registradas
cfour modelagem use portaria         # troca a que abre por padrão
cfour check --modelagem portaria     # sem trocar a padrão
cfour check --all                    # todas, e confere os espelhos

C4_MODELAGEM no ambiente faz o mesmo que --modelagem, para a sessão inteira.

Próximo passo

O modelo está completo. A seção Linha de comando mostra como trabalhar nele sem editar YAML à mão, e Publicar leva o resultado para o ar.