forlogic-core 3.0.10 → 4.0.0

package/docs/design-system/patterns/core-providers.md

@@ -1,258 +0,0 @@
-# Padrão: CoreProviders Setup
-
-## Providers incluídos
-
-| Provider | Descrição |
-|----------|-----------|
-| ErrorBoundary | Captura erros de renderização React |
-| I18nextProvider | Sistema de internacionalização |
-| QueryClientProvider | Cache e queries (React Query) |
-| AuthProvider | Autenticação e sessão |
-| LocaleProvider | Idioma, timezone, formato de data |
-| ModuleProvider | Configuração de módulo ativo |
-| ModuleAccessGuard | Bloqueio de acesso por módulo |
-
-## Uso básico
-
-```tsx
-<CoreProviders moduleAlias="performance" appTranslations={{ 'pt-BR': ptBR }}>
-  <BrowserRouter>
-    <Routes />
-  </BrowserRouter>
-</CoreProviders>
-```
-
-## Props
-
-| Prop | Tipo | Obrigatório | Descrição |
-|------|------|-------------|-----------|
-| children | ReactNode | Sim | Componentes filhos |
-| queryClient | QueryClient | Não | Instância customizada (default criado automaticamente) |
-| moduleAlias | string | Não | Alias canônico do módulo para acesso e filtro de atualizações. Obrigatório na prática quando o app usa `AppLayout`/`UserUpdatesViewer`; sem um alias reconhecido, atualizações segmentadas são ocultadas. |
-| moduleApiUrl | string | Não | (DEPRECATED — substituído por `associationsBaseUrl`) |
-| associationsBaseUrl | string | Não | Base URL completa para `/Users/{userId}/associations`. Ver seção abaixo. |
-| moduleAccessGuardProps | object | Não | Props para o ModuleAccessGuard |
-| appTranslations | Record<string, Record<string, string>> | Não | Traduções por idioma no namespace 'app' |
-| clarityProjectId | string | Não | Project ID do Microsoft Clarity. Sem ele, integração desativada. |
-| clarityMode | 'auto' \| 'disabled' | Não | Opt-out do tracking Clarity. Default `'auto'`. |
-| backend | 'supabase' \| 'dotnet' | Não | Backend ativo. Default `'supabase'`. Ver seção abaixo. |
-| signDocumentsSchema | string | Não | Schema onde a tabela de tracking do D4Sign vive neste projeto. Default `'common'`. Ver seção abaixo. |
-| signDocumentsTable | string | Não | Nome da tabela de tracking. Default `'sign_documents'`. |
-
-## Tabela `sign_documents` por schema (D4Sign)
-
-Por padrão, o webhook D4Sign grava o resultado em `common.sign_documents`. Projetos que mantêm a tabela no próprio schema (ex.: Educação) podem redirecionar via:
-
-```tsx
-<CoreProviders
-  moduleAlias="educacao"
-  signDocumentsSchema="educacao"
-  // signDocumentsTable opcional — default 'sign_documents'
->
-  ...
-</CoreProviders>
-```
-
-O que acontece:
-
-1. `DocumentSigner` envia `target_schema` e `target_table` para a edge function `d4sign` no `create_and_send`.
-2. A edge function `d4sign` insere a linha `pending` no schema/tabela alvo e registra o webhook do D4Sign com a URL `/functions/v1/d4sign-webhook?schema={schema}&table={table}`.
-3. A edge function `d4sign-webhook` lê os query params, valida contra uma **allowlist** de schemas (`common`, `educacao`, `treinamentos`, `inovacao`, `public`) e faz o `UPDATE` no schema correto.
-4. O front se inscreve no Realtime no mesmo schema/tabela.
-
-**Requisitos no projeto consumidor:**
-
-Cada projeto que redirecionar o destino precisa criar a tabela no seu próprio schema com **exatamente** o contrato abaixo — os nomes e tipos das colunas são consumidos pelas edge functions `d4sign` e `d4sign-webhook` e pelo `DocumentSigner`. Divergir quebra o fluxo.
-
-### Contrato de campos
-
-| Campo | Tipo | Obrigatório | Default | Preenchido por |
-|---|---|---|---|---|
-| `document_id` | `text` PK | sim | — | front (`DocumentSigner`, `crypto.randomUUID()`) |
-| `alias` | `text` | sim | — | front |
-| `provider` | `text` | sim | `'d4sign'` | front |
-| `envelope_id` | `text` | sim | — | edge `d4sign` (UUID retornado pelo D4Sign) |
-| `signer_email` | `text` | sim | — | front |
-| `signer_name` | `text` | não | — | front |
-| `filename` | `text` | não | — | front |
-| `status` | `text` | sim | `'pending'` | webhook (`pending` → `signed` / `cancelled` / `failed`) |
-| `signed_at` | `timestamptz` | não | — | webhook |
-| `download_url` | `text` | não | — | webhook |
-| `download_url_expires_at` | `timestamptz` | não | — | webhook (~50 min) |
-| `raw_webhook_payload` | `jsonb` | não | — | webhook |
-| `created_at` | `timestamptz` | sim | `now()` | DB |
-| `updated_at` | `timestamptz` | sim | `now()` | trigger |
-
-> **PK em `document_id`** (não `id` serial) — é a chave que o front usa para correlacionar o envelope com a row.
-
-### Script SQL (substituir `{schema}`)
-
-```sql
-CREATE TABLE {schema}.sign_documents (
-  document_id text PRIMARY KEY,
-  alias text NOT NULL,
-  provider text NOT NULL DEFAULT 'd4sign',
-  envelope_id text NOT NULL,
-  signer_email text NOT NULL,
-  signer_name text,
-  filename text,
-  status text NOT NULL DEFAULT 'pending',
-  download_url text,
-  download_url_expires_at timestamptz,
-  raw_webhook_payload jsonb,
-  signed_at timestamptz,
-  created_at timestamptz NOT NULL DEFAULT now(),
-  updated_at timestamptz NOT NULL DEFAULT now()
-);
-
-CREATE INDEX sign_documents_alias_status_idx ON {schema}.sign_documents (alias, status);
-CREATE INDEX sign_documents_envelope_idx     ON {schema}.sign_documents (envelope_id);
-
-GRANT SELECT ON {schema}.sign_documents TO authenticated;
-GRANT ALL    ON {schema}.sign_documents TO service_role;
-
-ALTER TABLE {schema}.sign_documents ENABLE ROW LEVEL SECURITY;
-
-CREATE POLICY "sign_documents_select_own_tenant"
-  ON {schema}.sign_documents
-  FOR SELECT
-  TO authenticated
-  USING (alias = ((SELECT auth.jwt()) ->> 'alias'));
-
-CREATE OR REPLACE FUNCTION {schema}.sign_documents_set_updated_at()
-RETURNS TRIGGER LANGUAGE plpgsql SET search_path = {schema}, public AS $$
-BEGIN NEW.updated_at = now(); RETURN NEW; END;
-$$;
-
-CREATE TRIGGER sign_documents_updated_at
-  BEFORE UPDATE ON {schema}.sign_documents
-  FOR EACH ROW EXECUTE FUNCTION {schema}.sign_documents_set_updated_at();
-
--- Realtime — obrigatório, senão o DocumentSigner nunca recebe o evento de assinatura
-ALTER TABLE {schema}.sign_documents REPLICA IDENTITY FULL;
-ALTER PUBLICATION supabase_realtime ADD TABLE {schema}.sign_documents;
-```
-
-### Notas importantes
-
-- **`sign_configs` continua em `common`** — o webhook lê de lá independentemente do schema alvo. Cada projeto que usa assinatura precisa ter `common.sign_configs` populado (via `/a/cs` no Admin).
-- **`REPLICA IDENTITY FULL` + entrada na publication `supabase_realtime`** são obrigatórios. Sem isso, o `DocumentSigner` fica em loading eterno após assinar.
-- **Schemas novos** precisam ser adicionados à constante `ALLOWED_SCHEMAS` em `supabase/functions/d4sign/index.ts` **e** `supabase/functions/d4sign-webhook/index.ts`, senão o webhook silenciosamente cai para `common` (proteção anti-SSRF).
-
-**Retrocompatibilidade:** sem essas props, tudo continua apontando para `common.sign_documents` — Admin segue funcionando inalterado.
-
-
-## Associações em outra base URL
-
-Por padrão, `useModuleAccess` (e o `ModuleAccessGuard`) busca as associações em:
-
-```
-{QUALIEX_API_URL}/api/common/v1/Users/{userId}/associations
-```
-
-Quando o módulo expõe seu próprio endpoint de associações, informe `associationsBaseUrl` no `CoreProviders`. A lib passa a chamar:
-
-```
-{associationsBaseUrl}/Users/{userId}/associations
-```
-
-`associationsBaseUrl` deve incluir todo o prefixo (host + `/api/{modulo}/v1`):
-
-```tsx
-<CoreProviders
-  backend="dotnet"
-  associationsBaseUrl={import.meta.env.VITE_ASSOCIATIONS_API_URL}
-  // ex: "https://api.qualiex.com/api/inovacao/v1"
->
-  ...
-</CoreProviders>
-```
-
-Características:
-
-- **Uma única variável** — não exige `moduleAlias`. Pode ser usada sem ativar o `ModuleAccessGuard` (útil enquanto o software do módulo ainda não foi cadastrado no `SOFTWARES_MAP` da lib).
-- A API alvo deve responder no mesmo contrato (`UserAssociation[]`) e aceitar os headers `Authorization: Bearer <token>` e `un-alias: <alias>`.
-- Demais endpoints (`/companiesusers`, `/softwares`) continuam consultando a common.
-
-
-## Backend (Supabase opcional)
-
-A prop `backend` controla se a lib usa o stack Supabase ou apenas a API .NET do Qualiex.
-
-- `'supabase'` (default, retrocompat): inicializa o cliente Supabase, valida tokens via Edge Function `validate-token` e exige `SUPABASE_URL` + `SUPABASE_PUBLISHABLE_KEY` (ou as versões `VITE_SUPABASE_*` legadas) no `.env`. O `vite.config.ts` consolida ambos os formatos via `resolveSupabaseEnv()` — ver `docs/design-system/patterns/feature-flags.md`.
-- `'dotnet'`: a lib **não** chama Supabase em nenhum momento da inicialização. O `AuthProvider` autentica apenas com os tokens OAuth do Qualiex (`access_token` + `id_token`). Não exige envs do Supabase. **Importante:** defina `VITE_APP_ENV="DEV"` no `.env` quando o app rodar contra o ambiente dev do Qualiex — sem essa variável, o failsafe assume `PROD`.
-
-### Exemplos de uso por backend
-
-```tsx
-// ============================================================
-// Módulo COM Supabase (default — não precisa declarar backend)
-// ============================================================
-// .env obrigatório:
-//   SUPABASE_URL="https://<project>.supabase.co"
-//   SUPABASE_PUBLISHABLE_KEY="sb_publishable_..."
-//   VITE_SUPABASE_PK_OVERRIDE="sb_publishable_..."
-//
-import { CoreProviders } from 'forlogic-core';
-import { BrowserRouter } from 'react-router';
-import pt from '@/locales/pt-BR.json';
-
-<CoreProviders moduleAlias="performance" appTranslations={{ 'pt-BR': pt }}>
-  <BrowserRouter>
-    <Routes />
-  </BrowserRouter>
-</CoreProviders>
-```
-
-```tsx
-// ============================================================
-// Módulo SEM Supabase (ex.: Documentos, APIs próprias)
-// ============================================================
-// .env obrigatório:
-//   VITE_APP_ENV="DEV"   // ou "PROD"
-//
-// Nenhuma env do Supabase é exigida.
-//
-import { CoreProviders } from 'forlogic-core';
-import { BrowserRouter } from 'react-router';
-import pt from '@/locales/pt-BR.json';
-
-<CoreProviders
-  backend="dotnet"
-  moduleAlias="documents"
-  appTranslations={{ 'pt-BR': pt }}
->
-  <BrowserRouter>
-    <Routes />
-  </BrowserRouter>
-</CoreProviders>
-```
-
-
-### O que funciona sem Supabase em `backend="dotnet"`
-
-A lib mantém os seguintes recursos funcionando 100% sem nenhuma env var Supabase:
-
-- **Logos e favicon** (`assets`, `logoSrc`, `smallLogoSrc`): servidos a partir de bucket público fixo embutido na lib.
-- **Login automático em dev/preview**: `shouldUseDevTokens()` agora exige modo Supabase, então em modo dotnet o `ProtectedRoute` sempre vai para `loginProd()` (OAuth real), mesmo em `localhost`/Lovable preview.
-- **Logoff manual**: `TokenManager.clearAll()` preserva o flag `manual_logout`, garantindo que `logout()` realmente deslogue (sem auto-login no próximo render).
-- **`LegacyKeyBanner`**: oculto automaticamente em modo dotnet.
-
-### Features que continuam exigindo Supabase
-
-Mesmo com `backend="dotnet"`, se você importar qualquer um dos módulos abaixo eles vão falhar em runtime sem Supabase configurado:
-
-- `forlogic-core/sign`
-- `forlogic-core/audit-trail`
-- `forlogic-core/action-plans`
-- `forlogic-core/leadership`
-- `forlogic-core/places`
-- `EmailService` (do barrel principal)
-
-Esses módulos **foram removidos do barrel principal** (breaking change) — importe-os via subpath quando precisar. Use `isSupabaseConfigured()` para checar disponibilidade antes de chamar `getSupabaseClient()`.
-
-## QueryClient default
-
-```ts
-{ defaultOptions: { queries: { staleTime: 5 * 60 * 1000, retry: 1 } } }
-```

