Camada forecasting

Papel da camada

domain.forecasting transforma resultado de modelo em uma execução de previsão auditável. Ela garante que apenas runs completos e consistentes sejam considerados válidos.

Objetos centrais

ForecastPointValue

• valor previsto (Decimal);
• unidade (UomCode);
• período de referência.

Regra:

• valor não pode ser negativo.

PredictionInterval

• limite inferior;
• limite superior;
• confiança.

Regras:

• lower <= upper;
• confidence no intervalo aberto (0, 1).

ForecastPoint

Combina período, valor e intervalo opcional.

Regra:

• período do ponto deve coincidir com período de ForecastPointValue.

ForecastRun

Aggregate root da inferência.

Responsável por:

• controlar estado de execução;
• validar sequência e cardinalidade dos pontos;
• registrar metadata de fallback;
• garantir consistência final do run.

Máquina de estados do ForecastRun

Estado	Significado	Próximas transições válidas
REQUESTED	Run criado e ainda não executado	RUNNING, FAILED
RUNNING	Execução em andamento	COMPLETED, FAILED
COMPLETED	Run finalizado com pontos válidos	nenhuma
FAILED	Run finalizado sem resultado válido	nenhuma

Regras de negócio detalhadas

Regra	Onde é aplicada	Motivo de negócio
series_key.organization_id deve bater com organization_id do run	__post_init__	Evita execução cruzada entre organizações.
Grão do horizonte deve bater com grão da série	__post_init__	Evita previsão em escala temporal incompatível.
Ponto previsto deve respeitar UOM esperada	_validate_point	Impede mistura de unidade no resultado final.
Sequência de pontos deve ser monotônica e alinhada ao step	_validate_point_sequence	Garante horizonte coerente para consumo posterior.
Run completo deve ter exatamente horizon.periods pontos	complete	Evita previsão parcial tratada como sucesso.
Run completo exige executed_model_version	complete	Garante auditabilidade de versão realmente usada.
Fallback degradado exige origem e versão executada distintas	_validate_fallback_metadata	Torna explícita a degradação operacional.

Fluxo interno do aggregate

1. Criar run em REQUESTED.
2. start() para RUNNING.
3. Inserir pontos via record_point ou set_points.
4. Registrar versão executada (set_executed_model_version) ou fallback degradado (mark_degraded_fallback).
5. complete() ou fail(reason).

Semântica de fallback degradado

Quando um run é degradado:

• degraded = True;
• fallback_from_version indica versão primária que falhou;
• executed_model_version indica versão efetivamente usada no sucesso.

Isso permite separar claramente:

• sucesso primário;
• sucesso degradado;
• falha total.

Erros esperados

• tentativa de completar run com pontos insuficientes;
• tentativa de adicionar ponto após run finalizado;
• sequência temporal inválida (salto de período);
• fallback com versões iguais;
• motivo de falha vazio em fail.

Contrato de saída da camada

Um ForecastRun em COMPLETED representa previsão pronta para consumo pela plataforma com:

• horizonte completo;
• unidade consistente;
• versão executada conhecida;
• rastreabilidade de degradação, quando aplicável.