@seedgrid/ai-toolkit 0.0.0-stage → 0.3.1

package/seedgridKB/SeedGrid/SeedGrid-components/layout/Visao-geral.md

@@ -0,0 +1,98 @@
+---
+tags: [seedgrid, front, component, layout]
+fonte: front/seedgrid-fe-components/packages/seedgrid-fe-components/src/layout
+branch: main
+commit: ad30fc11de
+analisado-em: 2026-10-14
+---
+
+# Layout — visão geral
+
+Componentes de estrutura de tela do `@seedgrid/fe-components` (pasta `src/layout`): primitivas de composição (pilha, grade, painel com docking, tela), containers (card, accordion, abas, painel expansível, carrossel), navegação (breadcrumb, menu, árvore) e o sistema de **docking** de toolbars (`SgDockLayout`/`SgDockZone`/`SgDockScreen`/`SgToolBar`).
+
+- API completa (props, eventos, ref, a11y, funções): [[SeedGrid/SeedGrid-components/layout/API|Layout — API]]
+- Exemplos verificados: [[SeedGrid/SeedGrid-components/layout/Exemplos|Layout — exemplos]]
+- Instalação, CSS, i18n e utilitários: [[SeedGrid/SeedGrid-components/fundamentos/Visao-geral|Fundamentos]]
+- Persistência (`SgEnvironmentProvider`, `useSgPersistence`, `useSgPersistentState`): [[SeedGrid/SeedGrid-components/providers/Visao-geral|Providers]]
+
+## Componentes
+
+"Exportado" = presente em `src/index.ts` (barrel do pacote; único entry point JS em `exports["."]` do `package.json`). Rotas do showcase relativas ao app `apps/showcase`.
+
+| Componente | Exportado | Para que serve | Showcase |
+|---|---|---|---|
+| `SgStack` | sim | Flex em linha/coluna com `gap`, `justify`, `align`, `wrap`, `grow`. | `/components/sg-stack` |
+| `SgGrid` | sim | Grade CSS com colunas por breakpoint ou `minItemWidth` (auto-fit); respeita `span`/`rowSpan` dos filhos. | `/components/sg-grid` |
+| `SgPanel` | sim | Painel com borda/scroll e **docking** de painéis filhos por `align` (top/left/right/bottom/client). | `/components/sg-panel` |
+| `SgScreen` | sim | Raiz de tela (100% × 100dvh por padrão) com o mesmo docking de `SgPanel`. | `/components/sg-screen` |
+| `SgGroupBox` | sim | `fieldset` + `legend` para agrupar campos. | `/components/sg-group-box` |
+| `SgCard` | sim | Card com cabeçalho/rodapé, clicável, colapsável e arrastável (posição persistida). | `/components/sg-card` |
+| `SgAccordion` | sim | Seções colapsáveis verticais ou horizontais, controladas ou não. | `/components/sg-accordion` |
+| `SgPageControl` | sim | Abas com páginas declarativas; select nativo opcional no celular. | `/components/sg-page-control` |
+| `SgPageControlPage` | sim | Declaração de uma página do `SgPageControl`. | `/components/sg-page-control` |
+| `SgExpandablePanel` | sim | Painel expansível inline ou overlay (drawer) com resize, foco preso e Esc. | `/components/sg-expandable-panel` |
+| `SgCarousel` | sim | Carrossel com vários itens visíveis, circular, autoplay, navegadores e indicadores. | `/components/sg-carousel` |
+| `SgBreadcrumb` | sim | Trilha de navegação com colapso de excedentes ou rolagem. | `/components/sg-breadcrumb` |
+| `SgMenu` | sim | Menu de navegação: sidebar, drawer, inline, híbrido; variantes painel, em camadas e mega menu; busca; encaixe em dock. | `/components/sg-menu` |
+| `SgTreeView` | sim | Árvore com busca, checkboxes em cascata, modo confirmação, trilhas extras e ref imperativa. | `/components/sg-tree-view` |
+| `SgDockLayout` | sim | Provedor de zonas de encaixe e do estado persistido das toolbars. | `/components/sg-dock-layout` |
+| `SgDockZone` | sim | Zona nomeada (`top`/`bottom`/`left`/`right`/`free`) de um `SgDockLayout`. | `/components/sg-dock-layout` |
+| `SgDockScreen` | sim | `SgScreen` + `SgDockLayout` com grade 3×3 pronta. | `/components/sg-dock-screen` |
+| `SgToolBar` | sim | Barra de ferramentas colapsável, arrastável entre zonas ou livre. | `/components/sg-toolbar` |
+| `SgToolbarIconButton` | sim | Botão de toolbar com ícone, rótulo, `hint` (tooltip), severidade e loading automático para `onClick` assíncrono. | `/components/sg-toolbar` |
+| `useSgDockLayout` | não (interno) | Hook do contexto do dock (exportado só de `SgDockLayout.tsx`). | — |
+| `renderDockContent` e helpers de `sgDocking.tsx` | não (interno) | Motor de docking de `SgPanel`/`SgScreen`. | — |
+
+## Funções e tipos exportados relacionados
+
+- Árvore: `sgTreeFromJson`, `sgTreeFromJsonWithChecked`; tipos `SgTreeViewRef`, `SgTreeNode`, `SgTreeNodeJson`, `SgTreeIconRegistry`, `SgTreeConfirmBar`, `SgSize`, `SgDensity`, `SgTone`.
+- Lógica pura de menu (`src/layout/menu-logic.ts`): `buildMenuMaps`, `collectMenuSearchEntries`, `collectParentChain`, `computeActiveSets`, `filterMenuNodes`, `flattenVisibleNodes`, `mergeExpandedIdsForActivePath`, `resolveEffectiveActiveId`, `resolveExpandedIdsToggle`, `resolveHorizontalDockAlign`, `resolveMegaMenuActiveNode`, `resolveMegaMenuHoverActiveId`, `resolveMegaMenuInteraction`, `resolveMenuAutocompleteItems`, `resolveMenuHintPosition`, `resolveMenuKeyboardAction`, `resolveMenuLayoutState`, `resolveMenuNodeActionIntent`, `resolveMenuSearchSelectionState`, `resolveTieredActiveState`, `resolveTieredClickState`, `resolveTieredHoverIntent`, `resolveTieredHoverPath`, `resolveTieredNodeClickIntent` (24 funções) + tipos `MenuKeyboardAction`, `MenuVisibleNode`, `MenuLogicNode`.
+- Toolbar (`toolbar-logic.ts`): `buildToolbarLayoutState`, `resolveToolbarDockOrientationDirection`, `resolveToolbarOrientationDirection`.
+- Posição de arraste (`drag-position.ts`): `parseStoredPanelDragPosition`, `buildToolbarStorageKey`, `buildDockMenuStorageKey`.
+- Assinaturas completas: [[SeedGrid/SeedGrid-components/layout/API|API › Funções utilitárias exportadas]].
+
+## Como se compõem
+
+```mermaid
+flowchart TD
+  ENV[SgEnvironmentProvider<br/>opcional] -.persistência.-> DL
+  DS[SgDockScreen] --> SC[SgScreen]
+  DS --> DL[SgDockLayout<br/>estado dock-layout:&lt;id&gt;]
+  DL --> DZ[SgDockZone top/left/right/bottom/free]
+  DZ --> TB[SgToolBar]
+  TB --> TIB[SgToolbarIconButton]
+  DL -.portal na zona.-> MN[SgMenu dockable]
+  SC --> PN[SgPanel align=...]
+```
+
+- **Docking de painéis** (`SgPanel`/`SgScreen`): sem contexto; o pai inspeciona filhos `SgPanel` com `align` e monta as faixas. **Docking de toolbars** (`SgDockLayout`): contexto React + portal das toolbars/menus na zona atribuída — são mecanismos independentes (Confirmado).
+- **Persistência** (Confirmado): `SgDockLayout` usa `useSgPersistentState` (chave base `dock-layout:<id>`); `SgCard` (`sg-card-pos:<id>` ou `dragPersistKey`), `SgToolBar` com `freeDrag` (`sg-toolbar-pos:<id>`) e `SgMenu` (`sg-menu:<id>:collapsed`) usam `useSgPersistence` quando há `SgEnvironmentProvider` e `localStorage` direto quando não há.
+- **i18n**: textos padrão (rótulos ARIA, "vazio", placeholder de busca) vêm de `useComponentsI18n` — ver [[SeedGrid/SeedGrid-components/fundamentos/API|Fundamentos › i18n]].
+- `SgMenu` reutiliza `SgExpandablePanel` (drawer/hybrid), `SgAutocomplete` (busca), `SgAvatar` e `SgCard` (bloco do usuário).
+
+## Dependências externas
+
+- `react` (peer `^18.2.0 || ^19.0.0`), `react-dom` (`createPortal` em `SgExpandablePanel`, `SgMenu`, `SgToolBar`).
+- `lucide-react` (peer): ícones de `SgBreadcrumb`, `SgCarousel`, `SgMenu`.
+- Estilos via classes Tailwind compiladas no CSS do pacote (ver Fundamentos).
+
+## Testes que cobrem o grupo (não executados)
+
+| Arquivo | Cobertura relacionada |
+|---|---|
+| `tests/menu-logic.test.mjs` | Todas as funções de `menu-logic.ts` (mapas, cadeia de pais, ativo por id/url, busca, filtro, nós visíveis, teclado, tiered/mega, layout) e que o `SgMenu` consome os helpers. |
+| `tests/buttons-menus.test.mjs` | Rótulos traduzidos/ARIA de `SgMenu`, `SgToolBar`, `SgExpandablePanel`, `SgTreeView`, `SgCard`, `SgCarousel`, `SgBreadcrumb`, `SgPageControl`; helpers de `drag-position.ts` e `toolbar-logic.ts`. |
+| `tests/buttons-menus-dom.test.mjs` | DOM (jsdom): `SgToolBar` alterna conteúdo e notifica colapso; persistência do arraste livre em `localStorage`. |
+| `tests/i18n-components-contract.test.mjs` | Contrato de chaves i18n usadas em `SgMenu`, `SgCard`, `SgToolBar`, `SgExpandablePanel`, `SgCarousel`, `SgBreadcrumb`, `SgPageControl`. |
+
+Os testes rodam após `pnpm run build` (script `test` do pacote); não foram executados nesta análise.
+
+## Limitações e lacunas (Confirmado no código, salvo indicação)
+
+- `SgTreeView`: sem `role="tree"`/`treeitem` e sem navegação por setas; os tipos `SgTreeTrack*` da prop `tracks` não são exportados pelo barrel.
+- `SgCarousel`: botões anterior/próximo sem `aria-label`; sem teclado; índice não controlável de fora.
+- `SgToolBar`: sem `role="toolbar"`; `hideLabel` de `SgToolbarIconButton` não está em `SgToolbarIconButtonProps` (só na assinatura do componente).
+- `SgMenu`: item com `url` e sem `onNavigate` navega com `window.location.assign` (recarga completa) — em apps SPA passe `onNavigate`. `SgMenuOrientationDirection` não exportado.
+- `SgAccordion` vertical anima `max-height` até 960px (conteúdo maior pode ser cortado — Inferência).
+- `SgDockZone` sem `className` assume grade 3×3; com `className` o posicionamento é todo do chamador.
+- Componentes deste grupo não usam `forwardRef`, exceto `SgExpandablePanel` (`HTMLDivElement`) e `SgTreeView` (`SgTreeViewRef`).

