Visão
03 · Conceitos e vocabulário
As palavras que usamos com sentido preciso. Quando um documento as usa, é este o sentido.
Stack, aplicação, módulo
Na Hibex, stack, produto e repositório são a mesma coisa: um repositório Git que entrega um produto, com uma ou mais aplicações.
Os exemplos desta documentação usam um produto fictício, o atendimento: uma stack em que clientes compram créditos e abrem chamados, com uma aplicação de gestão para os colaboradores, uma aplicação para os clientes e um site público.
| Termo | Definição | Exemplo |
|---|---|---|
| Stack (= produto = repositório) | Definição: Um repositório Git que entrega um produto. Nome no GitHub: <plataforma>-stack-<produto> | Exemplo: enterprise-stack-atendimento |
| Plataforma | Definição: O agrupamento comercial de stacks (define o domínio <plataforma>.hibex.net das aplicações de colaboradores) | Exemplo: Enterprise |
| Aplicação | Definição: Unidade implantável: uma imagem Docker, um serviço Kamal, um endereço público, uma família de cor e, se tiver usuários, um client no Keycloak | Exemplo: atendimento-gestao, atendimento-cliente, atendimento-site |
| Módulo | Definição: Unidade de build. Uma aplicação é montada de um ou mais módulos; um módulo pode servir várias aplicações (ex.: o domínio compartilhado) | Exemplo: atendimento-core, atendimento-gestao |
| Site estático | Definição: Aplicação sem backend (HTML + CSS em nginx), em geral pública | Exemplo: |
| Aplicação pública | Definição: Aplicação sem login: declarada como pública na ficha e no documento de acesso, com o que expõe | Exemplo: atendimento-site |
| Plataforma Hibex | Definição: A infraestrutura compartilhada por todas as stacks (toolbox) e o design system (enterprise-stack-design) | Exemplo: — |
Decisão e especificação
| Termo | Definição |
|---|---|
| ORG | Definição: Organization Architecture Decision Record: decisão da organização, que vale para toda stack. Nasce aqui, numerada ORG-NNNN, e chega a cada stack como cópia em docs/decisoes/organizacao/, nunca editada à mão |
| ADR | Definição: Architecture Decision Record: decisão do projeto, com contexto, alternativas e consequências. Numerada ADR-NNNN em cada stack, imutável depois de aceita, e nunca contradiz uma ORG |
| ADR pré-escrita | Definição: Uma das primeiras ADRs da stack, já escrita no modelo com a escolha em lacuna, para cumprir uma ORG que deixa algo para a stack decidir |
| Lacuna | Definição: Um ponto propositalmente vazio no modelo zerado, marcado {{LACUNA:<id>}}, que a stack preenche ao nascer |
| Ficha da stack | Definição: O documento onde as lacunas de tecnologia são preenchidas, num só lugar (docs/stack.md) |
| Portão | Definição: Condição que precisa ser verdadeira para passar de uma fase à seguinte (ex.: "nenhuma lacuna aberta") |
| Capability | Definição: Uma área de comportamento do produto, com spec própria em openspec/specs/<capability>/ |
| Spec | Definição: A verdade viva do que uma capability faz: requisitos (Requirement) com cenários (Scenario, WHEN/THEN) |
| Change | Definição: Uma unidade de trabalho do OpenSpec: proposal, design, specs delta e tasks, em openspec/changes/<nome>/ |
| Solução | Definição: Documento que detalha um pedaço da implementação que não cabe na arquitetura nem numa ADR (docs/solucoes/) |
| Guia | Definição: Passo a passo operacional (docs/guias/) |
Testes
| Termo | Definição |
|---|---|
| Teste de unidade | Definição: Uma regra isolada, sem rede, sem container, em milissegundos |
| Teste de integração | Definição: Uma parte real do sistema contra dependências reais em container (banco, Keycloak) |
| Teste de rota | Definição: Um teste de integração da camada web: a requisição atravessa, dentro do processo, o roteamento, a segurança e a resposta da aplicação, com usuário simulado; prova status, permissão e redirecionamento |
| Teste fim a fim (E2E) | Definição: Um navegador de verdade usando as aplicações no ar, como um usuário |
| Agrupamento | Definição: 1º nível do E2E. Reúne cenários de uma área (em geral, uma capability) |
| Cenário | Definição: 2º nível. Uma situação dentro do agrupamento (em geral, um requisito da spec) |
| Caso | Definição: 3º nível. Uma verificação concreta, com passos e resultado esperado (em geral, um Scenario da spec) |
| Setup | Definição: Script que cria as condições de que um nível precisa. Roda uma vez por corrida, e só se algum caso abaixo dele foi selecionado |
| Corrida | Definição: Uma execução do E2E, com uma seleção (tudo, um agrupamento, um cenário, um caso) |
| Regressão | Definição: A corrida de tudo, a partir do ambiente zerado, no fim de uma change |
| Captura | Definição: Print de tela tirado num ponto de um caso, nas variantes (desktop/celular × claro/escuro) |
| Acervo | Definição: O conjunto versionado de capturas (opcional por stack) |
O modelo de E2E está em 11 · Testes fim a fim hierárquicos.
Identidade e acesso
| Termo | Definição |
|---|---|
| Realm | Definição: Unidade de política de autenticação no Keycloak. Separado por população (colaboradores × clientes), nunca por aplicação |
| Client | Definição: O registro de uma aplicação num realm |
| Permissão | Definição: Um client role fino, no formato <recurso>:<ação> (ex.: chamado:atender). É o que o código confere |
| Perfil | Definição: Um client role composto (perfil:<nome>) que reúne permissões. É o que se atribui às pessoas — via grupo |
| Grupo | Definição: Onde os perfis são atribuídos. Uma pessoa recebe acesso entrando num grupo, nunca por papel direto no usuário |
| Perfil padrão | Definição: O perfil que todo usuário autenticado do realm recebe (pelos default roles), quando toda a população tem o mesmo acesso |
| Conta de serviço | Definição: O usuário técnico de um client confidencial, usado quando outra aplicação precisa chamar a API desta |
O modelo de acesso está em 12 · Identidade e acesso.
Papéis de pessoas
| Papel | O que faz |
|---|---|
| Mantenedor | O que faz: Decide, revisa e publica: aceita ADRs, aprova changes, faz commit, push, deploy, guarda segredos, envia pedidos ao design system |
| Agente | O que faz: Agente de IA (Claude Code ou outro que leia AGENTS.md): explora, propõe, implementa, testa, documenta, entrega instruções |
| Usuário | O que faz: Quem usa uma aplicação, num perfil |
| Operador | O que faz: Quem administra o Keycloak e a VPS (hoje, o próprio mantenedor) |
Convenções de nome
| O quê | Convenção | Exemplo |
|---|---|---|
| Repositório | Convenção: <plataforma>-stack-<produto> | Exemplo: enterprise-stack-atendimento |
| Aplicação / módulo | Convenção: <produto>-<papel> | Exemplo: atendimento-gestao |
Serviço Kamal, service.name, client Keycloak | Convenção: o nome da aplicação | Exemplo: atendimento-gestao |
| Endereço — usuário final | Convenção: <app>.hibex.app | Exemplo: atendimento.hibex.app |
| Endereço — colaboradores | Convenção: <app>.<plataforma>.hibex.net | Exemplo: gestao-atendimento.enterprise.hibex.net |
| Endereço — exceções comerciais | Convenção: <nome>.hibex.co (com ADR) | Exemplo: atendimento.hibex.co |
| Prefixo de segredo no Bitwarden | Convenção: sigla curta da aplicação, em maiúsculas | Exemplo: ATDGESTAO_ |
| Grupo no Keycloak | Convenção: <produto>-<perfil-no-plural> | Exemplo: atendimento-gestores |
| Permissão | Convenção: <recurso>:<ação> | Exemplo: carteira:conceder |
| Perfil | Convenção: perfil:<nome> | Exemplo: perfil:gestor |
| ORG | Convenção: docs/decisoes/organizacao/ORG-NNNN-slug.md (só aqui) | Exemplo: ORG-0022-backup-e-restauracao.md |
| ADR | Convenção: docs/decisoes/ADR-NNNN-slug-no-imperativo.md | Exemplo: ADR-0012-… |
| Change | Convenção: kebab-case descritivo | Exemplo: creditos-com-validade |