package/docs/design-system/patterns/crud-bulk-actions.md

@@ -1,12 +0,0 @@
-# Padrão: CRUD — Ações em Lote
-
-As ações em lote foram unificadas em um dropdown "Ações em lote" no CrudActionBar.
-
-**Comportamento:**
-- O menu permanece visível se habilitado
-- Exibe um badge com a contagem de itens selecionados
-- As opções internas são desabilitadas se a seleção for zero
-
-**Regras:**
-- O componente `BulkActionBar` foi **removido** para evitar barras duplicadas e layout shifts
-- Na CrudTable, a coluna de ações de linha não deve ter label no cabeçalho (usar apenas ícone ⋮ ou tooltip) para evitar confusão com o menu de ações em lote da toolbar

package/docs/design-system/patterns/crud-config-props.md

@@ -1,17 +0,0 @@
-# Padrão: CRUD — Props Padronizadas de Configuração
-
-A interface CrudPageConfig foi estendida para padronizar a UX em todos os CRUDs (createCrudPage, CrudTable, CrudGrid).
-
-**Props disponíveis:**
-
-| Prop | Default | Descrição |
-|------|---------|-----------|
-| `showNewButton` | `true` | Exibe botão de criação |
-| `showSearch` | `true` | Exibe campo de busca |
-| `showBulkActions` | — | Alias para `enableBulkActions` |
-| `showActionBar` | `true` | Exibe a barra de ações (substitui `hideActionBar`) |
-| `newButtonLabel` | — | Customiza texto do botão de criação |
-| `searchPlaceholder` | — | Customiza placeholder da busca |
-| `showDeleteAction` | `true` | Exibe ação "Excluir" na linha e no dialog de confirmação. Use `false` quando a entidade não suporta exclusão de verdade (ex.: só "ignorar"/soft actions) |
-
-Esta padronização garante que todos os CRUDs ofereçam as mesmas capacidades de busca, criação e ações em lote de forma consistente.