package/seedgridKB/SeedGrid/SeedGrid-components/modulos/Visao-geral.md

@@ -0,0 +1,98 @@
+---
+tags: [seedgrid, front, modulo]
+fonte: front/seedgrid-fe-components/packages/modules; front/seedgrid-fe-components/packages/seedgrid-fe-core/src/cli-module-manifest.ts
+branch: main
+commit: ad30fc11de
+analisado-em: 2026-10-14
+---
+
+# Módulos front (`packages/modules/*`)
+
+Os módulos são pacotes npm `@seedgrid/fe-<domínio>` que entregam a parte **front-end** de uma funcionalidade de plataforma (autenticação, API keys, auditoria, backup, billing, tenancy, auto-cadastro) para apps Next.js gerados pela **CLI SeedGrid**. Cada um conversa com uma extension backend (Quarkus/Rust) via HTTP.
+
+Relacionados: [[SeedGrid/SeedGrid-components/pacotes/fe-core|@seedgrid/fe-core]] (contrato do manifesto e `createApiClient`) · [[SeedGrid/SeedGrid-components/pacotes/Visao-geral|Pacotes de base]].
+
+## Modelo de distribuição: lib + scaffold
+
+Decisão registrada em `packages/modules/SECURITY-EXTRACTION-MAP.md` e `FE-SECURITY-PACKAGE-CONTRACT.md` (Confirmado no código):
+
+- **Lógica** (sessão, refresh, permissões, DTOs, paths, chamadas HTTP, mensagens i18n) → **lib versionada** em `dist/` (compilada com `tsc`).
+- **Telas** (pages, forms, route handlers, menus) → **`scaffold/`** publicado junto (campo `files`), copiado pela CLI para dentro do app (modelo "shadcn": a lib dá as peças, a tela é do app). As referências `from: "@/modules/<nome>"` dos manifestos apontam para esse código copiado.
+- **Variantes** (ex.: tenancy por login × por subdomínio) são escolhidas na montagem pela CLI (`variantGroup`), não em runtime.
+- **Separação client/server**: a maioria expõe `./server` (código só-servidor: cookies httpOnly, Bearer, refresh) separado do `.` client-safe, para que `next/headers` não vaze para o bundle do browser. O browser fala *same-origin* com route handlers do Next; o servidor do Next segura o token e chama o backend.
+
+## Como se registram no fe-core
+
+**Não há registro em runtime** no `SeedGridRegistry` (Confirmado: nenhum módulo chama `registry.add*`). Cada pacote exporta `module: SeedGridCliModuleManifest` em `src/module.ts`; o `postbuild` (`scripts/emit-module-manifest.mjs`) importa `dist/module.js` e grava `dist/module.json`, **único artefato lido pela CLI** (comentário em `fe-core/src/cli-module-manifest.ts`).
+
+Campos do contrato: `id`, `requires`, `variantGroup`, `configKey`, `env`, `provider[]`, `navigation`, `messages`, `postAuthResolver` — ver [[SeedGrid/SeedGrid-components/pacotes/fe-core|fe-core › Módulos e registry]].
+
+| Pacote | Versão | `id` | `requires` | `variantGroup` | `env` | `provider` | `navigation` | `messages` | `postAuthResolver` | Nota |
+|---|---|---|---|---|---|---|---|---|---|---|
+| `@seedgrid/fe-security` | 2026.7.3 | `security` | — | — | — | `AuthProvider` (`@/modules/security`) | `useSecurityAppShellSections` | `securityMessages` | — | [[SeedGrid/SeedGrid-components/modulos/fe-security\|fe-security]] |
+| `@seedgrid/fe-apikeys` | 2026.7.0 | `api-keys` | `security` | — | — | — | — | — | — | [[SeedGrid/SeedGrid-components/modulos/fe-apikeys\|fe-apikeys]] |
+| `@seedgrid/fe-audit` | 2026.7.0 | `audit` | `security` | — | — | — | — | — | — | [[SeedGrid/SeedGrid-components/modulos/fe-audit\|fe-audit]] |
+| `@seedgrid/fe-backup` | 2026.7.0 | `backup` | `security` | — | — | — | `useBackupAppShellSections` | `backupMessages` | — | [[SeedGrid/SeedGrid-components/modulos/fe-backup\|fe-backup]] |
+| `@seedgrid/fe-billing-platform` | 2026.7.0 | `billing-platform` | `security` | — | — | — | `useBillingPlatformAppShellSections` | `billingPlatformMessages` | — | [[SeedGrid/SeedGrid-components/modulos/fe-billing-platform\|fe-billing-platform]] |
+| `@seedgrid/fe-billing-user` | 2026.7.0 | `billing-user` | `security` | — | — | — | `useBillingUserAppShellSections` | `billingUserMessages` | — | [[SeedGrid/SeedGrid-components/modulos/fe-billing-user\|fe-billing-user]] |
+| `@seedgrid/fe-login-tenancy` | 2026.7.0 | `login-tenancy` | `security` | `tenancy` | — | — | — | `loginTenancyMessages` | `resolveLoginTenancyPostAuthPath` | [[SeedGrid/SeedGrid-components/modulos/fe-login-tenancy\|fe-login-tenancy]] |
+| `@seedgrid/fe-self-enter` | 2026.7.0 | `self-enter` | `security` | — | — | — | — | — | — | [[SeedGrid/SeedGrid-components/modulos/fe-self-enter\|fe-self-enter]] |
+| `@seedgrid/fe-subdomain-tenancy` | 2026.7.0 | `subdomain-tenancy` | `security` | `tenancy` | — | `TenantProvider` (`@seedgrid/fe-subdomain-tenancy/client`) | — | — | — | [[SeedGrid/SeedGrid-components/modulos/fe-subdomain-tenancy\|fe-subdomain-tenancy]] |
+
+Todos Confirmados em `packages/modules/<pasta>/src/module.ts`. `configKey` = `id` em todos.
+
+## Pacotes: exports, dependências, scaffold e testes
+
+| Pacote | `exports` | peerDependencies | Arquivos em `scaffold/` | Testes (`node --test`, não executados) |
+|---|---|---|---|---|
+| fe-security | `.`, `./server`, `./client`, `./paths` | fe-core, fe-components, `next` (opcional), `react` (opcional) | 56 | `paths`, `module-manifest`, `permissions` |
+| fe-apikeys | `.`, `./server` | fe-core, fe-security | 1 | `module-manifest` |
+| fe-audit | `.`, `./server` | fe-core, fe-security | 0 (sem pasta no `files`) | `module-manifest` |
+| fe-backup | `.`, `./server` | fe-core, fe-security | 17 | `module-manifest`, `export-status` |
+| fe-billing-platform | `.`, `./server` | fe-core, fe-security | 18 | `module-manifest` |
+| fe-billing-user | `.`, `./server` | fe-core, fe-security | 19 | `module-manifest` |
+| fe-login-tenancy | `.`, `./client`, `./server` | fe-components (opcional), fe-core, fe-security, react | 12 | `module-manifest` |
+| fe-self-enter | `.`, `./server` | fe-core, fe-security | 3 | `module-manifest` |
+| fe-subdomain-tenancy | `.`, `./server`, `./client` | fe-core, fe-security, react (opcional) | 10 | `module-manifest`, `subdomain-rules` |
+
+Build de todos: `tsc -p tsconfig.json` + `postbuild` `node scripts/emit-module-manifest.mjs`. Contagem de `scaffold/` por `find -type f`.
+
+```mermaid
+graph TD
+  core["@seedgrid/fe-core"]
+  sec["fe-security"] --> core
+  sec --> comp["@seedgrid/fe-components"]
+  ak["fe-apikeys"] --> sec
+  au["fe-audit"] --> sec
+  bk["fe-backup"] --> sec
+  bp["fe-billing-platform"] --> sec
+  bu["fe-billing-user"] --> sec
+  lt["fe-login-tenancy"] --> sec
+  se["fe-self-enter"] --> sec
+  st["fe-subdomain-tenancy"] --> sec
+  lt -. "variantGroup tenancy (exclusivos)" .- st
+```
+
+## Relação com as extensions backend
+
+| Módulo front | Extension backend | Observação |
+|---|---|---|
+| fe-security | [[SeedGrid/Extensions/security/Visao-geral\|security]] | sessão, usuários, roles, companies, 2FA, self-enter, apikeys (paths) |
+| fe-apikeys | [[SeedGrid/Extensions/apikeys/Visao-geral\|apikeys]] | `ApiKeyPaths` espelha `RestControllerPath.java` da extension (Confirmado na nota do módulo) |
+| fe-audit | [[SeedGrid/Extensions/audit/Visao-geral\|audit]] | `/audit-logs` e sub-rotas |
+| fe-backup | [[SeedGrid/Extensions/backup/Visao-geral\|backup]] | `/exports/**` |
+| fe-billing-platform | [[SeedGrid/Extensions/billing/Visao-geral\|billing]] | `/admin/plans/**` (backoffice) |
+| fe-billing-user | [[SeedGrid/Extensions/billing/Visao-geral\|billing]] | `/me/*` do assinante (atenção aos endpoints de uso — ver nota) |
+| fe-login-tenancy | [[SeedGrid/Extensions/login-tenancy/Visao-geral\|login-tenancy]] + [[SeedGrid/Extensions/security/Visao-geral\|security]] | signup de empresa + `/me/companies`, `/me/select-company` |
+| fe-self-enter | [[SeedGrid/Extensions/security/Visao-geral\|security]] | não há extension própria; usa `SecurityPaths.selfEnter` |
+| fe-subdomain-tenancy | [[SeedGrid/Extensions/subdomain-tenancy/Visao-geral\|subdomain-tenancy]] | `/public/tenants`, validação/reenvio de e-mail |
+
+Detalhes de endpoints (método + path), permissões e telas em cada nota de módulo.
+
+## Configuração
+
+Variáveis de ambiente encontradas (detalhe e tabelas completas nas notas):
+- **fe-security** (scaffold): `NEXT_PUBLIC_SECURITY_SELF_ENTER_ENABLED`, `SEEDGRID_SECURITY_ACCESS_COOKIE_NAME`, `SEEDGRID_SECURITY_REFRESH_COOKIE_NAME`, `SEEDGRID_SECURITY_REFRESH_COOKIE_MAX_AGE_SECONDS`, `NODE_ENV` — ver [[SeedGrid/SeedGrid-components/modulos/fe-security|fe-security › Configuração]].
+- **fe-billing-platform**, **fe-billing-user**, **fe-login-tenancy** (scaffold, runtime server): `SEEDGRID_SECURITY_ACCESS_COOKIE_NAME` e `SEEDGRID_SECURITY_REFRESH_COOKIE_NAME` (mesmos nomes de cookie do fe-security).
+- **fe-subdomain-tenancy** (scaffold, runtime server): `SEEDGRID_CITIES_API_USERNAME` e `SEEDGRID_CITIES_API_KEY` 🔒 (API externa de cidades).
+- **fe-apikeys**, **fe-audit**, **fe-backup**, **fe-self-enter**: nenhuma leitura de `process.env` (grep em `src` e `scaffold`); backup usa o objeto `backupConfig`; self-enter depende indiretamente de `NEXT_PUBLIC_SECURITY_SELF_ENTER_ENABLED` (fe-security).

