domain.demand

Papel na engine

domain.demand é a fonte de verdade do histórico que alimenta todo o ciclo inteligente. As invariantes desta camada evitam que dados inválidos contaminem seleção de modelo e previsão em produção.

Módulo: domain.demand.model

SeriesKey

Identidade de série de demanda.

Campos:

• organization_id: OrganizationId
• sku_id: UUID
• store_id: UUID
• sku_key: ExternalKey
• store_key: ExternalKey
• grain: TimeGrain

Invariantes:

• sku_id e store_id não podem ser UUID nulo.

DemandObservation

Representa observação unitária de demanda.

Campos:

• period_start: PeriodStart
• quantity: DemandQuantity
• source: str
• id: UUID (autogerado por default)
• created_at: datetime (UTC por default)

Invariantes:

• id não pode ser nulo;
• source não pode ser vazio (após trim).

DemandSeries

Agregado de observações para uma SeriesKey.

Campos principais:

• key: SeriesKey
• id: UUID
• created_at: datetime

Propriedades:

• observations -> tuple[DemandObservation, ...]
• uom -> str | None

Métodos:

DemandSeries.create(...) -> DemandSeries

Factory com parâmetros opcionais para reconstrução de estado.

record_observation(observation) -> None

Adiciona observação, valida invariantes e mantém ordenação por período.

Falhas possíveis:

• DuplicatePeriodError para período repetido;
• InvariantViolation para UOM inconsistente;
• UnsupportedGrainError para incompatibilidade período/grão.

replace_observation(observation) -> None

Substitui observação do mesmo período; falha se período não existir.

remove_observation(period_start) -> None

Remove observação por período; falha se período não existir.

history_window(start, end) -> tuple[DemandObservation, ...]

Retorna observações no intervalo fechado [start, end].

Falha quando start > end.

Comportamentos relevantes

• observações são sempre ordenadas internamente;
• para granularidade horária, period_start deve ser datetime;
• para granularidades diária/semanal/mensal, aceita date ou datetime.