investigation

Tipo

Referência

Para

Desenvolvedor, Analista

Numa investigation (Investigação), uma pergunta de negócio ganha verificações que rodam numa agenda e listam achados para alguém revisar. O arquivo fica em investigations/<slug>--<id>.yaml. O que as Investigações fazem está em Investigações.

lumo new investigation --name "Margem entre filiais" --question "Alguma filial está com margem bem abaixo das outras?"
lumo info app:7302 --full     # ids dos indicadores e das colunas

Campos

• fileName
  string · opcional · valores: regex ^[a-z0-9-]+--\d+\.yaml$
• header
  object · obrigatório
• header.id
  integer · obrigatório · valores: ≥ 1
• header.kind
  string · obrigatório · valores: investigation (fixo)
• header.lumo
  string · obrigatório · valores: v2 (fixo)
• header.tenantId
  integer · obrigatório · valores: ≥ 1
• header.appId
  integer · opcional · valores: ≥ 1
• header.dashboardId
  integer · opcional · valores: ≥ 1
• body
  object · obrigatório
• body.criado_em
  string ou null · opcional · valores: regex ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$
  Somente leitura: o servidor preenche.
• body.criado_por
  string ou integer ou null · opcional
  Somente leitura: o servidor preenche.
• body.publicado_em
  string ou null · opcional · valores: regex ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$
  Somente leitura: o servidor preenche.
• body.publicado_por
  string ou integer ou null · opcional
  Somente leitura: o servidor preenche.
• body.nome
  string · obrigatório · valores: não vazio
• body.pergunta
  string · obrigatório
  Briefing da investigação (chamado briefing no backend): o contexto de negócio que a IA usa para julgar cada achado. O backend recusa menos de 20 caracteres - uma frase curta produz veredito genérico.
• body.publicada
  boolean · obrigatório
  Server-managed a partir de POST /investigation/:id/publish ou de um push que muda false → true (equivalentes). NÃO existe caminho de volta: o backend recusa true → false neste campo (duplique e exclua a publicada para desfazer).
• body.status
  string · obrigatório · valores: active, paused
  active roda na agenda; paused não dispara sozinha mas pode ser rodada com lumo investigation run.
• body.agenda
  object · obrigatório
• body.agenda.tipo
  string · obrigatório · valores: manual, daily, weekly
  manual nunca dispara sozinha (só via lumo investigation run ou pela tela); daily roda toda vez às hora; weekly roda em dia_semana às hora.
• body.agenda.hora
  integer ou null · obrigatório · valores: ≥ 0, ≤ 23
  Hora local do tenant (0-23). O backend preenche 6 por default na criação quando ausente.
• body.agenda.dia_semana
  integer ou null · obrigatório · valores: ≥ 0, ≤ 6
  0=domingo … 6=sábado. Só faz sentido (e só é exigido) quando tipo=weekly; nos outros tipos o backend grava null.
• body.verificacoes
  array de object · obrigatório
  As sondas (probes) desta investigação - cada uma roda um runner da Sentinela contra o app declarado em config.universo.app_id. Ver lumo scaffold investigation (peers) e lumo scaffold investigation change para exemplos; o shape de config é específico do runner e validado pelo backend (não duplicado aqui de propósito).
• body.verificacoes[].id
  integer · opcional · valores: ≥ 1
  Ausente ao criar uma verificação nova; o servidor atribui o id no push.
• body.verificacoes[].runner
  string · obrigatório · valores: não vazio
  Nome do runner registrado no backend (hoje: peers e change - catálogo aberto, o backend valida contra o registro no momento do push, então não é travado num enum aqui).
• body.verificacoes[].rotulo
  string · obrigatório · valores: não vazio
  Nome de exibição desta verificação (chamado label no backend).
• body.verificacoes[].ativa
  boolean · obrigatório
  false pula esta verificação nas rodadas sem removê-la (chamado enabled no backend).
• body.verificacoes[].config
  object · obrigatório
  JSON específico do runner (sonda, universo, colunas, janela, filtros, knobs, ...). O backend valida a config inteira contra o schema Zod do runner ao salvar; um objeto que passa aqui ainda pode ser recusado no push por uma regra do runner.

Exemplo

# investigations/margem-entre-filiais--88.yaml
# yaml-language-server: $schema=https://docs.horusbi.com.br/schemas/v2/investigation.schema.json
id: 88
kind: investigation
lumo: v2
tenantId: 1200
---
nome: Margem entre filiais
# O contexto que a IA usa para julgar cada achado. Mínimo de 20 caracteres.
pergunta: >-
  Alguma filial está com margem bem abaixo das outras, vendendo os mesmos produtos?
publicada: false                 # true é sem volta
status: active                   # paused não roda na agenda, mas roda com lumo investigation run
agenda:
  tipo: weekly                   # manual | daily | weekly
  hora: 6                        # 0 a 23, hora local do Tenant
  dia_semana: 1                  # 0 = domingo; sempre presente, só vale em weekly
verificacoes:
  - runner: peers                # cada filial contra as outras
    rotulo: Margem por filial
    ativa: true
    config:
      sonda: Margem por filial
      universo:
        app_id: 7302
        nome: Comercial
      indicador_id: 15           # numerador: indicador curado (Lucro bruto)
      volume_id: 14              # denominador: indicador da mesma Aplicação (Faturamento)
      quem: { column_id: 70020 } # quem é comparado (Filial)
      direcao: desce_ruim
      nome_taxa: Margem

As verificações

Há dois tipos de verificação (runner). lumo investigation runners lista os campos de config que cada um aceita.

runner	O que procura	Modelo
peers	Uma taxa (numerador sobre denominador) por entidade, comparada às outras do mesmo grupo	lumo scaffold investigation
change	O que mudou num indicador neste mês, e em que dimensões	lumo scaffold investigation change

Limites

• publicada: true não tem volta: o servidor recusa voltar para false, e não há comando para despublicar. Para desfazer, duplique a Investigação pela tela e apague a publicada. lumo investigation publish é o mesmo que mudar o campo para true e dar push.
• Publicar também torna curados os indicadores pessoais citados nas verificações, porque quem lê a Investigação publicada não enxerga indicador pessoal. Por isso publicar exige a mesma permissão de curar indicador.
• Criar e editar exige as Investigações liberadas no Tenant (sem elas, o servidor responde SENTINELA_DISABLED) e permissão de criar alerta.
• Tirar uma verificação do arquivo a apaga no push.
• pergunta precisa de pelo menos 20 caracteres. Uma frase curta demais produz achados genéricos.
• status: paused não roda na agenda, mas lumo investigation run roda na hora. lumo investigation findings mostra os achados da última rodada.
• O servidor valida config no push e a mensagem de erro diz qual campo está errado. Depois do primeiro push, cada verificação ganha um id: mantenha-o ao editar.