package/seedgridKB/SeedGrid/SeedGrid-components/modulos/fe-apikeys.md

@@ -0,0 +1,118 @@
+---
+tags: [seedgrid, front, modulo, fe-apikeys]
+fonte: front/seedgrid-fe-components/packages/modules/seedgrid-fe-apikeys
+branch: main
+commit: ad30fc11de
+analisado-em: 2026-10-14
+---
+
+# @seedgrid/fe-apikeys
+
+Módulo front de **API keys**: gestão de chaves de integração criadas **por role**, com o segredo exibido uma única vez na criação. Compõe sobre o motor de sessão do [[SeedGrid/SeedGrid-components/modulos/fe-security|fe-security]]. Faz parte dos [[SeedGrid/SeedGrid-components/modulos/Visao-geral|Módulos front]].
+
+Backend correspondente: [[SeedGrid/Extensions/apikeys/Visao-geral|extension apikeys (Quarkus)]] — `ApiKeyPaths` é declarado como espelho de `RestControllerPath.java` da extensão (**Confirmado**: paths conferidos contra `java/seedgrid-quarkus-ext-apikeys/runtime/src/main/java/br/com/seedgrid/apikeys/controllers/RestControllerPath.java`).
+
+## Pacote
+
+| Item | Valor |
+|---|---|
+| Nome npm | `@seedgrid/fe-apikeys` |
+| Versão | `2026.7.0` |
+| `type` | `module` |
+| peerDependencies | `@seedgrid/fe-core: *`, `@seedgrid/fe-security: *` |
+| devDependencies | `@seedgrid/fe-core`, `@seedgrid/fe-security` (`workspace:*`) |
+| `files` publicados | `dist`, `scaffold` |
+| Build | `tsc -p tsconfig.json`; `postbuild` → `node scripts/emit-module-manifest.mjs` (gera `dist/module.json`) |
+| Testes | `pnpm run build && node --test tests/module-manifest.test.mjs` |
+
+Campo `exports` do `package.json` (**Confirmado**):
+
+| Subpath | types | default | Natureza |
+|---|---|---|---|
+| `.` | `./dist/index.d.ts` | `./dist/index.js` | client-safe (DTOs + paths) |
+| `./server` | `./dist/server/index.d.ts` | `./dist/server/index.js` | SERVER-ONLY |
+
+Dependência de módulo: **requer `security`** (peer `@seedgrid/fe-security` + manifesto `requires: ["security"]`). Usa o tipo `SecurityServer` de [[SeedGrid/SeedGrid-components/modulos/fe-security|fe-security]].
+
+## Exports públicos
+
+| Export | Tipo | Subpath | Descrição | Fonte |
+|---|---|---|---|---|
+| `ApiKeyPaths` | const | `.` | Paths REST: `base`, `byRole(roleName)`, `revoke(publicId)` | `front/seedgrid-fe-components/packages/modules/seedgrid-fe-apikeys/src/paths.ts → ApiKeyPaths` |
+| `ApiKeyCreateRequest` | interface | `.` | `{ name; expiresDays? }` (ausente = sem expiração) | `.../seedgrid-fe-apikeys/src/apikeys.ts → ApiKeyCreateRequest` |
+| `ApiKeyCreateResponse` | interface | `.` | Resposta da criação; único momento em que `apiKey` (segredo cru) aparece | `.../src/apikeys.ts → ApiKeyCreateResponse` |
+| `ApiKeyListItem` | interface | `.` | Item de listagem (só `prefix`/`masked`, `roleName`, `expiresAt`, `revokedAt`, `lastUsedAt`) | `.../src/apikeys.ts → ApiKeyListItem` |
+| `ApiKeyRevokeResponse` | interface | `.` | `{ publicId; revokedAt }` | `.../src/apikeys.ts → ApiKeyRevokeResponse` |
+| `createApiKeysServer` | função | `./server` | `(session: SecurityServer) => ApiKeysServer` | `.../src/server/create-apikeys-server.ts → createApiKeysServer` |
+| `ApiKeysServer` | interface | `./server` | `createForRole`, `listByRole`, `listMine`, `revoke` | `.../src/server/create-apikeys-server.ts → ApiKeysServer` |
+
+Contagem: `.` = 5 exports; `./server` = 2 exports. `module` (manifesto) existe em `src/module.ts` mas **não** é reexportado pelo barrel — só é serializado em `dist/module.json`.
+
+## Registro no @seedgrid/fe-core (manifesto do CLI)
+
+Não há registro em runtime. O módulo exporta um `SeedGridCliModuleManifest` (tipo de [[SeedGrid/SeedGrid-components/pacotes/fe-core|@seedgrid/fe-core]], `packages/seedgrid-fe-core/src/cli-module-manifest.ts`) que o build serializa em `dist/module.json`, lido pelo SeedGrid CLI (Rust) para copiar o scaffold e fazer o wiring (**Confirmado**).
+
+| Campo | Valor |
+|---|---|
+| `id` | `api-keys` |
+| `requires` | `["security"]` |
+| `configKey` | `api-keys` |
+| `navigation` / `messages` / `provider` | não declarados |
+
+Comentário em `src/module.ts`: o item de menu e o atalho de dashboard de API keys vivem no scaffold do fe-security (`useSecurityAppShellSections.tsx`/`SecurityDashboard.tsx`), condicionados por `{{#if security_api_keys_enabled}}` (dirigido por `config.is_module_enabled("api-keys")`). **Confirmado** (comentário no código); o template do fe-security não foi verificado aqui.
+
+## Páginas (scaffold) e permissões
+
+| Rota | Arquivo | Permissões |
+|---|---|---|
+| `/security/api-keys` | `scaffold/src/app/security/api-keys/page.tsx → ApiKeysPage` | `RouteGuard` com `APIKEY_READ`, `APIKEY_CREATE`, `APIKEY_REVOKE` (`permissionMode="any"`); ações individuais via `usePermission` |
+
+A tela importa `securityService`, `securityConfig`, `RouteGuard` etc. de `@/modules/security` (scaffold do fe-security) — **não** usa `createApiKeysServer` nem os DTOs deste pacote (**Confirmado**). Usa componentes `SgButton`, `SgCombobox`, `SgConfirmationDialog`, `SgDatatable`, `SgInputText`.
+
+## APIs backend chamadas
+
+Via `createApiKeysServer` (lib, `session.apiFetchSecurity`):
+
+| Método | Path | Função |
+|---|---|---|
+| POST | `/apikeys/role/{roleName}` | `createForRole` |
+| GET | `/apikeys/role/{roleName}` | `listByRole` |
+| GET | `/apikeys` | `listMine` |
+| POST | `/apikeys/{publicId}/revoke` | `revoke` |
+
+Via scaffold (`securityService` do fe-security): os mesmos 4 + `GET /roles/integration` (`listIntegrationRoles`) — 5 endpoints distintos no total. No backend, `GET /apikeys` é `ApiKeyManagementController#listCurrentUserKeys` (aceita `page`/`size`), `@PermissionsAllowed("APIKEY_READ")` (**Confirmado**).
+
+## Separação client/server
+
+- `.`: só tipos e constantes — seguro no client.
+- `./server`: depende de `SecurityServer` (sessão por cookie, server-side). Usar em Route Handler/Server Action.
+
+## Configuração
+
+Nenhuma variável de ambiente lida (verificado com `grep process.env` em `src/` e `scaffold/`). Nenhum objeto de configuração próprio; a tela usa `securityConfig.pagination.defaultPageSize` do fe-security.
+
+## Exemplo de uso (fonte: README do pacote)
+
+```ts
+import { createSecurityServer } from "@seedgrid/fe-security/server";
+import { createApiKeysServer } from "@seedgrid/fe-apikeys/server";
+
+const session = createSecurityServer({ /* ... */ });
+export const apiKeys = createApiKeysServer(session);
+
+const nova = await apiKeys.createForRole("INTEGRATION", { name: "Integração ERP", expiresDays: 90 });
+const chaves = await apiKeys.listByRole("INTEGRATION");
+await apiKeys.revoke(chaves[0].publicId);
+```
+
+Nenhum consumidor em `apps/showcase` (verificado por grep).
+
+## Testes (não executados)
+
+- `tests/module-manifest.test.mjs`: verifica `id`, `requires`, `configKey` do `dist/module.json` (exige build prévio).
+
+## Limitações
+
+- O segredo da chave criada vem no campo `apiKey` da resposta (`ApiKeyCreateResponse`); o scaffold do fe-security tipa `key?`, então leia `apiKey`.
+- O backend expõe também `GET /apikeys/roles` e `GET /apikeys/me`, sem constante em `ApiKeyPaths`.
+

