forlogic-core 2.1.4 → 2.2.0

package/.note/memory/features/import/attachment-idempotency-registry.md

@@ -1,8 +1,8 @@
-# Memory: features/import/attachment-idempotency-registry
-Updated: now
-
-## REMOVIDO
-
-O controle de idempotência via tabela `common.imports_file_registry` foi removido para simplificar o fluxo de importação de anexos. Agora todo arquivo válido (>0 bytes) é enviado diretamente ao Azure Blob Storage sem verificar se já existe no registry. As funções `lookupExistingFiles`, `registerUploadedFiles` e o campo `newFiles` do `UploadResult` foram removidos de `attachmentUploadService.ts`.
-
-A tabela `common.imports_file_registry` no Supabase pode ser removida manualmente se desejado — a aplicação não a consulta mais.
+# Memory: features/import/attachment-idempotency-registry
+Updated: now
+
+## REMOVIDO
+
+O controle de idempotência via tabela `common.imports_file_registry` foi removido para simplificar o fluxo de importação de anexos. Agora todo arquivo válido (>0 bytes) é enviado diretamente ao Azure Blob Storage sem verificar se já existe no registry. As funções `lookupExistingFiles`, `registerUploadedFiles` e o campo `newFiles` do `UploadResult` foram removidos de `attachmentUploadService.ts`.
+
+A tabela `common.imports_file_registry` no Supabase pode ser removida manualmente se desejado — a aplicação não a consulta mais.

package/.note/memory/features/import/attachment-strategy.md

@@ -1,30 +1,30 @@
-# Memory: features/import/attachment-strategy
-Updated: now
-
-O sistema de anexos usa upload direto ao Azure Blob Storage (sem staging). O .zip contém pastas nomeadas pelo código do registro (ex: `OC-001/foto.pdf`). Cada arquivo recebe um `id_file_revision` de 8 caracteres alfanuméricos (`crypto.randomUUID().slice(0,8)`) gerado no front-end. O arquivo é enviado ao container `un{id_company}` com nome `{id_file_revision}.{ext}`. Esse mesmo ID é incluído no CSV como coluna `id_file_revision` para que a API grave no banco com a mesma referência.
-
-## Idempotência via `common.imports_file_registry`
-
-Tabela Supabase com PK `CHAR(8)` (o próprio `id_file_revision`) e constraint `UNIQUE(alias, code, file_name)`:
-- Se `(alias, code, file_name)` já existe com **mesmo tamanho** → reutiliza `id_file_revision` e `blob_url`, **não faz upload**
-- Se existe com **tamanho diferente** → erro de conflito
-- Se não existe → gera novo ID, faz upload, registra no registry **somente após sucesso da API**
-- Arquivos com 0 bytes são rejeitados imediatamente
-
-## Fluxo de consistência
-
-1. Upload para Azure (novos arquivos)
-2. Envio do CSV para API staging
-3. **Se API sucesso** → `registerUploadedFiles()` grava no registry
-4. **Se API falhar** → registry NÃO é gravado, próxima tentativa refaz upload
-
-## Templates de anexo (attachment-only)
-
-Quando `import_target === 'attachments'` ou todos os campos ativos são `file`/`file_metadata`, o sistema detecta automaticamente. Nesse modo:
-- O .zip **não precisa conter xlsx** — apenas pastas com arquivos
-- O código é extraído do **diretório pai imediato** do arquivo
-- As linhas do CSV são geradas automaticamente a partir dos metadados
-- Função `executeAttachmentOnlyImport` orquestra o fluxo completo
-- `buildRowsFromAttachments` gera as linhas
-- `extractZipAttachmentsOnly` extrai sem exigir xlsx
-- `isAttachmentOnlyTemplate` detecta o tipo
+# Memory: features/import/attachment-strategy
+Updated: now
+
+O sistema de anexos usa upload direto ao Azure Blob Storage (sem staging). O .zip contém pastas nomeadas pelo código do registro (ex: `OC-001/foto.pdf`). Cada arquivo recebe um `id_file_revision` de 8 caracteres alfanuméricos (`crypto.randomUUID().slice(0,8)`) gerado no front-end. O arquivo é enviado ao container `un{id_company}` com nome `{id_file_revision}.{ext}`. Esse mesmo ID é incluído no CSV como coluna `id_file_revision` para que a API grave no banco com a mesma referência.
+
+## Idempotência via `common.imports_file_registry`
+
+Tabela Supabase com PK `CHAR(8)` (o próprio `id_file_revision`) e constraint `UNIQUE(alias, code, file_name)`:
+- Se `(alias, code, file_name)` já existe com **mesmo tamanho** → reutiliza `id_file_revision` e `blob_url`, **não faz upload**
+- Se existe com **tamanho diferente** → erro de conflito
+- Se não existe → gera novo ID, faz upload, registra no registry **somente após sucesso da API**
+- Arquivos com 0 bytes são rejeitados imediatamente
+
+## Fluxo de consistência
+
+1. Upload para Azure (novos arquivos)
+2. Envio do CSV para API staging
+3. **Se API sucesso** → `registerUploadedFiles()` grava no registry
+4. **Se API falhar** → registry NÃO é gravado, próxima tentativa refaz upload
+
+## Templates de anexo (attachment-only)
+
+Quando `import_target === 'attachments'` ou todos os campos ativos são `file`/`file_metadata`, o sistema detecta automaticamente. Nesse modo:
+- O .zip **não precisa conter xlsx** — apenas pastas com arquivos
+- O código é extraído do **diretório pai imediato** do arquivo
+- As linhas do CSV são geradas automaticamente a partir dos metadados
+- Função `executeAttachmentOnlyImport` orquestra o fluxo completo
+- `buildRowsFromAttachments` gera as linhas
+- `extractZipAttachmentsOnly` extrai sem exigir xlsx
+- `isAttachmentOnlyTemplate` detecta o tipo

