06 · Modelo zerado e lacunas

Uma lacuna é um marcador procurável num arquivo do modelo:

{{LACUNA:<id>}}

• <id> é estável e único (stack.linguagem, persistencia.banco, app.lista…), para que a mesma lacuna em vários arquivos seja preenchida com o mesmo valor;
• cada id tem a sua descrição num lugar só: o catálogo das lacunas, no fim do roteiro da Fase 1 (docs/guias/definir-a-stack.md), com o que preencher e se é de escolha ou de valor. O modelo de hoje tem 93;
• o formato é ASCII de propósito: grep -rn '{{LACUNA:' . lista todas;
• eng/gaps.sh faz essa busca e falha se encontrar alguma. Ele roda na CI desde o primeiro commit — enquanto houver lacuna, a CI fica vermelha, e isso é o esperado na Fase 1.

Dois tipos de lacuna

Lacunas de escolha sempre viram texto de ADR (com alternativas consideradas); lacunas de valor só precisam do valor.

A ficha é o único lugar onde a stack declara sua tecnologia. É curta, tabelada e lida em segundos. As ADRs explicam o porquê; a ficha diz o quê.

Abaixo, a ficha zerada como ela vem no modelo. Ao lado de cada lacuna, como ficaria no produto fictício dos exemplos, o atendimento (03), para dar o tom.

1. Produto e aplicações

2. Tecnologia das aplicações

3. Persistência

O modelo não tem banco padrão: cada stack escolhe os seus armazenamentos (banco relacional, MongoDB, fila, armazenamento de arquivos, cache…) numa ADR, pelos critérios abaixo. O PostgreSQL é a opção já provada para dados relacionais, não uma imposição.

4. Testes

Em todas as camadas, o teste vem antes do código (TDD, ORG-0009).

5. Containers e implantação

6. Identidade

7. Observabilidade

8. Pré-requisitos de máquina

Uma versão escrita em dois lugares diverge. Por isso a ficha diz onde cada versão mora, e todos os outros lugares a referenciam ou a conferem.

eng/pinned-versions.sh (modelo) falha quando encontra:

• latest, *, ^x, ~x, >=x, 1.+, latest.release, faixas Maven e -SNAPSHOT nos manifestos que conhece: package.json, requirements*.txt, *.versions.toml, build.gradle(.kts), pom.xml, .nvmrc, .node-version, .python-version, .tool-versions e eng/tools.versions;
• imagem Docker sem tag ou com tag sem x.y.z (postgres:16), no Dockerfile, no compose.yaml, nos acessórios do deploy.yml e nos workflows. Com digest, passa. Uma imagem que só publica x.y entra em eng/pinned-versions.exceptions, exata e com a razão;
• npx <pacote> sem @x.y.z em scripts, workflows, Makefile, scripts do package.json e nos blocos de código do Markdown. Sem versão passa só o pacote que um package.json do repositório já declara com versão exata;
• runs-on: ubuntu-latest ou uses: action@vN sem vX.Y.Z nem o SHA completo;
• a mesma imagem com versões diferentes entre compose.yaml, deploy/*/config/deploy.yml, os Dockerfile, os workflows e o código (ex.: Keycloak do Testcontainers × Keycloak do Compose).

Lacunas e variáveis (${X}) ficam de fora: as lacunas são do gaps.sh, e a variável vem da fonte única. Um ecossistema que falte entra no script por mudança na arquitetura, com teste.

O modelo traz o roteiro que o mantenedor e o agente seguem, em conversa:

Critérios mínimos que toda escolha de tecnologia precisa responder (vão para o "Contexto" da ADR de stack):

Algumas decisões são da stack, mas surgem ao longo da vida, não no nascimento. O modelo não as força na Fase 1 — elas viram ADRs próprias quando aparecerem:

• formato de API entre aplicações (se um dia houver);
• fila, cache, busca, agendador;
• armazenamento de arquivos (o padrão Hibex até aqui é só links, sem upload);
• internacionalização;
• integrações externas específicas.