.agent/global/rules/drive-entidades-internas.md

type	name	description	scope	trigger	updatedAt
rule	drive-entidades-internas	Consultar entidades do e-licencie (empreendedor, empreendimento, usuário) via eLicencieDrive com token interno	local	model_decision	2026-09-28

Regra: Consultar Entidades do e-licencie via Drive Interno

Contexto

Dentro de sigma-back/src/INFO/ e sigma-back/src/_FILAS/, quando um gerador de info ou um worker de fila precisa dos dados de empreendedor, empreendimento ou usuário, esses dados não existem localmente no banco do SIGMA — eles vivem no e-licencie. A consulta deve ser feita via eLicencieDrive com token interno, nunca retornando campos em branco (nome: "", documento: "").

Regra

1. Instanciar o drive com token interno

Sempre usar montarTokenInterno({ inquilino }) para autenticar o drive. O inquilino já está disponível no contexto do gerador (tipoGeradorInfo) e no worker de fila (extraído do schema).

import { eLicencieDrive, montarTokenInterno } from "../plugins/e-licencie-drive"

const drive = eLicencieDrive({ token: montarTokenInterno({ inquilino }) })

2. Preferir os helpers de cacheEntidadesDrive

Para buscas pontuais por código, usar os helpers prontos de sigma-back/src/e-licencie-drive/cacheEntidadesDrive.ts:

import {
  obterEmpreendedorPorCodigo,
  obterEmpreendimentoPorCodigo,
  obterUsuarioPorCodigo,
} from "../e-licencie-drive/cacheEntidadesDrive"

// dentro do gerador de info (já tem inquilino no contexto):
const empreendedor = await obterEmpreendedorPorCodigo(
  objeto.codigo_empreendedor,
  montarTokenInterno({ inquilino }),
)

3. Nunca retornar campos em branco

É proibido retornar nome: "" ou documento: "" quando esses dados podem ser obtidos pelo drive.

// ❌ ERRADO — dado em branco não tem utilidade para busca ou exibição
return respostaComuns.valor({
  codigo: objeto.codigo_empreendedor,
  nome: "",
  documento: "",
})

// ✅ CORRETO — consultar e retornar dados reais
const emp = await obterEmpreendedorPorCodigo(
  objeto.codigo_empreendedor,
  montarTokenInterno({ inquilino }),
)
return respostaComuns.valor({
  codigo: objeto.codigo_empreendedor,
  nome: emp?.nome ?? "",
  documento: emp?.documento ?? "",
})

4. O inquilino já está disponível — não inventar

Nos geradores de info (tipoGeradorInfo), o parâmetro { objeto, schema, inquilino } já inclui inquilino. Na fila _recalcular_todos_infos, o inquilino é extraído do schema via decodeURIComponent(parts[2]). Não é necessário buscá-lo de outra forma.

5. Tratar falha do drive com fallback

Se o drive retornar erro, registrar no log e retornar campos vazios — nunca lançar exceção que interrompa o recálculo global de infos.

const emp = await obterEmpreendedorPorCodigo(
  objeto.codigo_empreendedor,
  montarTokenInterno({ inquilino }),
)
if (!emp) {
  console.warn("[info] Empreendedor não encontrado no drive:", objeto.codigo_empreendedor)
}
return respostaComuns.valor({
  codigo: objeto.codigo_empreendedor,
  nome: emp?.nome ?? "",
  documento: emp?.documento ?? "",
})

Exemplos

✅ Correto — _registros.ts consultando drive

empreendedor: async ({ objeto, inquilino }) => {
  const emp = await obterEmpreendedorPorCodigo(
    objeto.codigo_empreendedor,
    montarTokenInterno({ inquilino }),
  )
  return respostaComuns.valor({
    codigo: objeto.codigo_empreendedor,
    nome: emp?.nome ?? "",
    documento: emp?.documento ?? "",
  })
},

❌ Incorreto — retornar em branco sem consultar

empreendedor: async ({ objeto }) => {
  return respostaComuns.valor({
    codigo: objeto.codigo_empreendedor,
    nome: "",       // ← proibido quando drive está disponível
    documento: "",  // ← proibido quando drive está disponível
  })
},

✅ Correto — worker de fila com drive

// inquilino já extraído do schema
const drive = eLicencieDrive({ token: montarTokenInterno({ inquilino }) })
const resultado = await drive.listarEmpreendedores()

Arquivos de referência

Arquivo	Papel
sigma-back/src/plugins/e-licencie-drive.ts	Ponto único de importação do drive + montarTokenInterno
sigma-back/src/e-licencie-drive/cacheEntidadesDrive.ts	Helpers: obterEmpreendedorPorCodigo, obterEmpreendimentoPorCodigo, obterUsuarioPorCodigo
sigma-back/src/INFO/tipagem.ts	Define tipoGeradorInfo<T> com { objeto, schema, inquilino }
sigma-back/src/INFO/index.ts	gravarInfo — repassa inquilino para cada gerador

Impacto

Sem esta regra:

• Campos nome e documento ficam em branco no JSONB info, quebrando buscas textuais e exibição no frontend
• O drive é instanciado sem uso (código morto)
• Geradores novos podem replicar o padrão incorreto sem saber que o drive está disponível