package/.note/memory/patterns/admin-i18n-policy.md

@@ -1,20 +1,20 @@
-# Política de Idioma — Admin, Design System e Lib
-
-## Decisão
-
-| Camada | Idioma | i18n (useTranslation) |
-|--------|--------|-----------------------|
-| **Projeto Admin (`src/`)** | Português (Brasil) — hardcoded | ❌ Não usa |
-| **Design System (`src/design-system/`)** | Português (Brasil) — hardcoded | ❌ Não usa |
-| **Lib (`lib/`)** | Multi-idioma (pt-BR, en-US, es-ES) | ✅ Usa `t()` + JSONs |
-
-## Regras
-
-1. **Nenhum arquivo em `src/`** deve importar `useTranslation` ou usar `t()` — todos os textos são strings fixas em português.
-2. **A documentação interativa do Design System** (páginas `*Doc.tsx`, sidebar, home) é escrita diretamente em português, sem chaves de tradução.
-3. **A lib (`lib/`)** mantém o sistema completo de i18n com namespaces, JSONs por idioma e integração com Tolgee, pois é consumida por projetos que precisam de múltiplos idiomas.
-4. **Arquivos de tradução da lib** (`lib/i18n/locales/`) contêm apenas chaves usadas pelos componentes internos da lib.
-
-## Contexto
-
-O Admin é um painel interno da Forlogic usado exclusivamente em português. Manter i18n no Admin adiciona complexidade sem benefício. A lib, por outro lado, é distribuída para projetos consumidores que operam em múltiplos idiomas.
+# Política de Idioma — Admin, Design System e Lib
+
+## Decisão
+
+| Camada | Idioma | i18n (useTranslation) |
+|--------|--------|-----------------------|
+| **Projeto Admin (`src/`)** | Português (Brasil) — hardcoded | ❌ Não usa |
+| **Design System (`src/design-system/`)** | Português (Brasil) — hardcoded | ❌ Não usa |
+| **Lib (`lib/`)** | Multi-idioma (pt-BR, en-US, es-ES) | ✅ Usa `t()` + JSONs |
+
+## Regras
+
+1. **Nenhum arquivo em `src/`** deve importar `useTranslation` ou usar `t()` — todos os textos são strings fixas em português.
+2. **A documentação interativa do Design System** (páginas `*Doc.tsx`, sidebar, home) é escrita diretamente em português, sem chaves de tradução.
+3. **A lib (`lib/`)** mantém o sistema completo de i18n com namespaces, JSONs por idioma e integração com Tolgee, pois é consumida por projetos que precisam de múltiplos idiomas.
+4. **Arquivos de tradução da lib** (`lib/i18n/locales/`) contêm apenas chaves usadas pelos componentes internos da lib.
+
+## Contexto
+
+O Admin é um painel interno da Forlogic usado exclusivamente em português. Manter i18n no Admin adiciona complexidade sem benefício. A lib, por outro lado, é distribuída para projetos consumidores que operam em múltiplos idiomas.