package/docs/design-system/patterns/crud-defaults.md

@@ -1,17 +0,0 @@
-# Padrão: CRUD — Defaults Obrigatórios
-
-Todos os CRUDs (CrudTable, createCrudPage) incluem por padrão:
-
-| Feature | Default | Nota |
-|---------|---------|------|
-| Column resize | `true` ✓ | Já obrigatório |
-| Column manager | `true` ✓ | Botão ⋮ no header da coluna "Ações" |
-| Sort | `true` ✓ | Todas as colunas ordenáveis por padrão. Use `sortable: false` para desabilitar |
-| Busca | Header global | Para busca na action bar, usar `showSearch=true` |
-| Paginação | 25 itens/página | — |
-
-**NÃO vem por padrão:**
-- **Agrupamento** (`enableGrouping=false`) — precisa ser habilitado explicitamente
-- **Busca na action bar** (`showSearch=false`) — padrão é busca no header
-
-**Storage keys:** `createCrudPage` gera automaticamente `columnManagerStorageKey` e `resizeStorageKey` a partir do `entityName`.

package/docs/design-system/patterns/crud-toolbar.md

@@ -1,28 +0,0 @@
-# Padrão: CRUD Toolbar — Layout 3 Zonas
-
-O CrudActionBar implementa um layout rígido de 3 zonas:
-
-| Zona | Posição | Conteúdo |
-|------|---------|----------|
-| Esquerda | `justify-start` | Botão "Novo" (ação principal) + Dropdown ações em lote |
-| Centro | `flex-1 max-w-md` | Campo de busca (FilterBar/Input) |
-| Direita | `justify-end` | Filtros customizados + Toggle de visualização |
-
-```tsx
-// ✅ CORRETO
-<div className="flex items-center gap-4">
-  <Button>Novo Item</Button>
-  <div className="flex-1 max-w-md">
-    <Input placeholder="Buscar..." />
-  </div>
-  <div className="flex gap-2">
-    <Button variant="outline">Filtrar</Button>
-    <ActionButton items={actions} />
-  </div>
-</div>
-```
-
-**Regras:**
-- Botão de criação NUNCA deve ficar isolado no cabeçalho do Card
-- Este componente substitui implementações locais de barra de ferramentas
-- Garante visual consistente (bg-muted/50), comportamento e espaçamento em todos os CRUDs

