🚧 Em Construção 🚧
Pular para o conteúdo principal

Entidades

Esta especificação define o modelo estrutural mínimo que todas as entidades da plataforma Guardia DEVEM seguir. O objetivo é garantir consistência entre serviços, interoperabilidade entre domínios e aderência a requisitos de segurança, rastreabilidade e conformidade desde a concepção.

Essa estrutura base se aplica a qualquer objeto persistente e rastreável da plataforma, abrangendo APIs, bases de dados, eventos de domínio, integrações externas e demais mecanismos de representação de entidades.

Ao adotar esse padrão, toda entidade:

  • Possui um identificador único e global;
  • É versionada com controle explícito de alterações;
  • Mantém histórico completo e auditável;
  • Pode ser integrada e eventualmente descartada sem perda de rastreabilidade.

A aplicação dessa estrutura reduz inconsistências, facilita integrações e elimina lacunas de auditoria que poderiam comprometer a conformidade com normas como LGPD, SOC 2 e ISO 27001.

Além disso, o modelo reforça os princípios do Compliance by Design, assegurando:

  • Identificação única (entity_id);
  • Rastreabilidade temporal (created_at, updated_at, discarded_at);
  • Integridade e controle de concorrência (version);
  • Preservação de histórico e reversibilidade (history);
  • Integração e interoperabilidade com sistemas externos (external_entity_id, metadata).

Estrutura base​

A estrutura base de uma entidade na Guardia DEVE conter os seguintes propriedades:

PropriedadeTipoObrigatórioDescrição
entity_idUUID v7SimIdentificador único da entidade.
entity_typestringSimTipo de entidade.
external_entity_idstringNãoIdentificador único da entidade em um sistema externo.
created_atdatetimeSimData e hora de criação da entidade.
updated_atdatetimeSimData e hora da última atualização da entidade.
discarded_atdatetimeNãoData e hora de descarte da entidade.
metadataJson ObjectNãoMetadados da entidade.
versionintegerSimVersão da entidade.
historyarrayNãoHistórico de versões da entidade.

Propriedades detalhadas​

entity_id​

  • DEVE ser único, imutável e gerado pelo sistema.
  • DEVE implementar o UUID v7 conforme a RFC 9562 assegurando ordenação temporal.

entity_type​

  • DEVE pertencer a uma lista controlada de entidades conhecidas pelo sistema.

external_entity_id​

  • PODE ser nulo.
  • DEVE ter no máximo 36 caracteres.
  • QUANDO presente, DEVE ser único dentro do entity_type.
  • Ideal para referências cruzadas com sistemas legados ou externos.

created_at​

  • DEVE ser um datetime em UTC formatado conforme a RFC 3339.
  • DEVE ser gerado automaticamente na criação.
  • NÃO PODE ser alterado após a criação.

updated_at​

  • DEVE ser um datetime em UTC formatado conforme a RFC 3339.
  • DEVE ser atualizado a cada modificação persistente.
  • Na criação, DEVE assumir o mesmo valor de created_at.
  • No descarte, DEVE assumir o mesmo valor de discarded_at.
  • Utilizado para controle de concorrência e sincronização.

discarded_at​

  • DEVE ser um datetime em UTC formatado conforme a RFC 3339.
  • PODE ser nulo.
  • Quando preenchido, indica soft delete. A entidade permanece no sistema para fins de rastreabilidade.

metadata​

  • DEVE ser um JSON Object.
  • Chave e valor DEVEM ser strings.
  • DEVE ter seguir o tamanho ideal de 4KB sempre que possível e não DEVE ultrapassar 10KB.
  • Atualizações DEVEM ser feitas via JSON Merge Patch RFC 7386.
  • NÃO DEVE conter dados sensíveis ou pessoais sem previsão legal.
  • Valores PODEM ser armazenados criptografados, com impacto na performance.

version​

  • Inicializa em 1 e é incrementado automaticamente junto com o updated_at.
  • NUNCA é reiniciado, mesmo após restauração de entidade descartada.
  • Em caso de conflito de versão, a última versão é preservada, descartando a que conflitou.

history​

  • Armazena snapshots de versões anteriores.
  • Utilizado para auditoria, rollback e investigação.
  • Por padrão, armazena as últimas 10 versões mais recentes por até 365 dias.
  • O histórico DEVE ser omitido das respostas temporais (create, update, delete e get).
  • DEVE ser omitido dos eventos de domínio.
  • O histórico DEVE ser fornecido nas respostas de leitura (get) quando solicitado pelo cliente no endpoint api/v1/<entity_type>/<entity_id>/history.
  • O endpoint de histórico retorna uma lista de até 10 registros históricos da mesma entidade.
  • Valores PODEM ser armazenados criptografados, com impacto na performance.

Quando aplicar​

Este modelo DEVE ser adotado sempre que:

  • Um novo recurso de domínio for modelado;
  • APIs forem expostas internamente ou externamente;
  • Eventos de domínio forem gerados;
  • Dados precisarem de unicidade, rastreabilidade, reversibilidade ou interoperabilidade.

IMPORTANTE: Exceções DEVEM ser justificadas e aprovadas pelo Comitê Diretivo e registradas em um Registro de Decisão de Produto (PDR).

Referências​