package/.note/memory/patterns/alias-url-resolution.md

@@ -1,69 +1,69 @@
-# Alias via URL — Resolução de Unidade por Rota
-
-## Padrão
-
-O alias da unidade ativa deve **sempre** estar presente na URL como primeiro segmento de rota (`/:alias/...`). A **URL é a fonte única de verdade** para o alias ativo.
-
-## Arquitetura (URL como Source of Truth)
-
-```
-Header/Seletor → navigate(/{novoAlias}/...) → URL muda → AliasRouteGuard → switchUnit()
-```
-
-- **Header/UI**: Apenas navega (muda a URL). Nunca chama `switchUnit` diretamente.
-- **AliasRouteGuard**: Detecta que `urlAlias !== activeAlias` e chama `switchUnit()` para sincronizar a sessão.
-- **Resultado**: Um único writer (guard) controla a sessão, eliminando race conditions.
-
-## Componentes
-
-### `useAliasFromUrl(options?)`
-Hook que extrai o alias do param de rota e valida contra `companies` do `useAuth()`.
-
-Retorna: `{ urlAlias, isAliasMismatch, isValidAlias, isMissing, matchedCompany }`
-
-### `AliasRouteGuard`
-Wrapper de rota com **auto-detect de modo**:
-
-- **Modo URL** (`:alias` presente na rota): comportamento padrão com 1 effect de decisão
-- **Modo Legado** (sem `:alias` na rota): passthrough transparente, sem redirects
-
-| Cenário (Modo URL) | Ação |
-|---------|------|
-| Alias ausente na URL | Redireciona para `/{aliasAtivo}/{path}` |
-| Alias inválido | Redireciona para `/{aliasAtivo}/{path}` |
-| Alias válido e diferente do ativo | Chama `switchUnit()` |
-| Alias correto | Renderiza children |
-
-Proteção de concorrência: `switchingRef` evita chamadas duplicadas no mesmo ciclo.
-
-### `AppHeader` (mudança de unidade)
-
-O header usa `navigate()` para trocar o segmento de alias na URL:
-
-```tsx
-const handleUnitChangeNavigate = (company) => {
-  const segments = pathname.split('/');
-  const aliasIndex = segments.indexOf(alias);
-  segments[aliasIndex] = company.alias;
-  navigate(segments.join('/') + search + hash);
-};
-
-<UserInfo onUnitChange={handleUnitChangeNavigate} />
-```
-
-## Uso nos Consumidores
-
-```tsx
-<Route element={<ProtectedRoute><AliasRouteGuard><Outlet /></AliasRouteGuard></ProtectedRoute>}>
-  <Route path="/:alias/documents" element={<DocumentsPage />} />
-  <Route path="/:alias/documents/:id" element={<DocumentDetailPage />} />
-</Route>
-```
-
-## Regras
-- Guard só age após `isLoading=false && isAuthenticated=true`
-- Usa `replace: true` para evitar poluir o histórico
-- Se `switchUnit` falha, mantém alias atual (sem loop)
-- `switchUnit` já faz `queryClient.clear()` — cache é limpo automaticamente
-- Navegação inter-módulos já usa `{alias}` nas URLs (`modulesData.ts`)
-- **Header/seletor NUNCA chama switchUnit diretamente** — apenas navega
+# Alias via URL — Resolução de Unidade por Rota
+
+## Padrão
+
+O alias da unidade ativa deve **sempre** estar presente na URL como primeiro segmento de rota (`/:alias/...`). A **URL é a fonte única de verdade** para o alias ativo.
+
+## Arquitetura (URL como Source of Truth)
+
+```
+Header/Seletor → navigate(/{novoAlias}/...) → URL muda → AliasRouteGuard → switchUnit()
+```
+
+- **Header/UI**: Apenas navega (muda a URL). Nunca chama `switchUnit` diretamente.
+- **AliasRouteGuard**: Detecta que `urlAlias !== activeAlias` e chama `switchUnit()` para sincronizar a sessão.
+- **Resultado**: Um único writer (guard) controla a sessão, eliminando race conditions.
+
+## Componentes
+
+### `useAliasFromUrl(options?)`
+Hook que extrai o alias do param de rota e valida contra `companies` do `useAuth()`.
+
+Retorna: `{ urlAlias, isAliasMismatch, isValidAlias, isMissing, matchedCompany }`
+
+### `AliasRouteGuard`
+Wrapper de rota com **auto-detect de modo**:
+
+- **Modo URL** (`:alias` presente na rota): comportamento padrão com 1 effect de decisão
+- **Modo Legado** (sem `:alias` na rota): passthrough transparente, sem redirects
+
+| Cenário (Modo URL) | Ação |
+|---------|------|
+| Alias ausente na URL | Redireciona para `/{aliasAtivo}/{path}` |
+| Alias inválido | Redireciona para `/{aliasAtivo}/{path}` |
+| Alias válido e diferente do ativo | Chama `switchUnit()` |
+| Alias correto | Renderiza children |
+
+Proteção de concorrência: `switchingRef` evita chamadas duplicadas no mesmo ciclo.
+
+### `AppHeader` (mudança de unidade)
+
+O header usa `navigate()` para trocar o segmento de alias na URL:
+
+```tsx
+const handleUnitChangeNavigate = (company) => {
+  const segments = pathname.split('/');
+  const aliasIndex = segments.indexOf(alias);
+  segments[aliasIndex] = company.alias;
+  navigate(segments.join('/') + search + hash);
+};
+
+<UserInfo onUnitChange={handleUnitChangeNavigate} />
+```
+
+## Uso nos Consumidores
+
+```tsx
+<Route element={<ProtectedRoute><AliasRouteGuard><Outlet /></AliasRouteGuard></ProtectedRoute>}>
+  <Route path="/:alias/documents" element={<DocumentsPage />} />
+  <Route path="/:alias/documents/:id" element={<DocumentDetailPage />} />
+</Route>
+```
+
+## Regras
+- Guard só age após `isLoading=false && isAuthenticated=true`
+- Usa `replace: true` para evitar poluir o histórico
+- Se `switchUnit` falha, mantém alias atual (sem loop)
+- `switchUnit` já faz `queryClient.clear()` — cache é limpo automaticamente
+- Navegação inter-módulos já usa `{alias}` nas URLs (`modulesData.ts`)
+- **Header/seletor NUNCA chama switchUnit diretamente** — apenas navega

