Skip to content
forecast-engine

Camada shared

Papel da camada

domain.shared concentra as definições que garantem linguagem comum em todo o domínio. Sem essa camada, cada contexto poderia interpretar tempo, unidade e erro de maneira diferente.

Objetos e enums

OrganizationId

Representa o escopo organizacional da operação.

Regras:

  • valor obrigatório;
  • UUID nulo é inválido.

Impacto de negócio:

  • impede que séries, modelos e runs sejam criados sem contexto de organização.

ExternalKey

Chave de integração com sistemas externos (ERP, WMS, etc.).

Regras:

  • system obrigatório, normalizado para minúsculo;
  • value obrigatório, normalizado para maiúsculo.

Impacto de negócio:

  • reduz erro por inconsistência de casing em integrações.

DemandQuantity

Quantidade observada com unidade (UOM).

Regras:

  • valor decimal deve ser >= 0.

Impacto de negócio:

  • impede entrada de demanda negativa sem tratamento explícito.

TimeGrain

Granularidades suportadas no domínio:

  • DAILY
  • WEEKLY
  • MONTHLY

UomCode

Unidades suportadas:

  • EA, KG, L, BOX, M, M2, M3

Regras temporais comuns

Compatibilidade period_start x grain

Função: ensure_period_matches_grain(period_start, grain).

Regras:

  • DAILY, WEEKLY, MONTHLY aceitam date ou datetime.

Cálculo de próximo período

Função: next_period_start(period_start, grain, step=1).

Regras:

  • step precisa ser > 0;
  • avanço temporal respeita granularidade;
  • no caso mensal, ajusta para último dia válido do mês alvo.

Exemplo de ajuste mensal:

  • 31/01 + 1 mês -> 28/02 ou 29/02 (ano bissexto).

Taxonomia de erros

DomainError

Classe base de erros do domínio.

InvariantViolation

Erro padrão para quebra de regra de negócio.

DuplicatePeriodError

Especialização para tentativa de inserir período repetido em série.

UnsupportedGrainError

Especialização para tipo temporal incompatível com granularidade.

InvalidModelSpecError

Especialização para configuração inválida de modelagem.

Princípio operacional

A camada shared não orquestra fluxos. Ela define o contrato mínimo para que os outros contextos possam operar de forma consistente e previsível.