package/docs/design-system/patterns/delete-confirmation.md

@@ -1,40 +0,0 @@
-# Padrão: Dialog de Confirmação de Exclusão
-
-Dialog de exclusão segue padrão visual específico (NÃO usar AlertDialog para deleções simples):
-
-```tsx
-<Dialog open={open} onOpenChange={setOpen}>
-  <DialogContent size="sm" className="bg-white">
-    <DialogHeader showSeparator>
-      <DialogTitle className="sr-only">Confirmação</DialogTitle>
-    </DialogHeader>
-    
-    <div className="flex flex-col items-center text-center space-y-3 py-4">
-      <div className="w-12 h-12 rounded-full bg-destructive/10 flex items-center justify-center">
-        <AlertTriangle className="h-6 w-6 text-destructive" />
-      </div>
-      <h3 className="text-lg font-semibold">Tem certeza?</h3>
-      <p className="text-sm text-muted-foreground">
-        Você está prestes a excluir este registro.<br />
-        Esta ação não pode ser desfeita.
-      </p>
-    </div>
-    
-    <DialogFooter className="justify-center gap-2 mt-6">
-      <Button variant="outline" onClick={() => setOpen(false)}>
-        Cancelar
-      </Button>
-      <Button variant="destructive" onClick={handleDelete}>
-        Sim, excluir
-      </Button>
-    </DialogFooter>
-  </DialogContent>
-</Dialog>
-```
-
-**Regras:**
-- Usar `size="sm"` (~420px quadrado)
-- Background branco (`bg-white`)
-- Ícone AlertTriangle com `bg-destructive/10`
-- Botões lado a lado, centralizados
-- Texto fixo em português

