Visão do domínio

Objetivo desta seção

Esta seção detalha o coração da forecast-engine: regras de negócio, objetos e responsabilidades de cada camada do domínio. O foco é explicar como o sistema evita estados inválidos e mantém previsões confiáveis em produção.

Estrutura lógica do domínio

O domínio é dividido em quatro camadas internas:

1. shared: tipos fundamentais e utilitários transversais.
2. demand: histórico observado de cada série.
3. modeling: governança de modelo, estratégia, versão e promoção.
4. forecasting: execução de inferência com controle de estado e fallback.

Mapa dos objetos principais

classDiagram
    class OrganizationId
    class ExternalKey
    class DemandQuantity
    class TimeGrain
    class UomCode

    class SeriesKey
    class DemandObservation
    class DemandSeries

    class ModelDefinition
    class ModelVersion
    class ModelInstance
    class HorizonSpec
    class StrategySpec
    class MetricSpec

    class ForecastRun
    class ForecastPoint
    class ForecastPointValue
    class PredictionInterval

    OrganizationId <.. SeriesKey
    ExternalKey <.. SeriesKey
    DemandQuantity <.. DemandObservation
    TimeGrain <.. SeriesKey
    UomCode <.. DemandQuantity

    SeriesKey <.. DemandSeries
    DemandObservation <.. DemandSeries

    HorizonSpec <.. ModelDefinition
    StrategySpec <.. ModelDefinition
    MetricSpec <.. ModelDefinition
    ModelVersion <.. ModelDefinition
    ModelInstance <.. ModelDefinition

    SeriesKey <.. ModelInstance

    SeriesKey <.. ForecastRun
    HorizonSpec <.. ForecastRun
    ForecastPointValue <.. ForecastPoint
    PredictionInterval <.. ForecastPoint
    ForecastPoint <.. ForecastRun

Regras de negócio transversais

• Identificadores de negócio não aceitam UUID nulo.
• Granularidade temporal deve ser compatível com tipo de período (date ou datetime).
• Unidade de medida de uma série deve ser consistente ao longo de todo o histórico.
• Toda promoção de modelo deve manter apenas uma instância ativa por série.
• Todo run de previsão concluído deve conter exatamente o tamanho do horizonte.
• Fallback degradado deve registrar origem da falha e versão efetivamente executada.

Como as camadas se conectam

• demand fornece histórico limpo para treino e inferência.
• modeling define quais estratégias podem ser usadas e qual instância está ativa.
• forecasting executa previsão usando a instância ativa e controla degradação em falha.
• shared garante que tempo, UOM, IDs e erros sigam o mesmo contrato em todo o domínio.

Leitura recomendada

1. Camada shared
2. Camada demand
3. Camada modeling
4. Camada forecasting
5. Interação entre camadas