---
type: rule
name: drive-entidades-internas
description: Consultar entidades do e-licencie (empreendedor, empreendimento, usuário) via eLicencieDrive com token interno
scope: local
trigger: model_decision
updatedAt: "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).

```ts
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`:

```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.

```ts
// ❌ 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.

```ts
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

```ts
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

```ts
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

```ts
// 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