forlogic-core 1.7.2 → 1.7.4

package/README.md

@@ -873,6 +873,183 @@ KR1 50% dos indicadores de empreendimento e áreas de negócio atingindo a meta
 
 ---
 
+### 🔗 Enrichment de Múltiplos Campos de Usuário do Qualiex
+
+O `forlogic-core` suporta enriquecimento automático de **múltiplos campos de ID de usuário** com dados do Qualiex (nome, email, username).
+
+#### **Configuração Global**
+
+Configure o enrichment uma vez na inicialização do app:
+
+```typescript
+import { setQualiexConfig } from 'forlogic-core';
+
+// Configuração básica (usa localStorage como fallback)
+setQualiexConfig({
+  enableUserEnrichment: true,
+  enableUsersApi: true,
+});
+
+// Configuração avançada (recomendado)
+setQualiexConfig({
+  enableUserEnrichment: true,
+  enableUsersApi: true,
+  getAccessToken: () => localStorage.getItem('qualiex_access_token'),
+  getCompanyId: () => localStorage.getItem('selectedUnitId'),
+  userNameFieldSuffix: '_name',   // default
+  userEmailFieldSuffix: '_email', // default
+  userUsernameFieldSuffix: '_username', // default
+});
+```
+
+#### **Uso Básico: Lista de Campos de ID**
+
+Use `userIdFields` para enriquecer múltiplos campos de ID automaticamente:
+
+```typescript
+import { createSimpleService } from 'forlogic-core';
+
+const { service, useCrudHook } = createSimpleService({
+  tableName: 'evaluations',
+  schemaName: 'performance',
+  entityName: 'Avaliação',
+  searchFields: ['title', 'description'],
+  enableQualiexEnrichment: true,
+  
+  // ✅ Lista de campos de ID para enriquecer
+  userIdFields: ['target_user_id', 'evaluator_user_id'],
+});
+```
+
+**Resultado automático:**
+- `target_user_id` → `target_user_name` (nome do usuário)
+- `evaluator_user_id` → `evaluator_user_name` (nome do usuário)
+
+#### **Uso Avançado: Mapeamento Customizado**
+
+Use `userFieldsMapping` para controlar exatamente quais campos de saída criar:
+
+```typescript
+const { service, useCrudHook } = createSimpleService({
+  tableName: 'evaluations',
+  entityName: 'Avaliação',
+  enableQualiexEnrichment: true,
+  
+  // ✅ Mapeamento granular de campos
+  userFieldsMapping: [
+    {
+      idField: 'target_user_id',
+      nameField: 'avaliado_nome',      // customizado
+      emailField: 'avaliado_email',    // opcional
+    },
+    {
+      idField: 'evaluator_user_id',
+      nameField: 'avaliador_nome',
+      emailField: 'avaliador_email',
+      usernameField: 'avaliador_username', // opcional
+    },
+  ],
+});
+```
+
+**Resultado customizado:**
+- `target_user_id` → `avaliado_nome`, `avaliado_email`
+- `evaluator_user_id` → `avaliador_nome`, `avaliador_email`, `avaliador_username`
+
+#### **Enrichment Manual (Casos Avançados)**
+
+Para casos onde você precisa enriquecer dados fora do `createSimpleService`:
+
+```typescript
+import { QualiexEnrichmentService } from 'forlogic-core';
+
+// Enriquecer entidades manualmente
+const enrichedData = await QualiexEnrichmentService.enrichWithUserData(entities, {
+  entityName: 'Avaliações',
+  userIdFields: ['target_user_id', 'evaluator_user_id'],
+});
+
+// Ou com mapeamento customizado
+const enrichedData = await QualiexEnrichmentService.enrichWithUserData(entities, {
+  entityName: 'Avaliações',
+  userFieldsMapping: [
+    { idField: 'target_user_id', nameField: 'avaliado_nome' },
+    { idField: 'evaluator_user_id', nameField: 'avaliador_nome' },
+  ],
+});
+```
+
+#### **Utilitários de Derivação de Campos**
+
+Use helpers para gerar nomes de campos de forma consistente:
+
+```typescript
+import { deriveNameField, deriveEmailField } from 'forlogic-core';
+
+deriveNameField('target_user_id');    // => "target_user_name"
+deriveEmailField('evaluator_user_id'); // => "evaluator_user_email"
+```
+
+#### **Retrocompatibilidade**
+
+O comportamento legado (`id_user` → `responsible_name`) continua funcionando sem mudanças:
+
+```typescript
+// Código antigo funciona normalmente
+const { service } = createSimpleService({
+  tableName: 'processes',
+  entityName: 'Processo',
+  enableQualiexEnrichment: true,
+  // Automaticamente enriquece id_user -> responsible_name
+});
+```
+
+#### **Características**
+
+✅ **Cache inteligente**: Usuários Qualiex são cacheados por 5 minutos  
+✅ **Resiliência**: Falhas não quebram a UI (apenas logs no console)  
+✅ **Deduplicação**: IDs duplicados são buscados apenas uma vez  
+✅ **Não sobrescreve**: Campos já preenchidos não são alterados  
+✅ **Type-safe**: TypeScript valida configurações  
+✅ **Retrocompatível**: Projetos antigos continuam funcionando  
+
+#### **Boas Práticas**
+
+✅ **BOM**: Configurar `getAccessToken` e `getCompanyId` para evitar dependência de localStorage
+
+```typescript
+setQualiexConfig({
+  enableUserEnrichment: true,
+  getAccessToken: async () => {
+    // Buscar token de forma segura (ex: context, Zustand, etc)
+    return myAuthStore.getToken();
+  },
+  getCompanyId: () => myAppStore.getSelectedCompanyId(),
+});
+```
+
+❌ **EVITAR**: Múltiplos campos apontando para o mesmo campo de saída
+
+```typescript
+// ❌ Conflito: ambos escrevem em "user_name"
+userFieldsMapping: [
+  { idField: 'created_by_id', nameField: 'user_name' },
+  { idField: 'updated_by_id', nameField: 'user_name' }, // Conflito!
+]
+```
+
+✅ **BOM**: Usar sufixos distintos
+
+```typescript
+// ✅ Campos de saída únicos
+userFieldsMapping: [
+  { idField: 'created_by_id', nameField: 'created_by_name' },
+  { idField: 'updated_by_id', nameField: 'updated_by_name' },
+]
+```
+
+---
+
 ### 🏢 Sistema de Gestores de Locais (Qualiex)
 
 Componentes para gerenciamento de gestores e membros de locais/sublocais integrados com a API Qualiex.