package/seedgridKB/SeedGrid/SeedGrid-components/modulos/fe-audit.md

@@ -0,0 +1,88 @@
+---
+tags: [seedgrid, front, modulo, fe-audit]
+fonte: front/seedgrid-fe-components/packages/modules/seedgrid-fe-audit
+branch: main
+commit: ad30fc11de
+analisado-em: 2026-10-14
+---
+
+# @seedgrid/fe-audit
+
+Módulo front de **auditoria**: consulta somente-leitura do trilho de auditoria (audit log) com filtros e detalhe antes/depois. Compõe sobre o motor de sessão do [[SeedGrid/SeedGrid-components/modulos/fe-security|fe-security]]. Faz parte dos [[SeedGrid/SeedGrid-components/modulos/Visao-geral|Módulos front]].
+
+Backend: [[SeedGrid/Extensions/audit/Visao-geral|extension audit]] — os paths batem com `java/seedgrid-quarkus-ext-audit/seedgrid-quarkus-ext-audit-core/runtime/src/main/java/br/com/seedgrid/audit/core/controllers/RestControllerPath.java` (`/audit-logs`, `/{id}`, `/entities`, `/users`) (**Confirmado**). O README e o comentário de `src/paths.ts` citam o "Audit Log Controller do `seedgrid-report-api`" e a lib `seedgrid-quarkus-lib-audit`; a extension do monorepo expõe os mesmos paths.
+
+## Pacote
+
+| Item | Valor |
+|---|---|
+| Nome npm / versão | `@seedgrid/fe-audit` `2026.7.0` |
+| peerDependencies | `@seedgrid/fe-core: *`, `@seedgrid/fe-security: *` |
+| `files` | `dist` (sem `scaffold`) |
+| Build | `tsc -p tsconfig.json` + `postbuild` `emit-module-manifest.mjs` → `dist/module.json` |
+| `exports` | `.` → `./dist/index.{d.ts,js}`; `./server` → `./dist/server/index.{d.ts,js}` |
+
+Dependência de módulo: **requer `security`** (usa `SecurityServer` e `PaginatedResult` de `@seedgrid/fe-security`).
+
+## Exports públicos
+
+| Export | Tipo | Subpath | Descrição | Fonte |
+|---|---|---|---|---|
+| `AuditPaths` | const | `.` | `logs`, `entities`, `users`, `byId(id)` | `front/seedgrid-fe-components/packages/modules/seedgrid-fe-audit/src/paths.ts → AuditPaths` |
+| `AuditOperation` | type | `.` | `"CREATE" \| "UPDATE" \| "DELETE" \| "READ" \| "OTHER"` | `.../src/audit.ts → AuditOperation` |
+| `AuditLogEntry` | interface | `.` | Registro com `beforeState`/`afterState` (JSON serializado), origem, IP, user-agent, `metadata?` | `.../src/audit.ts → AuditLogEntry` |
+| `AuditLogFilters` | interface | `.` | Filtros do `GET /audit-logs` + `page`/`size` | `.../src/audit.ts → AuditLogFilters` |
+| `AuditLogEntityOption` | interface | `.` | `{ id; entity }` | `.../src/audit.ts → AuditLogEntityOption` |
+| `AuditLogUserOption` | interface | `.` | `{ id; userName }` | `.../src/audit.ts → AuditLogUserOption` |
+| `createAuditServer` | função | `./server` | `(session) => AuditServer` | `.../src/server/create-audit-server.ts → createAuditServer` |
+| `AuditServer` | interface | `./server` | `searchLogs`, `listEntities`, `listUsers`, `getById` | `.../src/server/create-audit-server.ts → AuditServer` |
+
+Contagem: `.` = 6; `./server` = 2.
+
+## Registro no @seedgrid/fe-core (manifesto do CLI)
+
+`SeedGridCliModuleManifest` (tipo de [[SeedGrid/SeedGrid-components/pacotes/fe-core|@seedgrid/fe-core]]): `id: "audit"`, `requires: ["security"]`, `configKey: "audit"`. Sem `navigation`, `messages`, `provider` (**Confirmado**, `src/module.ts`).
+
+## Páginas, rotas e permissões
+
+**Nenhuma tela.** Não há pasta `scaffold/`; as telas de lista/detalhe de auditoria não são entregues pelo pacote ou pelo CLI. Nenhuma permissão é referenciada no pacote.
+
+## APIs backend chamadas (`createAuditServer`)
+
+| Método | Path | Função |
+|---|---|---|
+| GET | `/audit-logs?<filtros>` | `searchLogs` (filtros não vazios viram query string) |
+| GET | `/audit-logs/entities` | `listEntities` |
+| GET | `/audit-logs/users` | `listUsers` |
+| GET | `/audit-logs/{id}` | `getById` |
+
+## Separação client/server
+
+`.` só tipos/constantes; `./server` SERVER-ONLY (sessão do fe-security). Só leitura — nenhuma mutação.
+
+## Configuração
+
+Nenhuma variável de ambiente lida (verificado com `grep process.env`). Sem objetos de configuração.
+
+## Exemplo (fonte: README)
+
+```ts
+import { createSecurityServer } from "@seedgrid/fe-security/server";
+import { createAuditServer } from "@seedgrid/fe-audit/server";
+
+const session = createSecurityServer({ /* ... */ });
+export const audit = createAuditServer(session);
+const page = await audit.searchLogs({ entity: "User", operation: "UPDATE", operationDateFrom: "2026-07-01", page: 0, size: 20 });
+```
+
+Sem consumidor em `apps/showcase`.
+
+## Testes (não executados)
+
+`tests/module-manifest.test.mjs` — valida `id`, `requires`, `configKey` de `dist/module.json`.
+
+## Limitações
+
+- Não há telas de busca/detalhe de auditoria no pacote (o `files` não inclui `scaffold`).
+- As permissões de leitura do audit não são modeladas no front.
+

