.

rules/drive-entidades-internas.md

@@ -0,0 +1,147 @@
+# 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