152 lines
5 KiB
Markdown
152 lines
5 KiB
Markdown
---
|
|
type: rule
|
|
name: drive-entidades-internas
|
|
description: Consultar entidades compartilhadas (empreendedor, empreendimento, usuário) via Drive SSO com token interno
|
|
scope: local
|
|
trigger: model_decision
|
|
updatedAt: "2026-10-14"
|
|
---
|
|
|
|
# Regra: Consultar Entidades Compartilhadas via Drive Interno
|
|
|
|
## Contexto
|
|
|
|
Nos módulos do ecossistema (identificados em `memorias-ia/modulo.yml`), dentro de `<modulo>-back/src/INFO/` e `<modulo>-back/src/_FILAS/`, quando um gerador de info ou um worker de fila precisa dos dados de **empreendedor**, **empreendimento** ou **usuário** providos via SSO/Drive, esses dados **não existem localmente no banco do módulo** — eles vivem no serviço centralizado de diretório/SSO (`eLicencieDrive`). 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
|
|
`<modulo>-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 |
|
|
|---|---|
|
|
| `<modulo>-back/src/plugins/e-licencie-drive.ts` | Ponto único de importação do drive + `montarTokenInterno` |
|
|
| `<modulo>-back/src/e-licencie-drive/cacheEntidadesDrive.ts` | Helpers: `obterEmpreendedorPorCodigo`, `obterEmpreendimentoPorCodigo`, `obterUsuarioPorCodigo` |
|
|
| `<modulo>-back/src/INFO/tipagem.ts` | Define `tipoGeradorInfo<T>` com `{ objeto, schema, inquilino }` |
|
|
| `<modulo>-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
|