package/dist/README.md

@@ -873,6 +873,183 @@ KR1 50% dos indicadores de empreendimento e áreas de negócio atingindo a meta
 
 ---
 
+### 🔗 Enrichment de Múltiplos Campos de Usuário do Qualiex
+
+O `forlogic-core` suporta enriquecimento automático de **múltiplos campos de ID de usuário** com dados do Qualiex (nome, email, username).
+
+#### **Configuração Global**
+
+Configure o enrichment uma vez na inicialização do app:
+
+```typescript
+import { setQualiexConfig } from 'forlogic-core';
+
+// Configuração básica (usa localStorage como fallback)
+setQualiexConfig({
+  enableUserEnrichment: true,
+  enableUsersApi: true,
+});
+
+// Configuração avançada (recomendado)
+setQualiexConfig({
+  enableUserEnrichment: true,
+  enableUsersApi: true,
+  getAccessToken: () => localStorage.getItem('qualiex_access_token'),
+  getCompanyId: () => localStorage.getItem('selectedUnitId'),
+  userNameFieldSuffix: '_name',   // default
+  userEmailFieldSuffix: '_email', // default
+  userUsernameFieldSuffix: '_username', // default
+});
+```
+
+#### **Uso Básico: Lista de Campos de ID**
+
+Use `userIdFields` para enriquecer múltiplos campos de ID automaticamente:
+
+```typescript
+import { createSimpleService } from 'forlogic-core';
+
+const { service, useCrudHook } = createSimpleService({
+  tableName: 'evaluations',
+  schemaName: 'performance',
+  entityName: 'Avaliação',
+  searchFields: ['title', 'description'],
+  enableQualiexEnrichment: true,
+  
+  // ✅ Lista de campos de ID para enriquecer
+  userIdFields: ['target_user_id', 'evaluator_user_id'],
+});
+```
+
+**Resultado automático:**
+- `target_user_id` → `target_user_name` (nome do usuário)
+- `evaluator_user_id` → `evaluator_user_name` (nome do usuário)
+
+#### **Uso Avançado: Mapeamento Customizado**
+
+Use `userFieldsMapping` para controlar exatamente quais campos de saída criar:
+
+```typescript
+const { service, useCrudHook } = createSimpleService({
+  tableName: 'evaluations',
+  entityName: 'Avaliação',
+  enableQualiexEnrichment: true,
+  
+  // ✅ Mapeamento granular de campos
+  userFieldsMapping: [
+    {
+      idField: 'target_user_id',
+      nameField: 'avaliado_nome',      // customizado
+      emailField: 'avaliado_email',    // opcional
+    },
+    {
+      idField: 'evaluator_user_id',
+      nameField: 'avaliador_nome',
+      emailField: 'avaliador_email',
+      usernameField: 'avaliador_username', // opcional
+    },
+  ],
+});
+```
+
+**Resultado customizado:**
+- `target_user_id` → `avaliado_nome`, `avaliado_email`
+- `evaluator_user_id` → `avaliador_nome`, `avaliador_email`, `avaliador_username`
+
+#### **Enrichment Manual (Casos Avançados)**
+
+Para casos onde você precisa enriquecer dados fora do `createSimpleService`:
+
+```typescript
+import { QualiexEnrichmentService } from 'forlogic-core';
+
+// Enriquecer entidades manualmente
+const enrichedData = await QualiexEnrichmentService.enrichWithUserData(entities, {
+  entityName: 'Avaliações',
+  userIdFields: ['target_user_id', 'evaluator_user_id'],
+});
+
+// Ou com mapeamento customizado
+const enrichedData = await QualiexEnrichmentService.enrichWithUserData(entities, {
+  entityName: 'Avaliações',
+  userFieldsMapping: [
+    { idField: 'target_user_id', nameField: 'avaliado_nome' },
+    { idField: 'evaluator_user_id', nameField: 'avaliador_nome' },
+  ],
+});
+```
+
+#### **Utilitários de Derivação de Campos**
+
+Use helpers para gerar nomes de campos de forma consistente:
+
+```typescript
+import { deriveNameField, deriveEmailField } from 'forlogic-core';
+
+deriveNameField('target_user_id');    // => "target_user_name"
+deriveEmailField('evaluator_user_id'); // => "evaluator_user_email"
+```
+
+#### **Retrocompatibilidade**
+
+O comportamento legado (`id_user` → `responsible_name`) continua funcionando sem mudanças:
+
+```typescript
+// Código antigo funciona normalmente
+const { service } = createSimpleService({
+  tableName: 'processes',
+  entityName: 'Processo',
+  enableQualiexEnrichment: true,
+  // Automaticamente enriquece id_user -> responsible_name
+});
+```
+
+#### **Características**
+
+✅ **Cache inteligente**: Usuários Qualiex são cacheados por 5 minutos  
+✅ **Resiliência**: Falhas não quebram a UI (apenas logs no console)  
+✅ **Deduplicação**: IDs duplicados são buscados apenas uma vez  
+✅ **Não sobrescreve**: Campos já preenchidos não são alterados  
+✅ **Type-safe**: TypeScript valida configurações  
+✅ **Retrocompatível**: Projetos antigos continuam funcionando  
+
+#### **Boas Práticas**
+
+✅ **BOM**: Configurar `getAccessToken` e `getCompanyId` para evitar dependência de localStorage
+
+```typescript
+setQualiexConfig({
+  enableUserEnrichment: true,
+  getAccessToken: async () => {
+    // Buscar token de forma segura (ex: context, Zustand, etc)
+    return myAuthStore.getToken();
+  },
+  getCompanyId: () => myAppStore.getSelectedCompanyId(),
+});
+```
+
+❌ **EVITAR**: Múltiplos campos apontando para o mesmo campo de saída
+
+```typescript
+// ❌ Conflito: ambos escrevem em "user_name"
+userFieldsMapping: [
+  { idField: 'created_by_id', nameField: 'user_name' },
+  { idField: 'updated_by_id', nameField: 'user_name' }, // Conflito!
+]
+```
+
+✅ **BOM**: Usar sufixos distintos
+
+```typescript
+// ✅ Campos de saída únicos
+userFieldsMapping: [
+  { idField: 'created_by_id', nameField: 'created_by_name' },
+  { idField: 'updated_by_id', nameField: 'updated_by_name' },
+]
+```
+
+---
+
 ### 🏢 Sistema de Gestores de Locais (Qualiex)
 
 Componentes para gerenciamento de gestores e membros de locais/sublocais integrados com a API Qualiex.