Fluxos principais

Visão geral dos fluxos

Fluxo	Caso de uso	Resultado
Treino e promoção	train_candidates_and_promote_champion	nova instância ACTIVE por série elegível, com audit trail e alias de serving
Ativação explícita	activate_model_instance	versão promovida e sincronizada com MLflow Registry
Inferência com fallback	run_forecast_with_fallback	ForecastRun concluído, preferindo ativo e degradando quando necessário

Fluxo 1: treino e promoção de campeão

Objetivo: decidir a melhor instância por série, com rastreabilidade completa de métricas e artefatos.

sequenceDiagram
    participant UC as UseCase
    participant MR as ModelingRepository
    participant DR as DemandRepository
    participant SR as StrategyRegistry
    participant TR as ExperimentTracker
    participant AS as ArtifactStore
    participant RG as ModelRegistry

    UC->>MR: get_model_definition(model_definition_id)
    UC->>DR: list_series(org_id, target_selector)
    UC->>UC: ensure_current_version()

    loop Para cada estratégia habilitada
        UC->>SR: resolve(strategy_key)
        alt execution.training_mode = series
            loop Para cada série elegível
                UC->>TR: start_run(...)
                UC->>SR: train(TrainRequest)
                UC->>TR: log_params/log_metrics
                alt artifact_uri presente
                    UC->>TR: log_artifact(artifact_uri)
                else artifact_payload presente
                    UC->>AS: store_artifact(...)
                    UC->>TR: log_artifact(uri)
                end
                UC->>TR: end_run(FINISHED)
                UC->>MR: add_instance(DRAFT, model_version=snapshot)
            end
        else execution.training_mode = batch
            UC->>TR: start_batch_run(...)
            UC->>SR: train_batch(BatchTrainRequest)
            UC->>TR: log_params/log_tags
            alt shared artifact_payload presente
                UC->>AS: store_batch_artifact(...)
                UC->>TR: log_artifact(uri)
            else shared artifact_uri presente
                UC->>TR: log_artifact(shared_artifact_uri)
            end
            loop Para cada série bem-sucedida
                alt artifact_payload por série
                    UC->>AS: store_artifact(...)
                end
                UC->>MR: add_instance(DRAFT, model_version=snapshot)
            end
            UC->>TR: end_run(FINISHED)
        end
    end

    UC->>MR: save_model_definition(candidatos DRAFT)
    UC->>UC: select_champion(policy)
    UC->>MR: save_promotion_audit_record(PENDING)
    UC->>RG: register_model_version(...)
    UC->>MR: promote_instance(series_key, version)
    UC->>MR: save_model_definition(model_definition)
    UC->>RG: promote_model_version(alias=champion)
    UC->>MR: save_promotion_audit_record(COMPLETED)

Entradas e saídas do fluxo 1

• Entrada: TrainCandidatesAndPromoteChampionCommand(model_definition_id=...).
• Saída: lista de PromotionResult para séries promovidas.
• Persistências críticas: ModelDefinition, PromotionAuditRecord, runs do tracker e artefatos.

Fluxo 2: inferência com fallback degradado

Objetivo: preservar continuidade de previsão quando o modelo ativo falha.

sequenceDiagram
    participant UC as UseCase
    participant MR as ModelingRepository
    participant SR as StrategyRegistry
    participant FR as ForecastingRepository
    participant FO as ForecastObservability

    UC->>MR: get_model_definition(run.model_definition_id)
    UC->>UC: run.start()
    UC->>MR: active_instance_for_series(series_key)

    alt instância ativa existe
        UC->>SR: resolve(primary.strategy_key)
        UC->>SR: predict(PredictRequest)
        alt predição primária funciona
            UC->>UC: run.set_executed_model_version(primary.version)
            UC->>UC: run.complete(points)
        else falha da primária
            UC->>MR: previous_instance_for_series(series_key, primary.version)
            alt fallback existe e funciona
                UC->>SR: predict(com fallback)
                UC->>UC: run.mark_degraded_fallback(...)
                UC->>UC: run.complete(points)
            else fallback indisponível/falha
                UC->>UC: run.fail(reason)
            end
        end
    else sem instância ativa
        UC->>UC: run.fail("No active model instance...")
    end

    UC->>FR: save_forecast_run(run)
    UC->>FO: record_forecast(telemetry)

Entradas e saídas do fluxo 2

• Entrada: RunForecastWithFallbackCommand(run, series).
• Saída: ForecastRun em COMPLETED ou FAILED.
• Persistências críticas: metadados de fallback e pontos previstos válidos.
• Sinais críticos: fallback rate, executed model version e duração por run.

Máquina de estados de execução de previsão

stateDiagram-v2
    [*] --> REQUESTED
    REQUESTED --> RUNNING
    RUNNING --> COMPLETED: primário ou fallback válido
    RUNNING --> FAILED: sem ativo ou sem fallback válido

Garantias de produto fornecidas pelos fluxos

• run concluído sempre tem horizonte completo (horizon_spec.periods);
• fallback degradado sempre registra versão de origem e versão executada;
• falhas de estratégia não violam invariantes do domínio.
• batch training preserva promoção, ativação e fallback por série.
• toda ativação pode ser auditada por ator, motivo e evidência métrica.
• toda execução de forecast pode gerar telemetria desacoplada do domínio.

Falhas esperadas e tratamento

Cenário	Comportamento esperado
Estratégia falha no treino	run de treino marcado como FAILED; fluxo continua com candidatos restantes
Instância ativa falha na predição	tenta versão anterior (fallback) automaticamente
Sem instância ativa ou fallback indisponível	run finaliza em FAILED com motivo explícito