package/.note/memory/patterns/doc-sync-rule.md

@@ -1,35 +1,35 @@
-# Regra: Sincronização Automática de Documentação
-
-## Gatilho
-
-Sempre que modificar qualquer arquivo em `lib/`, verificar se existe documentação correspondente em `src/design-system/docs/`.
-
-**Esta regra é obrigatória e deve ser aplicada em toda alteração de componente, sem exceção.**
-
-## Ações obrigatórias
-
-### 1. Componente/hook existente com doc existente
-- Atualizar props, exemplos, hierarquias e descrições no `*Doc.tsx` correspondente para refletir a mudança
-- Atualizar previews interativos para que reflitam o comportamento atual do componente
-
-### 2. Componente/hook novo sem doc
-- Criar `*Doc.tsx` usando `ComponentDocTemplate` (com prop `usage` obrigatória)
-- Registrar no `src/design-system/config/docRegistry.ts` (lazy import)
-- Registrar no `src/design-system/config/sections.ts` (sidebar + breadcrumb)
-
-### 3. Mudanças arquiteturais
-- Atualizar `docs/KNOWLEDGE.md` se afetar regras, mapa de módulos ou convenções
-- Atualizar `.note/memory/` se afetar padrões documentados
-
-## Mapeamento de referência
-
-```
-lib/components/ui/<comp>.tsx      → src/design-system/docs/components/<Comp>Doc.tsx
-lib/crud/components/<comp>.tsx    → src/design-system/docs/components/crud/<Comp>Doc.tsx
-lib/contexts/<Context>.tsx        → src/design-system/docs/ContextsDoc.tsx
-lib/hooks/<hook>.ts               → src/design-system/docs/HooksDoc.tsx
-lib/services/<Service>.ts         → src/design-system/docs/ServicesDoc.tsx
-lib/components/layout/<comp>.tsx  → src/design-system/docs/components/layout/<Comp>Doc.tsx
-```
-
-Consultar `.note/memory/patterns/components-registry.md` para componentes agrupados sob uma única doc.
+# Regra: Sincronização Automática de Documentação
+
+## Gatilho
+
+Sempre que modificar qualquer arquivo em `lib/`, verificar se existe documentação correspondente em `src/design-system/docs/`.
+
+**Esta regra é obrigatória e deve ser aplicada em toda alteração de componente, sem exceção.**
+
+## Ações obrigatórias
+
+### 1. Componente/hook existente com doc existente
+- Atualizar props, exemplos, hierarquias e descrições no `*Doc.tsx` correspondente para refletir a mudança
+- Atualizar previews interativos para que reflitam o comportamento atual do componente
+
+### 2. Componente/hook novo sem doc
+- Criar `*Doc.tsx` usando `ComponentDocTemplate` (com prop `usage` obrigatória)
+- Registrar no `src/design-system/config/docRegistry.ts` (lazy import)
+- Registrar no `src/design-system/config/sections.ts` (sidebar + breadcrumb)
+
+### 3. Mudanças arquiteturais
+- Atualizar `docs/KNOWLEDGE.md` se afetar regras, mapa de módulos ou convenções
+- Atualizar `.note/memory/` se afetar padrões documentados
+
+## Mapeamento de referência
+
+```
+lib/components/ui/<comp>.tsx      → src/design-system/docs/components/<Comp>Doc.tsx
+lib/crud/components/<comp>.tsx    → src/design-system/docs/components/crud/<Comp>Doc.tsx
+lib/contexts/<Context>.tsx        → src/design-system/docs/ContextsDoc.tsx
+lib/hooks/<hook>.ts               → src/design-system/docs/HooksDoc.tsx
+lib/services/<Service>.ts         → src/design-system/docs/ServicesDoc.tsx
+lib/components/layout/<comp>.tsx  → src/design-system/docs/components/layout/<Comp>Doc.tsx
+```
+
+Consultar `.note/memory/patterns/components-registry.md` para componentes agrupados sob uma única doc.