package/docs/design-system/patterns/dialog-body-scroll.md

@@ -1,26 +0,0 @@
-# Padrão: Scroll Interno em Dialogs
-
-Conteúdo de Dialog/Sheet com scroll interno **DEVE** usar o padrão responsivo:
-
-```tsx
-// ✅ CORRETO - padrão obrigatório
-<div className="flex-1 min-h-0 overflow-auto py-4 px-2 -mx-2">
-  {/* Conteúdo scrollável */}
-</div>
-
-// ❌ ERRADO - overflow escondido, sem scroll
-<div className="p-4">
-  {/* Conteúdo pode ser cortado */}
-</div>
-```
-
-**Breakdown das classes:**
-| Classe | Função |
-|--------|--------|
-| `flex-1` | Expande para preencher espaço disponível |
-| `min-h-0` | Permite shrink em flex container |
-| `overflow-auto` | Habilita scroll quando necessário |
-| `py-4` | Padding vertical padrão (16px) |
-| `px-2 -mx-2` | Previne corte de focus rings (8px de respiro) |
-
-**Aplica-se a:** Dialog, Sheet, Drawer, AlertDialog

package/docs/design-system/patterns/dialog-structure.md

@@ -1,32 +0,0 @@
-# Padrão: Dialog — Tamanhos e Estrutura
-
-Dialog possui 3 tamanhos opcionais (sem default) e estrutura obrigatória:
-
-| Size | Width | MaxHeight | Uso |
-|------|-------|-----------|-----|
-| (nenhum) | Auto (className controla) | Auto | Quando classes Tailwind definem o tamanho |
-| `sm` | 30vw (320-480px) | 320px | Confirmações rápidas |
-| `md` | 50vw (480-720px) | 70vh | Formulários padrão |
-| `lg` | 85vw (max 1440px) | 900px | Tabelas, conteúdo extenso |
-
-**Mobile (<640px):** Todos os tamanhos são sobrepostos para ocupar `calc(100vw-2rem)` x `calc(100dvh-2rem)` com padding reduzido (`p-4`).
-
-**Regra de prioridade:** Quando `size` é informado, inline styles são aplicados e vencem sobre className. Sem `size`, className controla livremente.
-
-**Estrutura obrigatória:**
-```tsx
-<DialogContent size="md">
-  <DialogHeader showSeparator>
-    <DialogTitle>Título</DialogTitle>
-  </DialogHeader>
-  <DialogBody>
-    {/* Conteúdo aqui */}
-  </DialogBody>
-  <DialogFooter>...</DialogFooter>
-</DialogContent>
-```
-
-**Regras:**
-- `showSeparator` no DialogHeader para linha divisória
-- DialogBody é obrigatório para scroll interno
-- `size` é opcional — sem ele, classes Tailwind no className controlam o tamanho

