Camada demand

Papel da camada

domain.demand modela o histórico observado que alimenta treino e inferência. Esta camada define o que é uma série válida para o negócio.

Objetos centrais

SeriesKey

Identidade única da série no contexto de negócio.

Composição:

• organização (OrganizationId);
• SKU (sku_id + sku_key);
• loja (store_id + store_key);
• granularidade (TimeGrain).

DemandObservation

Ponto observado de demanda em um período.

Composição:

• period_start;
• DemandQuantity;
• source;
• id e created_at.

DemandSeries

Agregado de observações ordenadas para uma SeriesKey.

É o aggregate root da camada: toda alteração de observação deve passar por ele.

Regras de negócio detalhadas

Regra	Onde é aplicada	Motivo de negócio
Não aceitar período duplicado	record_observation	Evita ambiguidade no histórico e duplicidade de sinal para treino.
Ordenar observações por período	record_observation	Garante consistência temporal para extração de features.
UOM única por série	_validate_observation	Evita mistura de unidades incompatíveis na mesma série.
Tipo temporal compatível com granularidade	_validate_observation + ensure_period_matches_grain	Impede combinação inválida (ex.: date em série horária).
Janela histórica com start <= end	history_window	Evita leituras semânticas inválidas no consumo de histórico.

Ciclo de vida da série

1. Criar série com DemandSeries.create(...) ou construtor.
2. Registrar observações com record_observation(...).
3. Ajustar observação existente com replace_observation(...).
4. Remover observação com remove_observation(...) quando necessário.
5. Extrair intervalo com history_window(start, end).

Comportamentos importantes

uom

Propriedade derivada da primeira observação da série.

• retorna None quando série está vazia;
• após primeira observação, passa a atuar como referência de consistência.

Reconstrução segura

No __post_init__, observações pré-carregadas são revalidadas via record_observation. Isso garante que até séries reconstruídas de persistência passem pelas mesmas regras.

Cenários de erro esperados

• DuplicatePeriodError: inserção do mesmo período duas vezes.
• InvariantViolation: UOM diferente da referência da série.
• InvariantViolation: tentativa de substituir/remover período inexistente.
• UnsupportedGrainError: período incompatível com granularidade.

Contrato de saída da camada

Quando uma DemandSeries é considerada válida:

• identidade da série é consistente;
• observações estão ordenadas;
• unidade é homogênea;
• dados podem ser convertidos de forma segura para treino/inferência.