package/.note/memory/patterns/documentation-standard.md

@@ -1,17 +1,17 @@
-# Design System Documentation Standard
-
-## Fonte de verdade
-
-Os arquivos `*Doc.tsx` em `src/design-system/docs/` são a fonte de verdade para documentação de componentes. Eles alimentam a rota `/ds` no app.
-
-## Regras para *Doc.tsx
-
-- Devem usar `ComponentDocTemplate` com a prop `usage` obrigatória (snippet de código)
-- Seções críticas como ModuleAccess e Audit Log devem incluir padrões SQL e configurações
-- Exemplos visuais interativos são obrigatórios para componentes complexos
-
-## Acesso à documentação
-
-- **Rota `/ds`**: Design system interativo no app
-- **Cross-project**: IA lê `*Doc.tsx` diretamente do código-fonte do projeto **Admin** (forlogic-core)
-- **Não há mais geração automática** de `DESIGN_SYSTEM.md` — foi removido em favor de leitura direta
+# Design System Documentation Standard
+
+## Fonte de verdade
+
+Os arquivos `*Doc.tsx` em `src/design-system/docs/` são a fonte de verdade para documentação de componentes. Eles alimentam a rota `/ds` no app.
+
+## Regras para *Doc.tsx
+
+- Devem usar `ComponentDocTemplate` com a prop `usage` obrigatória (snippet de código)
+- Seções críticas como ModuleAccess e Audit Log devem incluir padrões SQL e configurações
+- Exemplos visuais interativos são obrigatórios para componentes complexos
+
+## Acesso à documentação
+
+- **Rota `/ds`**: Design system interativo no app
+- **Cross-project**: IA lê `*Doc.tsx` diretamente do código-fonte do projeto **Admin** (forlogic-core)
+- **Não há mais geração automática** de `DESIGN_SYSTEM.md` — foi removido em favor de leitura direta

package/.note/memory/patterns/dynamic-supabase-config.md