package/docs/design-system/patterns/dialog-variants.md

@@ -1,41 +0,0 @@
-# Padrão: Dialog — Variantes Semânticas
-
-O `DialogContent` possui uma prop `variant` que controla o comportamento de fechamento:
-
-## Variantes
-
-| Variante | Clique externo | ESC | Botão X | Uso |
-|----------|---------------|-----|---------|-----|
-| `informative` (padrão) | Fecha | Fecha | Fecha | Avisos, leitura |
-| `form` | Bloqueado | Fecha* | Fecha* | Formulários, edições |
-| `destructive` | Bloqueado | Bloqueado | Oculto | Exclusões, ações irreversíveis |
-
-\* Com `isDirty={true}`, exibe `window.confirm` antes de fechar.
-
-## Props
-
-```typescript
-interface DialogContentProps {
-  variant?: 'informative' | 'form' | 'destructive'; // default: 'informative'
-  isDirty?: boolean; // para variant='form', confirmação antes de fechar
-}
-```
-
-## Padrão de uso
-
-```tsx
-// Formulários
-<DialogContent variant="form" isDirty={form.formState.isDirty}>
-
-// Exclusões
-<DialogContent variant="destructive" size="sm">
-
-// Informativos (comportamento padrão, pode omitir variant)
-<DialogContent variant="informative">
-```
-
-## Regras
-- Default é `'informative'` para compatibilidade com dialogs existentes
-- `destructive` oculta o botão X — fechamento apenas por botões no DialogFooter
-- `form` com `isDirty` usa `window.confirm` nativo para confirmação
-- Tipos exportados: `DialogVariant`, `DialogSize`, `DialogContentProps`

package/docs/design-system/patterns/feature-flags.md