package/seedgridKB/SeedGrid/SeedGrid-components/modulos/fe-backup.md

@@ -0,0 +1,131 @@
+---
+tags: [seedgrid, front, modulo, fe-backup]
+fonte: front/seedgrid-fe-components/packages/modules/seedgrid-fe-backup
+branch: main
+commit: ad30fc11de
+analisado-em: 2026-10-14
+---
+
+# @seedgrid/fe-backup
+
+Módulo front de **backup/exportação de dados**: cria jobs de export, acompanha o status com polling, baixa o ZIP gerado e remove jobs. Compõe sobre o motor de sessão do [[SeedGrid/SeedGrid-components/modulos/fe-security|fe-security]]. Parte dos [[SeedGrid/SeedGrid-components/modulos/Visao-geral|Módulos front]].
+
+Backend: [[SeedGrid/Extensions/backup/Visao-geral|extension backup]] — `BackupPaths` espelha `java/seedgrid-quarkus-ext-backup/runtime/src/main/java/br/com/seedgrid/backup/controllers/RestControllerPath.java` (`/exports`, `/exports/{jobId}`, `/exports/{jobId}/download`) (**Confirmado**). O `scaffold/README.md` registra que `BackupFormat` e `ArtifactInfo.id` foram corrigidos contra `BackupFormat.java`/`ExportResponse.java` reais.
+
+## Pacote
+
+| Item | Valor |
+|---|---|
+| Nome npm / versão | `@seedgrid/fe-backup` `2026.7.0` |
+| peerDependencies | `@seedgrid/fe-core: *`, `@seedgrid/fe-security: *` |
+| `files` | `dist`, `scaffold` |
+| Build | `tsc -p tsconfig.json` + `postbuild` `emit-module-manifest.mjs` → `dist/module.json` |
+| Test (script) | `pnpm run build && node --test tests/module-manifest.test.mjs tests/export-status.test.mjs` |
+| `exports` | `.` → `./dist/index.{d.ts,js}`; `./server` → `./dist/server/index.{d.ts,js}` |
+
+Dependência de módulo: **requer `security`**.
+
+## Exports públicos
+
+| Export | Tipo | Subpath | Descrição | Fonte |
+|---|---|---|---|---|
+| `BackupPaths` | const | `.` | `exports`, `byId(jobId)`, `download(jobId)` | `front/seedgrid-fe-components/packages/modules/seedgrid-fe-backup/src/paths.ts → BackupPaths` |
+| `BackupFormat` | type | `.` | `"CSV_ZIP" \| "SQL_DUMP_ZIP"` | `.../src/backup.ts → BackupFormat` |
+| `ExportScope` | type | `.` | `"CUSTOM" \| "DOMAIN" \| "RAW"` | `.../src/backup.ts → ExportScope` |
+| `ExportStatus` | type | `.` | `REQUESTED`, `QUEUED`, `RUNNING`, `DONE`, `DONE_NOTIFIED`, `FAILED`, `CANCELLED`, `EXPIRED` | `.../src/backup.ts → ExportStatus` |
+| `ExportRequest` | interface | `.` | `{ format; scope; includeAttachments?; options? }` | `.../src/backup.ts → ExportRequest` |
+| `ArtifactInfo` | interface | `.` | Artefato (`id: number`, `filename`, `sizeBytes`, `sha256`…) | `.../src/backup.ts → ArtifactInfo` |
+| `ExportResponse` | type | `.` | Status/resultado do job (`progress`, `downloadable`, `artifacts`…) | `.../src/backup.ts → ExportResponse` |
+| `ExportStatusGroup` | type | `.` | `"pending" \| "running" \| "done" \| "failed" \| "terminal"` | `.../src/export-status.ts → ExportStatusGroup` |
+| `classifyExportStatus` | função | `.` | Mapeia `ExportStatus` → grupo | `.../src/export-status.ts → classifyExportStatus` |
+| `isExportInProgress` | função | `.` | `REQUESTED`/`QUEUED`/`RUNNING` | `.../src/export-status.ts → isExportInProgress` |
+| `isExportDownloadable` | função | `.` | `DONE`/`DONE_NOTIFIED` | `.../src/export-status.ts → isExportDownloadable` |
+| `backupMessages` | const | `.` | i18n: `en`, `es`, `fr`, `pt-BR`, `pt-PT` (merge sobre `en`) | `.../src/messages.ts → backupMessages` |
+| `createBackupServer` | função | `./server` | `(session) => BackupServer` | `.../src/server/create-backup-server.ts → createBackupServer` |
+| `BackupServer` | interface | `./server` | `createExport`, `listExports`, `getExportStatus`, `deleteExport`, `downloadExport` (devolve `Response` cru via `session.fetchWithSession`) | `.../src/server/create-backup-server.ts → BackupServer` |
+
+Contagem: `.` = 12; `./server` = 2.
+
+## Registro no @seedgrid/fe-core (manifesto do CLI)
+
+`SeedGridCliModuleManifest` ([[SeedGrid/SeedGrid-components/pacotes/fe-core|@seedgrid/fe-core]]), `src/module.ts` (**Confirmado**):
+
+| Campo | Valor |
+|---|---|
+| `id` / `configKey` | `backup` / `backup` |
+| `requires` | `["security"]` |
+| `navigation` | `{ import: "useBackupAppShellSections", from: "@/modules/backup" }` |
+| `messages` | `{ import: "backupMessages", from: "@seedgrid/fe-backup" }` |
+| `provider` | ausente |
+
+Menu (`scaffold/src/modules/backup/useBackupAppShellSections.tsx`): seção `backup` (order 50) → item `backup-management` → filho `backup-exports` (`/backup/exports`), visível só com `JOB_READ`.
+
+## Páginas (scaffold) e permissões
+
+| Rota | Arquivo | Permissão |
+|---|---|---|
+| `/backup/exports` | `scaffold/src/app/backup/exports/(list)/page.tsx` | `RouteGuard` `JOB_READ`; polling a cada `backupConfig.polling.intervalMs` |
+| `/backup/exports/new` | `scaffold/src/app/backup/exports/(create)/new/page.tsx` | `RouteGuard` `JOB_CREATE` |
+| `GET /api/backup/exports/[jobId]/download` (Route Handler) | `scaffold/src/app/api/backup/exports/[jobId]/download/route.ts → GET` | repassa `Authorization`/`Cookie` ao backend; 404/410/502 mapeados |
+
+Scaffold extra: `modules/backup/config.ts` (`backupConfig`), `services/backup-api.ts` (`configureBackupApi`, `extractBackupApiMessage`, `isApiClientError`), `services/backup-service.ts` (`backupService`), `components/ExportStatusBadge.tsx`, `types.ts` (reexporta a lib).
+
+## APIs backend chamadas
+
+| Método | Path | Onde |
+|---|---|---|
+| POST | `/exports` | `createExport` (lib) / `backupService.createExportJob` (scaffold) |
+| GET | `/exports` (scaffold envia `?page=&size=`) | `listExports` / `listExportJobs` |
+| GET | `/exports/{jobId}` | `getExportStatus` |
+| DELETE | `/exports/{jobId}` | `deleteExport` / `deleteExportJob` |
+| GET | `/exports/{jobId}/download` | `downloadExport` / Route Handler de download |
+
+5 endpoints.
+
+## Separação client/server
+
+- Lib `.`: tipos, helpers puros e mensagens — client-safe. `./server`: SERVER-ONLY.
+- Scaffold client: `backupConfig.apiBaseUrl` = `"/api"` quando `window` existe (proxy Next.js "para evitar CORS"); no server usa `appEnvironment.hosts.apiOrigin` (de `@/config/environment` do app).
+
+## Configuração
+
+Nenhuma variável de ambiente lida diretamente (verificado com `grep process.env`). Há um objeto de configuração no scaffold:
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `backupConfig.apiBaseUrl` | string | URL ou `/api` | `"/api"` no browser; `appEnvironment.hosts.apiOrigin` no server | Não (calculado) | Base do `createApiClient` do scaffold | `backup-api.ts → privateClient` | depende de `@/config/environment` (app) | runtime client / runtime server | `scaffold/src/modules/backup/config.ts → resolveApiBaseUrl` |
+| `backupConfig.pagination.defaultPageSize` | number | inteiro | `10` | Não | Tamanho de página inicial | telas de lista | — | runtime client | `scaffold/.../config.ts → backupConfig` |
+| `backupConfig.pagination.pageSizeOptions` | number[] | inteiros | `[10, 20, 50]` | Não | Opções do paginador | telas de lista | — | runtime client | idem |
+| `backupConfig.polling.intervalMs` | number | ms | `5000` | Não | Intervalo de polling dos jobs em andamento | `(list)/page.tsx` | `isExportInProgress` | runtime client | idem |
+| `backupConfig.routes.exports` | string | rota | `"/backup/exports"` | Não | Rota da lista / menu | `useBackupAppShellSections` | — | runtime client | idem |
+| `backupConfig.routes.newExport` | string | rota | `"/backup/exports/new"` | Não | Rota de criação | telas | — | runtime client | idem |
+
+`appEnvironment.hosts.apiOrigin` vem do app/fe-security (não deste pacote) — ver [[SeedGrid/SeedGrid-components/modulos/fe-security|fe-security]].
+
+## Exemplo (fonte: README)
+
+```ts
+import { createBackupServer } from "@seedgrid/fe-backup/server";
+const backup = createBackupServer(session);
+const job = await backup.createExport({ format: "CSV_ZIP", scope: "DOMAIN" });
+const status = await backup.getExportStatus(job.jobId);
+```
+
+```ts
+import { classifyExportStatus, isExportDownloadable } from "@seedgrid/fe-backup";
+```
+
+Sem consumidor em `apps/showcase`.
+
+## Testes (não executados)
+
+- `tests/module-manifest.test.mjs`: `id`, `requires`, `configKey`, `messages`, `navigation`, `provider === undefined`.
+- `tests/export-status.test.mjs`: classificação dos 8 status, `isExportInProgress`, `isExportDownloadable`.
+- Scaffold (Vitest + Testing Library): `page.test.tsx` (lista e criação), `ExportStatusBadge.test.tsx`, `backup-api.test.ts`, `backup-service.test.ts`, `useBackupAppShellSections.test.tsx`.
+
+## Limitações
+
+- O client chama `/api/exports...`; o scaffold só traz o proxy de download, então o app precisa de um proxy genérico `/api/*`.
+- `configureBackupApi` não é chamado no scaffold: ligue o token no seu app.
+- `ExportStatusGroup` assume `pending`, `running`, `done`, `failed` ou `terminal`.
+