@@ -1,4 +1,4 @@
-# Memory: patterns/dynamic-supabase-config
-Updated: 2026-03-24
-
-As credenciais do Supabase vêm exclusivamente do `.env` (auto-populado pelo Lovable ao trocar banco). O Vite injeta automaticamente variáveis `VITE_*` em `import.meta.env` — não há bloco `define` manual nem extração de `client.ts`. O `vite.config.ts` usa `loadEnv()` apenas para ler o project ID no contexto Node (CSP headers). O `SupabaseSingleton` lê `import.meta.env.VITE_SUPABASE_URL` e `VITE_SUPABASE_PUBLISHABLE_KEY` em runtime no browser.
+# Memory: patterns/dynamic-supabase-config
+Updated: 2026-03-24
+
+As credenciais do Supabase vêm exclusivamente do `.env` (auto-populado pelo Lovable ao trocar banco). O Vite injeta automaticamente variáveis `VITE_*` em `import.meta.env` — não há bloco `define` manual nem extração de `client.ts`. O `vite.config.ts` usa `loadEnv()` apenas para ler o project ID no contexto Node (CSP headers). O `SupabaseSingleton` lê `import.meta.env.VITE_SUPABASE_URL` e `VITE_SUPABASE_PUBLISHABLE_KEY` em runtime no browser.

package/.note/memory/patterns/environment-detection-logic.md

@@ -1,35 +1,35 @@
-# Memory: patterns/environment-detection-logic
-Updated: 2026-03-24
-
-O sistema separa duas preocupações independentes de ambiente:
-
-## 1. Método de autenticação (`shouldUseDevTokens()` / `isLovablePreview()`)
-Detecta se o app roda em contexto de desenvolvimento (preview Lovable via iframe, `*.lovable.dev`, localhost ou `import.meta.env.DEV`). Quando true, usa a edge function `dev-tokens` do Supabase conectado para autenticar. Quando false (app publicado), usa OAuth padrão do Qualiex.
-
-## 2. Qual API usar (`getEnvironmentConfig()` / `isDevSupabaseProject()`)
-Compara o project ID do Supabase conectado com `PROD_PROJECT_ID` (`ccjfvpnndclajkleyqkc`). Se igual → config PROD (API prod, OAuth prod). Se diferente → config DEV (API dev, OAuth dev).
-
-## Fonte de verdade do Project ID
-O project ID vem do `.env` (auto-populado pelo Lovable ao trocar banco), que o Vite injeta automaticamente em `import.meta.env.VITE_SUPABASE_PROJECT_ID`. **Não** é extraído de `src/integrations/supabase/client.ts`. O `vite.config.ts` usa `loadEnv()` apenas no contexto Node para configurar CSP headers.
-
-## Tabela de regras
-
-| Cenário                      | API  | Auth       |
-|------------------------------|------|------------|
-| Preview + Prod Supabase      | Prod | dev-tokens |
-| Preview + Dev Supabase       | Dev  | dev-tokens |
-| Publicado + Prod Supabase    | Prod | OAuth      |
-| Publicado + Dev Supabase     | Dev  | OAuth      |
-
-## Guard de troca de projeto (`TokenManager.checkProjectMismatch()`)
-Ao inicializar (`AuthService.initialize()`), o sistema compara `import.meta.env.VITE_SUPABASE_PROJECT_ID` com o valor armazenado em `localStorage('supabase_project_id')`. Se diferente, limpa todos os tokens stale automaticamente antes de qualquer chamada a `validate-token`, evitando 401 desnecessários. Após a limpeza, armazena o novo project ID. Isso garante transição limpa ao trocar de banco Supabase sem erros ou blank screen.
-
-## Funções (lib/config/index.ts)
-- `isLovablePreview()` — detecta contexto de preview/localhost
-- `shouldUseDevTokens()` — wrapper semântico sobre `isLovablePreview()`
-- `isDevEnvironment` — alias deprecated, mantido para compatibilidade
-- `getEnvironmentConfig()` — retorna config PROD ou DEV baseado no project ID
-- `isDevSupabaseProject()` — true se project ID ≠ PROD_PROJECT_ID
-
-## Funções (lib/auth/services/TokenManager.ts)
-- `checkProjectMismatch()` — detecta troca de projeto Supabase e limpa tokens stale
+# Memory: patterns/environment-detection-logic
+Updated: 2026-03-24
+
+O sistema separa duas preocupações independentes de ambiente:
+
+## 1. Método de autenticação (`shouldUseDevTokens()` / `isLovablePreview()`)
+Detecta se o app roda em contexto de desenvolvimento (preview Lovable via iframe, `*.lovable.dev`, localhost ou `import.meta.env.DEV`). Quando true, usa a edge function `dev-tokens` do Supabase conectado para autenticar. Quando false (app publicado), usa OAuth padrão do Qualiex.
+
+## 2. Qual API usar (`getEnvironmentConfig()` / `isDevSupabaseProject()`)
+Compara o project ID do Supabase conectado com `PROD_PROJECT_ID` (`ccjfvpnndclajkleyqkc`). Se igual → config PROD (API prod, OAuth prod). Se diferente → config DEV (API dev, OAuth dev).
+
+## Fonte de verdade do Project ID
+O project ID vem do `.env` (auto-populado pelo Lovable ao trocar banco), que o Vite injeta automaticamente em `import.meta.env.VITE_SUPABASE_PROJECT_ID`. **Não** é extraído de `src/integrations/supabase/client.ts`. O `vite.config.ts` usa `loadEnv()` apenas no contexto Node para configurar CSP headers.
+
+## Tabela de regras
+
+| Cenário                      | API  | Auth       |
+|------------------------------|------|------------|
+| Preview + Prod Supabase      | Prod | dev-tokens |
+| Preview + Dev Supabase       | Dev  | dev-tokens |
+| Publicado + Prod Supabase    | Prod | OAuth      |
+| Publicado + Dev Supabase     | Dev  | OAuth      |
+
+## Guard de troca de projeto (`TokenManager.checkProjectMismatch()`)
+Ao inicializar (`AuthService.initialize()`), o sistema compara `import.meta.env.VITE_SUPABASE_PROJECT_ID` com o valor armazenado em `localStorage('supabase_project_id')`. Se diferente, limpa todos os tokens stale automaticamente antes de qualquer chamada a `validate-token`, evitando 401 desnecessários. Após a limpeza, armazena o novo project ID. Isso garante transição limpa ao trocar de banco Supabase sem erros ou blank screen.
+
+## Funções (lib/config/index.ts)
+- `isLovablePreview()` — detecta contexto de preview/localhost
+- `shouldUseDevTokens()` — wrapper semântico sobre `isLovablePreview()`
+- `isDevEnvironment` — alias deprecated, mantido para compatibilidade
+- `getEnvironmentConfig()` — retorna config PROD ou DEV baseado no project ID
+- `isDevSupabaseProject()` — true se project ID ≠ PROD_PROJECT_ID
+
+## Funções (lib/auth/services/TokenManager.ts)
+- `checkProjectMismatch()` — detecta troca de projeto Supabase e limpa tokens stale