@@ -1,113 +0,0 @@
-# Padrão: Feature Flags (Variáveis de Ambiente)
-
-## Variáveis disponíveis
-
-| Variável | Descrição | Padrão |
-|----------|-----------|--------|
-| `VITE_APP_ENV` | Define o ambiente alvo da API/OAuth Qualiex. Valores aceitos: `"PROD"` ou `"DEV"`. Ausente ou qualquer outro valor = `PROD` (failsafe). Ver [seção abaixo](#vite_app_env). | `"PROD"` |
-| `VITE_SHOW_USER_PREFERENCES` | Exibe "Preferências" no menu do usuário (idioma, timezone, formato de data) | Não exibe |
-| `VITE_I18N_DEBUG_MODE` | Modo debug de i18n (mostra chaves ao invés de traduções) | `"false"` |
-| `VITE_IS_QUALIEX` | Usa logos Qualiex ao invés de Forlogic | `"false"` |
-| `VITE_SHOW_EDIT_PROFILE` | Exibe "Editar Perfil" no menu do usuário (foto e idioma) | Não exibe |
-| `VITE_WIKI_URL` | Exibe botão "Wiki" no header da aplicação. O valor é a URL que será aberta ao clicar | Não exibe |
-| `VITE_SHOW_ADMIN_REPORTS` | Exibe relatórios administrativos | `"false"` |
-| `VITE_SUPABASE_PK_OVERRIDE` | **Obrigatória (modo Supabase).** Publishable key correta do Supabase. Ver [seção abaixo](#vite_supabase_pk_override). | — |
-
-## Uso
-
-```env
-VITE_SHOW_USER_PREFERENCES=true
-VITE_I18N_DEBUG_MODE=false
-VITE_IS_QUALIEX=true
-VITE_WIKI_URL=https://wiki.example.com
-VITE_SHOW_ADMIN_REPORTS=false
-VITE_SUPABASE_PK_OVERRIDE="sb_publishable_w-TKU0hE4bjM_uOgt3fK1g_ewrXKJ8J"
-```
-
-Variáveis Vite precisam do prefixo `VITE_` para serem expostas ao cliente.
-
----
-
-## Resolução unificada das envs Supabase (sem duplicação)
-
-A partir do `vite.config.ts`, o helper `resolveSupabaseEnv(mode)` (de `forlogic-core/vite`) lê **ambos os formatos** de variáveis e injeta um valor único via `define`:
-
-- Aceita `VITE_SUPABASE_*` (legado) **ou** `SUPABASE_*` (formato novo Lovable Cloud).
-- Prioridade: `VITE_SUPABASE_*` → `SUPABASE_*` → fallback derivado (`projectId` extraído da URL).
-- Injeta `import.meta.env.VITE_SUPABASE_URL` / `VITE_SUPABASE_PUBLISHABLE_KEY` / `VITE_SUPABASE_PROJECT_ID` / `VITE_SUPABASE_PK_OVERRIDE` no bundle.
-- O código do app/lib continua usando os nomes `VITE_*` — nada muda no consumo.
-
-**Resultado:** o `.env` precisa apenas de **uma** versão de cada variável. Recomendado o formato sem prefixo (Lovable Cloud auto-injeta):
-
-```env
-SUPABASE_URL="https://ccjfvpnndclajkleyqkc.supabase.co"
-SUPABASE_PUBLISHABLE_KEY="sb_publishable_w-TKU0hE4bjM_uOgt3fK1g_ewrXKJ8J"
-VITE_SUPABASE_PK_OVERRIDE="sb_publishable_w-TKU0hE4bjM_uOgt3fK1g_ewrXKJ8J"
-```
-
-Ver `mem://patterns/dynamic-supabase-config`.
-
----
-
-## `VITE_APP_ENV`
-
-Define **explicitamente** o ambiente alvo da API Qualiex e do OAuth, sem depender de pistas indiretas (project ID do Supabase, hostname, etc).
-
-| Valor                          | Resultado                                                        |
-|--------------------------------|------------------------------------------------------------------|
-| `"PROD"`                       | API `common-v4-api.qualiex.com`, OAuth `login.qualiex.com`       |
-| `"DEV"`                        | API `common-v4-api-dev.qualiex.com`, OAuth `login-dev.qualiex.com` |
-| ausente / qualquer outro valor | **PROD (failsafe)** — esquecer a variável nunca aponta para dev |
-
-Apps em produção podem omitir a variável; apps que rodam contra dev **precisam** declarar `VITE_APP_ENV="DEV"` no `.env`. Não existe fallback derivado do Supabase.
-
-Helpers disponíveis em `forlogic-core`:
-
-- `getAppEnv(): 'PROD' | 'DEV'`
-- `isDevEnv(): boolean`
-- `getEnvironmentConfig(): EnvironmentConfig`
-
----
-
-## `VITE_SUPABASE_PK_OVERRIDE`
-
-### Problema
-
-O Supabase desativou as legacy API keys (formato JWT `eyJhbGci...`). A integração Supabase do Lovable **sobrescreve automaticamente** `SUPABASE_PUBLISHABLE_KEY` (e a versão `VITE_*` quando presente) no `.env` com a legacy anon key a cada prompt, causando `401 Unauthorized` em todas as requests.
-
-### Solução
-
-A lib `forlogic-core` implementa um mecanismo de override:
-
-1. Se `VITE_SUPABASE_PK_OVERRIDE` existir no `.env` → a lib usa essa key (ignora a publishable key resolvida)
-2. Se não existir → usa a key resolvida por `resolveSupabaseEnv()`
-3. Se a key ativa for uma JWT legada → exibe banner vermelho no preview (DEV, apenas `backend="supabase"`) + erro no console
-
-O Lovable **nunca toca** em `VITE_SUPABASE_PK_OVERRIDE` porque só auto-popula as envs Supabase padrão.
-
-### Como funciona internamente
-
-```text
-VITE_SUPABASE_PK_OVERRIDE existe?
-  ├─ SIM → usar ela
-  │        console.info: "✅ Usando VITE_SUPABASE_PK_OVERRIDE..."
-  └─ NÃO → usar a key resolvida por resolveSupabaseEnv()
-       ├─ Formato sb_publishable_* → OK
-       └─ Formato eyJ* (JWT legada) → ⛔ Erro
-            ├─ console.error com diagnóstico completo
-            └─ Banner vermelho fixo no topo (apenas DEV, modo supabase)
-```
-
-### Arquivos relevantes na lib
-
-| Arquivo | Responsabilidade |
-|---------|-----------------|
-| `lib/vite/resolve-supabase-env.ts` | `resolveSupabaseEnv()` — consolida envs Supabase no `define` do Vite |
-| `lib/supabase/legacyKeyGuard.ts` | `resolvePublishableKey()`, `isLegacyAnonKey()`, `warnIfLegacyKey()` |
-| `lib/supabase/SupabaseSingleton.ts` | Usa `resolvePublishableKey()` para a key do client |
-| `lib/supabase/publicClient.ts` | Idem para o client público |
-| `lib/providers/CoreProviders.tsx` | Renderiza `LegacyKeyBanner` em DEV (apenas `backend="supabase"`) |
-
-### ⚠️ Nunca remova esta variável do `.env`
-
-Mesmo que o Lovable corrija a integração no futuro, a presença do override não causa nenhum efeito colateral negativo — é um fallback seguro.

package/docs/design-system/patterns/header-metadata.md

@@ -1,57 +0,0 @@
-# Padrão: Título, Subtítulo e Breadcrumbs via Header (usePageMetadata)
-
-## Regra
-
-**O padrão da aplicação é exibir título, subtítulo e breadcrumbs no header** usando `usePageMetadata()`.
-
-- **NÃO** usar `BodyContent` ou `ContentContainer` com título/subtítulo internos por padrão.
-- Breadcrumbs, títulos e subtítulos internos ao conteúdo são **exceções** e devem ser usados **somente quando explicitamente solicitados**.
-
-## Uso Padrão
-
-```tsx
-import { usePageMetadata } from 'forlogic-core';
-
-export function MinhaPage() {
-  usePageMetadata({ title: 'Título', subtitle: 'Subtítulo descritivo' });
-
-  return (
-    <div className="flex flex-col h-full p-4 gap-4">
-      {/* conteúdo direto, sem BodyContent/ContentContainer */}
-    </div>
-  );
-}
-```
-
-## Com Breadcrumbs
-
-```tsx
-usePageMetadata({
-  title: 'Editar Usuário',
-  subtitle: 'Atualize os dados cadastrais',
-  breadcrumbs: [
-    { label: 'Usuários', href: '/users' },
-    { label: 'João Silva' }
-  ]
-});
-```
-
-## Subtitle com ReactNode
-
-```tsx
-usePageMetadata({
-  title: 'Detalhes',
-  subtitle: <span>Veja a <Link to="/docs">documentação</Link></span>
-});
-```
-
-## ❌ Evitar (exceto quando pedido)
-
-```tsx
-// NÃO fazer por padrão:
-<BodyContent breadcrumbs={[{ label: 'Página' }]}>
-  <ContentContainer title="Título" subtitle="Subtítulo">
-    ...
-  </ContentContainer>
-</BodyContent>
-```