Skip to content
forecast-engine

domain.shared

Papel na engine

Este módulo concentra primitivas críticas (erros, granularidade de tempo, IDs e UOM) usadas por todos os fluxos de treino e inferência. Em um componente central de produto, essas definições funcionam como contrato interno de consistência.

Módulo: domain.shared.errors

DomainError(Exception)

Tipo-base para falhas de domínio.

InvariantViolation(DomainError)

Levantada quando uma invariante é quebrada.

DuplicatePeriodError(InvariantViolation)

Usada quando o mesmo período é inserido mais de uma vez na mesma série.

UnsupportedGrainError(InvariantViolation)

Usada quando tipo de período não corresponde à granularidade esperada.

InvalidModelSpecError(InvariantViolation)

Usada para especificações inválidas de modelo/estratégia/métrica.

Módulo: domain.shared.value_objects

Tipos e enums

type PeriodStart = date | datetime

Representa início de período em granularidades diferentes.

TimeGrain(StrEnum)

Valores:

  • DAILY
  • WEEKLY
  • MONTHLY

UomCode(StrEnum)

Valores suportados:

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

Funções utilitárias

utc_now() -> datetime

Retorna timestamp atual em UTC.

new_uuid7() -> UUID

Gera UUID v7.

ensure_period_matches_grain(period_start, grain) -> None

Valida compatibilidade entre period_start e TimeGrain.

next_period_start(period_start, grain, step=1) -> PeriodStart

Retorna próximo período respeitando granularidade e passo.

Comportamentos:

  • DAILY: soma dias;
  • WEEKLY: soma semanas;
  • MONTHLY: soma meses com ajuste de último dia válido.

Value objects

OrganizationId

Campos:

  • value: UUID

Métodos:

  • OrganizationId.new() -> OrganizationId
  • OrganizationId.from_string(value: str) -> OrganizationId
  • __str__() -> str

Invariante:

  • UUID não pode ser nulo.

ExternalKey

Campos:

  • system: str
  • value: str

Normalização automática:

  • system: trim + lowercase
  • value: trim + uppercase

Invariantes:

  • ambos os campos devem ser não vazios.

DemandQuantity

Campos:

  • value: Decimal
  • uom: UomCode

Invariante:

  • value >= 0.