package/.note/memory/patterns/i18n-architecture.md

@@ -1,3 +1,3 @@
-# i18n Architecture
-
-A internacionalização utiliza namespaces 'core' (lib) e 'app' (consumidor). Traduções do consumidor são modularizadas em arquivos JSON por feature e mescladas via `mergeTranslationFiles`. Usa apenas i18next + JSONs estáticos (sem serviço externo de tradução). É mandatório o uso do hook `useTranslation` da biblioteca, garantindo fallback e suporte a flags de depuração. Os arquivos de tradução da biblioteca (`lib/i18n/locales/`) são restritos exclusivamente a chaves utilizadas por seus componentes internos; chaves órfãs ou termos de domínio de negócio devem ser geridos e traduzidos nos projetos consumidores no namespace 'app'.
+# i18n Architecture
+
+A internacionalização utiliza namespaces 'core' (lib) e 'app' (consumidor). Traduções do consumidor são modularizadas em arquivos JSON por feature e mescladas via `mergeTranslationFiles`. Usa apenas i18next + JSONs estáticos (sem serviço externo de tradução). É mandatório o uso do hook `useTranslation` da biblioteca, garantindo fallback e suporte a flags de depuração. Os arquivos de tradução da biblioteca (`lib/i18n/locales/`) são restritos exclusivamente a chaves utilizadas por seus componentes internos; chaves órfãs ou termos de domínio de negócio devem ser geridos e traduzidos nos projetos consumidores no namespace 'app'.