forlogic-core 2.3.0 → 2.3.1

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

@@ -4,13 +4,14 @@
 
 | 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.** Publishable key correta do Supabase. Ver [seção abaixo](#vite_supabase_pk_override). | — |
+| `VITE_SUPABASE_PK_OVERRIDE` | **Obrigatória (modo Supabase).** Publishable key correta do Supabase. Ver [seção abaixo](#vite_supabase_pk_override). | — |
 
 ## Uso
 
@@ -27,54 +28,85 @@ 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** `VITE_SUPABASE_PUBLISHABLE_KEY` no `.env` com a legacy anon key a cada prompt, causando `401 Unauthorized` em todas as requests.
+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 `VITE_SUPABASE_PUBLISHABLE_KEY`)
-2. Se não existir → usa `VITE_SUPABASE_PUBLISHABLE_KEY` normalmente
-3. Se a key ativa for uma JWT legada → exibe banner vermelho no preview (DEV) + erro no console
+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 estas 3 variáveis:
-- `VITE_SUPABASE_URL`
-- `VITE_SUPABASE_PUBLISHABLE_KEY`
-- `VITE_SUPABASE_PROJECT_ID`
-
-### Configuração obrigatória
-
-**Todo projeto consumidor** que aponta para o Supabase `ccjfvpnndclajkleyqkc` deve adicionar no `.env`:
-
-```env
-VITE_SUPABASE_PK_OVERRIDE="sb_publishable_w-TKU0hE4bjM_uOgt3fK1g_ewrXKJ8J"
-```
+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 (ignora VITE_SUPABASE_PUBLISHABLE_KEY)
+  ├─ SIM → usar ela
   │        console.info: "✅ Usando VITE_SUPABASE_PK_OVERRIDE..."
-  └─ NÃO → usar VITE_SUPABASE_PUBLISHABLE_KEY
+  └─ 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)
+            └─ 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 |
+| `lib/providers/CoreProviders.tsx` | Renderiza `LegacyKeyBanner` em DEV (apenas `backend="supabase"`) |
 
 ### ⚠️ Nunca remova esta variável do `.env`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forlogic-core",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",