@seedgrid/ai-toolkit 0.0.0-stage → 0.3.0

package/seedgridKB/SeedGrid/Extensions/login-tenancy/Rust.md

@@ -0,0 +1,139 @@
+---
+tags: [seedgrid, extension, login-tenancy, rust]
+fonte: rust/seedgrid-rust-crate-login-tenancy
+branch: main
+commit: be738a2d1e
+analisado-em: 2026-10-14
+---
+
+# `seedgrid-rust-crate-login-tenancy` — porte Rust
+
+Lado Java: [[SeedGrid/Extensions/login-tenancy/Visao-geral|Visão geral do login-tenancy (Quarkus)]] · [[SeedGrid/Extensions/login-tenancy/Configuracao|Configuração Java]]
+Configuração deste crate: [[SeedGrid/Extensions/login-tenancy/Configuracao-Rust|Configuração Rust do login-tenancy]]
+
+## Objetivo
+
+Porte da extensão `seedgrid-quarkus-ext-login-tenancy` (ex-`accounttenancy`): **foundation de banco único** com tenant-por-conta (Company + usuário root por CNPJ), sem subdomínio nem tenant técnico. Oferece:
+
+- **Signup institucional** (`/public/signup*`): pedido com código de 6 dígitos por e-mail, confirmação que cria Company + usuário root (ou vincula e-mail existente), evento `SignupConfirmedEvent`.
+- **SPIs de security**: audiência JWT `platform` (empresa-plataforma) / `client` (demais) e super-leitura para membros da empresa-plataforma.
+- **SPIs de audit**: isolamento de leitura por `companyPublicId` e carimbo na escrita.
+- **Orquestrador `assemble_all`**: migra security → audit → login-tenancy e devolve um `Router` agregado (security + signup/status + `/audit-logs` gateado por `LOG_READ`) e a OpenAPI agregada.
+- PII at-rest do `signup_request` via `CryptoProvider` global do `seedgrid-privacy` (bimodal por hash).
+
+## Coordenadas
+
+| Item | Valor |
+|---|---|
+| Diretório / pacote / lib | `rust/seedgrid-rust-crate-login-tenancy` / `seedgrid-rust-crate-login-tenancy` / `seedgrid_login_tenancy` |
+| Versão | `version.workspace = true` → `2026.10.14` |
+| Features | nenhuma |
+| Dependências SeedGrid | `seedgrid-security`, `seedgrid-privacy`, `seedgrid-audit`, `seedgrid-resilience`, `seedgrid-billing` (`default-features = false`, só domínio/SPI) |
+
+## API pública
+
+| Símbolo | Papel |
+|---|---|
+| `LoginTenancyConfig` (+ `from_env`), `LoginTenancyFoundationConfig`, `ModuleRegistry`, `FoundationModule` | config/fachada — ver [[SeedGrid/Extensions/login-tenancy/Configuracao-Rust\|Configuração Rust]] |
+| `assemble_all(Option<PgPool>, LoginTenancyPlatformOverrides)` → `AssembledLoginTenancy { security, audit, state, router, openapi }` | montagem completa single-DB; sem pool → tudo `None` e router vazio |
+| `LoginTenancyState::builder(pool, foundation)` → `.cipher`, `.cipher_from_base64_key`, `.email`, `.template`, `.password_policy`, `.jwt_issuer`, `.first_admin_email`, `.signup_confirmed_handler`, `.company_public_id_resolver`, `.build()` | estado do signup |
+| `router(LoginTenancyState)` | rotas abaixo |
+| `migrate(&PgPool)` / `MIGRATOR` | `0700`, `0701`, `0703`; histórico `_sqlx_migrations_login_tenancy` |
+| `spi_security::{LoginTenancyAllowedCompaniesResolver, LoginTenancyJwtTokenCustomizer}` (`AUDIENCE_PLATFORM`, `AUDIENCE_CLIENT`) | SPIs para o security |
+| `spi_audit::{LoginTenancyAuditReadScopeProvider, CompanyAuditMetadataContributor, CachedCompanyPublicIdResolver}` | SPIs para o audit (headers `x-seedgrid-company-id` / `x-seedgrid-all-companies`) |
+| `security_gate::{SecurityAuditAuthorizer, FixedAuditStateResolver, inject_trusted_company_scope_middleware}` | auth da leitura de auditoria |
+| `ratelimit::signup_*_rate_limit()` | fábricas `SeedGridRateLimit` (o host aplica) |
+| `openapi()` | spec utoipa |
+
+## Endpoints (Confirmado em `src/routes.rs`)
+
+| Método | Path | Observação |
+|---|---|---|
+| POST | `/public/signup` | 202; recusa CNPJ duplicado (409) |
+| GET | `/public/signup/email-exists` | — |
+| POST | `/public/signup/confirm-email` | cria Company + root |
+| POST | `/public/signup/resend-email` | — |
+| GET | `/public/signup/cnpj-status` | — |
+| GET | `/public/login-tenancy/status` | `{app, activeModules, bootstrap{enabled,admin}, security{jwtIssuer, firstAdminConfigured}}`; 404 se status desligado |
+
+Via `assemble_all` também entram as rotas do security (incl. `/me/security/users` e `/me/security/roles`, servidas pelo security) e a leitura de auditoria `/audit-logs`.
+
+## Exemplo (Confirmado em `rust/examples/seedgrid-login-tenancy-example/src/main.rs`)
+
+```rust
+use std::sync::Arc;
+use seedgrid_login_tenancy::{assemble_all, LoginTenancyPlatformOverrides};
+
+async fn boot(pool: sqlx::PgPool) -> Result<(), Box<dyn std::error::Error>> {
+    let overrides = LoginTenancyPlatformOverrides {
+        signup_confirmed: Some(Arc::new(MeuHandler)), // impl SignupConfirmedHandler
+        ..Default::default()
+    };
+    let assembled = assemble_all(Some(pool), overrides)
+        .await
+        .map_err(|e| format!("assemble_all falhou: {e}"))?;
+    let app = axum::Router::new().nest("/api/v1", assembled.router);
+    let _ = app;
+    Ok(())
+}
+```
+
+(`MeuHandler` é ilustrativo; o exemplo usa `LoggingSignupConfirmed`. O exemplo serve o router sem `nest`.)
+
+## Migrations
+
+`0700_signup_request.sql`, `0701_privacy_search_hashes.sql`, `0703_signup_request_pending_unique_by_cnpj.sql` (não há `0702`). Rodar depois do security.
+
+## Testes
+
+Unitários em `src/**` (config, error, dtos, SPIs) e `tests/foundation_it.rs` (Postgres via Testcontainers). **Não executados** nesta análise.
+
+## Notas de comportamento
+
+- A orquestração de migrations e os serviços de lifecycle Quarkus (`AccountTenancyBootstrapService`, readiness) ficam com o host; as flags `bootstrap.*`/`modules.*` só aparecem no status.
+- `assemble_all` não monta billing/apikeys/backup/filemanagement apesar das flags de módulo.
+- O signup usa `PasswordPolicy` própria (não a do security).
+
+## Enums
+
+Equivalentes Java em [[SeedGrid/Extensions/login-tenancy/Enums|Enums (Quarkus)]].
+
+| Enum | Arquivo | Usado em | Equivalente Java |
+|---|---|---|---|
+| `SignupRequestStatus` | `src/models.rs` | coluna `signup_request.status`; respostas do signup | [[SeedGrid/Extensions/login-tenancy/Enums#SignupRequestStatus\|SignupRequestStatus]] |
+| `CnpjSignupStatus` | `src/dtos.rs` | `GET /public/signup/cnpj-status` | [[SeedGrid/Extensions/login-tenancy/Enums#CnpjSignupStatus\|CnpjSignupStatus]] |
+| `FoundationModule` | `src/config.rs` | `ModuleRegistry`; `activeModules` do status | [[SeedGrid/Extensions/login-tenancy/Enums#FoundationModule\|FoundationModule]] |
+| `StateEnum` | `src/dtos.rs` | `state` do `AddressDto` do signup | `StateEnum` da lib commons (`br.com.seedgrid.commons.core.enums`) |
+| `LoginTenancyError` | `src/error.rs` | erro dos serviços, resposta RFC 7807 | exceções do Java (sem enum) |
+
+### SignupRequestStatus
+
+| Variante | Valor | Observação |
+|---|---|---|
+| `PendingEmailVerification` | `PENDING_EMAIL_VERIFICATION` | gravado no signup e no reenvio |
+| `Confirmed` | `CONFIRMED` | gravado em `confirm-email` |
+
+Serde `SCREAMING_SNAKE_CASE` (Serialize e Deserialize); `as_db_str()` / `from_db_str()`. **`from_db_str` é tolerante**: qualquer string diferente de `CONFIRMED` vira `PendingEmailVerification`. Coluna `status varchar(64) not null`, sem CHECK (`migrations/0700_signup_request.sql`). Java: mesmos 2 valores.
+
+### CnpjSignupStatus
+
+`Available` → `AVAILABLE`, `Registered` → `REGISTERED`, `PendingConfirmation` → `PENDING_CONFIRMATION` (serde `SCREAMING_SNAKE_CASE`, só `Serialize`; não persistido). `pendingEmailMasked` só vem em `PENDING_CONFIRMATION`. Java: mesmos 3 valores.
+
+### FoundationModule
+
+`Billing`, `Apikeys`, `Backup`, `Filemanagement` (ordem de `FoundationModule::ALL`). `name_lower()` devolve `billing` / `apikeys` / `backup` / `filemanagement`, usado em `activeModules`. Controlado pelas envs `SEEDGRID_LOGIN_TENANCY_MODULES_<MOD>_ENABLED` ([[SeedGrid/Extensions/login-tenancy/Configuracao-Rust|Configuração Rust]]). Não é serializado nem persistido. Java: `BILLING`, `APIKEYS`, `BACKUP`, `FILEMANAGEMENT`, os mesmos 4 valores.
+
+### StateEnum
+
+27 UFs na ordem do Java (`AC AL AP AM BA CE DF ES GO MA MT MS MG PA PB PR PE PI RJ RN RS RO RR SC SP SE TO`); as variantes Rust são `Ac`, `Al`, ... Serializa como **sigla**; desserializa sigla (sem diferenciar caixa) **ou nome completo** do estado (`from_json`). Valor inválido gera erro de bind, respondido como 400 `Dados invalidos`. `signup.rs` grava `sigla()` em `addr_state`. Mesmo conjunto e ordem do `StateEnum` Java.
+
+### LoginTenancyError
+
+| Variante | HTTP |
+|---|---|
+| `CompanyAlreadyExists`, `SignupRequestPending` | 409 |
+| `SignupRequestNotFound` | 404 |
+| `BadRequest` | 400 |
+| `RequiredRoleMissing`, `TemplateProcessing`, `Crypto`, `Database`, `Internal` | 500 |
+
+`type` e `title` do corpo seguem o `ProblemType` do Java (`src/error.rs`).

package/seedgridKB/SeedGrid/Extensions/login-tenancy/Visao-geral.md

@@ -0,0 +1,130 @@
+---
+tags: [seedgrid, extension, login-tenancy]
+fonte: java/seedgrid-quarkus-ext-login-tenancy
+branch: main
+commit: c67581bda9
+analisado-em: 2026-10-14
+---
+
+# Login-tenancy (Quarkus) — visão geral
+
+Foundation **orquestradora** para aplicações **banco único, multi-empresa (pooled)**: um só PostgreSQL compartilhado por N companies, com isolamento **lógico** (escopo do token + providers SPI). Uma única dependência traz e "fia" os módulos de foundation da v1 (security, audit, billing-core, backup, apikeys, filemanagement, privacy, resilience), orquestra as migrations por módulo, coordena o bootstrap, expõe signup institucional (empresa + usuário root), status técnico e readiness. Não existe `seedgrid.login-tenancy.enabled`: a presença da dependência ativa o baseline.
+
+- Configuração: [[SeedGrid/Extensions/login-tenancy/Configuracao|Configuração do login-tenancy]]
+- Exemplos: [[SeedGrid/Extensions/login-tenancy/Exemplos|Exemplos do login-tenancy]]
+- Enums: [[SeedGrid/Extensions/login-tenancy/Enums|Enums do login-tenancy]]
+- Porte Rust (crate `seedgrid-rust-crate-login-tenancy`): [[SeedGrid/Extensions/login-tenancy/Rust|Porte Rust]]
+- Alternativa com isolamento físico por tenant: [[SeedGrid/Extensions/subdomain-tenancy/Visao-geral|subdomain-tenancy]] (mutuamente exclusivas, segundo o README).
+
+## Módulos Maven e coordenadas (Confirmado — `pom.xml`)
+
+| Módulo | groupId | artifactId | Versão |
+|---|---|---|---|
+| parent | `br.com.seedgrid` | `seedgrid-login-tenancy-parent` | `2026.10.14-1` |
+| runtime | `br.com.seedgrid` | `seedgrid-login-tenancy` | `2026.10.14-1` |
+| deployment | `br.com.seedgrid` | `seedgrid-login-tenancy-deployment` | `2026.10.14-1` |
+
+Parent: `br.com.seedgrid:seedgrid-parent:2026.07.02`. Status `preview`.
+
+## Dependências SeedGrid (versões do `pom.xml` do parent)
+
+| Artefato | Versão | Papel |
+|---|---|---|
+| `seedgrid-commons` | `2026.10.08` | embeddables `Address`/`Contact`, `ApiExceptionExtension` |
+| `seedgrid-security` (+ `-deployment`) | `2026.10.14` | `Company`, `User`, `Role`, JWT, `EmailServiceInterface`, SPIs de escopo — ver [[SeedGrid/Extensions/security/Visao-geral|security]] |
+| `seedgrid-audit-core`, `seedgrid-audit-postgresql` (`seedgrid-audit-mongodb` só gerenciado) | `2026.09.25` | auditoria e SPIs `AuditMetadataContributor`/`AuditReadScopeProvider` |
+| `seedgrid-backup` (+ `-deployment`) | `2026.10.09` | backup |
+| `seedgrid-billing-core` (+ `-deployment`) | `2026.10.14-1` | cobrança agnóstica; `AccountProvisioningService` |
+| `seedgrid-apikeys` (+ `-deployment`) | `2026.10.14` | ver [[SeedGrid/Extensions/apikeys/Visao-geral|apikeys]] |
+| `seedgrid-notification` (+ `-deployment`) | `2026.10.15` | catálogo de eventos, regras, outbox e envio por e-mail/WhatsApp; vem transitivamente, o host não precisa declará-la — ver [[SeedGrid/Extensions/notification/Visao-geral|notification]] |
+| `seedgrid-filemanagement` | `2026.07.08` | arquivos |
+| `seedgrid-privacy` | `2026.07.27` | mascaramento/criptografia de PII |
+| `seedgrid-resilience-core` | `2026.10.13` | `@SeedGridRateLimit` |
+
+O **provider de billing** concreto (`BillingProvider`) não vem embarcado: o host precisa fornecer (ex.: `seedgrid-billing-stripe`) ou o boot falha (README; o teste usa `NoopBillingProvider`). Também empacota `quarkus-mongodb-client` como dependência opcional (README) para a auditoria MongoDB.
+
+## Arquitetura
+
+### Ordem de inicialização (Confirmado)
+
+| Prioridade | Componente | O que faz |
+|---|---|---|
+| 2000 (`APPLICATION`) | `LoginTenancyMigrationService#onStart` | Flyway por módulo no datasource único (Flyway nativo do Quarkus desligado) |
+| 2100 | `LoginTenancyBootstrapService#onStart` | Só coordena/loga o bootstrap de admin (delegado ao security) e os módulos ativos |
+| 2500 (padrão) | `FirstAdminBootstrapService` (security) | company default + primeiro admin |
+
+### Migrations orquestradas (Confirmado — `LoginTenancyMigrationService`)
+
+```mermaid
+flowchart LR
+    S[security<br/>flyway_schema_history_security] --> A{audit strategy = jpa?}
+    A -- sim --> AU[audit]
+    A -- não --> B
+    AU --> B{modules.backup}
+    B -- on --> BK[backup] --> BI
+    B -- off --> BI{modules.billing}
+    BI -- on --> BL[billing] --> AK
+    BI -- off --> AK{modules.apikeys}
+    AK -- on --> AP[apikeys] --> X
+    AK -- off --> X{ai-pricing / exchange<br/>migration.enabled}
+    X --> LT[login-tenancy<br/>V700-V703] --> APP["app (database.locations)<br/>flyway_schema_history"]
+```
+
+Cada módulo usa `classpath:db/migration/<modulo>` e a tabela `flyway_schema_history_<modulo>` (`ai-pricing` → `flyway_schema_history_ai_pricing`; `login-tenancy` → `flyway_schema_history_login_tenancy`); a aplicação usa `seedgrid.login-tenancy.database.locations` (padrão `classpath:db/migration/app`) e `flyway_schema_history`. Falha em qualquer módulo lança `MigrationExecutionException` e derruba o startup.
+
+### Isolamento lógico por company
+
+- `LoginTenancyAllowedCompaniesResolver` (SPI do security): memberships reais em `allowedCompanies`; membros da **default company** recebem super-leitura (`seeAll`) — usada no audit.
+- `LoginTenancyLoginScopeResolver` e `LoginTenancyJwtTokenCustomizer` (SPIs do security): escopo do login e claim `audience` = `platform` se a empresa corrente é a default company (comparação por CNPJ via `DefaultCompanyConfig`), senão `client`.
+- `CompanyAuditMetadataContributor` carimba `companyPublicId` na escrita do audit; `LoginTenancyAuditReadScopeProvider` força o filtro na leitura (sem contexto ⇒ nega).
+- `LoginTenancyAccountUserActivationMailer` (SPI `AccountUserActivationMailer` do security): e-mail de ativação quando admin de empresa cria usuário em `/me/security/users`.
+- `LoginTenancyBillingProvisioner`: ao `SignupConfirmedEvent` (AFTER_SUCCESS, `REQUIRES_NEW`) garante conta de billing com trial, se `modules.billing.enabled`.
+
+## API pública
+
+### REST (Confirmado — `RestControllerPath`)
+
+| Método | Path | Rate limit (`configKey`, padrão) | Descrição |
+|---|---|---|---|
+| `POST` | `/public/signup` | `signup`, 10/min | Cadastro institucional → `202 {status, signupRequestId, emailDelivered}`. Reaproveita solicitação pendente do mesmo CNPJ+e-mail; outro e-mail no mesmo CNPJ → `409`. E-mail existente = vinculação de nova empresa (senha ignorada). |
+| `GET` | `/public/signup/email-exists?email=` | `signup-email-exists`, 10/min | `{exists}` |
+| `GET` | `/public/signup/cnpj-status?cnpj=` | `signup-cnpj-status`, 10/min | `{status: AVAILABLE\|REGISTERED\|PENDING_CONFIRMATION, pendingEmailMasked}` |
+| `POST` | `/public/signup/confirm-email` | `signup-confirm-email`, 10/min | `{token}` (6 dígitos, com ou sem traço) → cria `Company` + usuário root com role `ADMIN` por conta, envia boas-vindas, dispara `SignupConfirmedEvent` |
+| `POST` | `/public/signup/resend-email` | `signup-resend-email`, 5/h | Gera novo código e reenvia |
+| `GET` | `/public/login-tenancy/status` | — | `app`, `activeModules`, `bootstrap`, `security.jwtIssuer`, `security.firstAdminConfigured`; `404` se `foundation.status.enabled=false` |
+| health | readiness `login-tenancy-foundation` | — | `Connection.isValid(2)` no datasource; UP sem tocar o banco se `foundation.health.enabled=false` |
+
+O código de verificação **não** volta na resposta do signup (`SignupResponse`): só chega pelo e-mail.
+
+### Eventos, SPIs e beans
+
+| Símbolo | Tipo | Uso |
+|---|---|---|
+| `br.com.seedgrid.logintenancy.dtos.SignupConfirmedEvent(cnpj, companyPublicId, corporateName, tradeName, rootEmail, representativeName)` | evento CDI | Pós-processamento de domínio no host |
+| `br.com.seedgrid.logintenancy.spis.LoginTenancyTemplateProvider` | SPI (`DefaultLoginTenancyTemplateProvider` é `@DefaultBean`) | `signupConfirmation`, `signupWelcome`, `userActivation`. Override por bean ou por arquivo em `templates/logintenancy/<nome>.html` (fallback `templates/logintenancy-default/html/`) |
+| `LoginTenancyConfig` / `LoginTenancyFoundationConfig` | `@ConfigMapping` / fachada CDI | ver [[SeedGrid/Extensions/login-tenancy/Configuracao|Configuração]] |
+| `LoginTenancyModuleRegistry` | bean | `isActive(FoundationModule)`, `activeModules()` |
+| `LoginTenancyMongoAuditDatabaseProducer` | producer `@DefaultBean` de `MongoDatabase` | registrado só se `com.mongodb.client.MongoClient` estiver no classpath (`LoginTenancyProcessor#registerMongoAuditDatabaseProducer`) |
+| `LoginTenancyApiExceptionExtension` | `ApiExceptionExtension` | `SignupRequestNotFoundException`→404, `SignupRequestPendingException`→409, `RequiredRoleMissingException`→500 (`application/problem+json`) |
+
+## Migrations próprias
+
+`runtime/src/main/resources/db/migration/login-tenancy/`: `V700__signup_request.sql`, `V701__privacy_search_hashes.sql`, `V702__timestamps_com_fuso.sql`, `V703__signup_request_pendente_unica_por_cnpj.sql` (faixa 700). Há um `docs/RUNBOOK-remocao-da-V704.md` (não analisado em detalhe).
+
+## Testes existentes (não executados)
+
+| Teste | Cobertura |
+|---|---|
+| `runtime/src/test/.../LoginTenancyFoundationIT` | config com defaults, migrations por schema, company default, endpoint de status, readiness (PostgreSQL via Dev Services) |
+| `.../controllers/SignupAccountRootIT` | confirmação torna o dono root da conta, não root global |
+| `.../controllers/SignupBillingAccountIT` | confirmação cria conta de billing com trial |
+| `.../controllers/SignupDedupIT` | reaproveitamento de pendente, conflito com outro e-mail, `emailDelivered`, `cnpj-status` |
+| `.../spis/*Test` | metadata/escopo de audit, resolvedor de escopo de login, defaults de gestão de conta |
+| `.../unit/LoginTenancyFoundationConfigTest`, `LoginTenancyModuleRegistryTest` | lógica da fachada e do registry |
+
+## Limitações
+
+- `modules.apikeys.enabled`, `modules.backup.enabled` e `modules.filemanagement.enabled` controlam só migrations e/ou o que aparece no status — **não** removem beans/endpoints desses módulos (Confirmado: não há outro consumo). Só `modules.billing.enabled` também alimenta `seedgrid.billing.api.enabled` e o provisionamento.
+- `bootstrap.admin.enabled=false` não impede o security de criar o admin se `seedgrid.security.first-admin-user.email` estiver preenchido (só gera WARN).
+- Company default é sempre garantida (sem flag).
+- `seeAll` é global para membros da default company.

package/seedgridKB/SeedGrid/Extensions/notification/Configuracao.md

@@ -0,0 +1,141 @@
+---
+tags: [seedgrid, extension, notification, configuracao]
+fonte: java/seedgrid-quarkus-ext-notification
+branch: main
+commit: b989a6248a
+analisado-em: 2026-10-14
+---
+
+# Notification (Quarkus) — configuração
+
+Voltar: [[SeedGrid/Extensions/notification/Visao-geral|Visão geral do notification]] · [[SeedGrid/Extensions/notification/Exemplos|Exemplos]]
+
+## 1. Cabeçalho
+
+| Item | Valor |
+|---|---|
+| Prefixo | `seedgrid.notification` |
+| Classe de config | `java/seedgrid-quarkus-ext-notification/runtime/src/main/java/br/com/seedgrid/notification/config/NotificationConfig.java` → `NotificationConfig` |
+| Mecanismo | SmallRye `@ConfigMapping(prefix = "seedgrid.notification")` (sem `ConfigMappingBuildItem` no processor; descoberto pelo índice Jandex do runtime) + expressão `${seedgrid.notification.poll-interval:10s}` em `@Scheduled` |
+| Fase | Runtime |
+| Validação | `NotificationStartup#initialize` (StartupEvent, `@Priority(APPLICATION + 1)`) lança `IllegalArgumentException("Configuracao seedgrid.notification invalida")` se: `scope` em branco ou > 120 caracteres; `max-attempts` fora de 1–20; `batch-size` fora de 1–1000; `lease` ≤ 0; `retry-delay` ≤ 0. A aplicação **não sobe**. |
+
+Variáveis de ambiente: a regra MicroProfile se aplica sem ambiguidade (ex.: `SEEDGRID_NOTIFICATION_MAX_ATTEMPTS`). Não há env lida diretamente no código.
+
+## 2. Propriedades da extension
+
+### Ativação e escopo
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `seedgrid.notification.enabled` | `boolean` | `true`/`false` | `true` | Não | `false`: o subscriber ignora eventos (não cria marcador nem entregas — mas código de evento desconhecido ainda lança erro, pois `catalog.require` vem antes) e o dispatcher não envia. Startup/migrations continuam rodando. | Pausar publicação e envio | Sobrepõe `dispatch-enabled` | Runtime | Decl.: `NotificationConfig#enabled()`. Consumo: `NotificationSubscriber#observe`, `NotificationDispatcher#drain` |
+| `seedgrid.notification.dispatch-enabled` | `boolean` | `true`/`false` | `true` | Não | `false`: só o worker para; eventos continuam sendo enfileirados (fila preservada). | Pausar só o envio | Só vale com `enabled=true` | Runtime | Decl.: `NotificationConfig#dispatchEnabled()`. Consumo: `NotificationDispatcher#drain` |
+| `seedgrid.notification.scope` | `String` | não vazio, ≤ 120 caracteres | `platform` | Não | Namespace fixo da instalação: separa regras, deduplicação, histórico e workers de instalações que compartilham o banco. Nunca vem do navegador. **Não** é company/tenant. | Isolamento entre instalações | Mudar o valor "esconde" regras e histórico gravados com o scope anterior (Inferência: todas as consultas filtram por scope) | Runtime | Decl.: `NotificationConfig#scope()`. Consumo: `NotificationRules`, `NotificationSubscriber`, `NotificationQueue`, `NotificationResource#deliveries`, validação em `NotificationStartup` |
+| `seedgrid.notification.datasource-name` | `Optional<String>` | nome de datasource Agroal existente | — | Não | Se informado (após `trim`), as migrations usam esse datasource; se não resolver, o startup falha com `IllegalStateException`. Ausente: usa o datasource `master` se existir, senão o default. | Escolher onde rodar as migrations da notification | **Não** muda a persistence unit das entidades, que é decidida no build (`master` se houver datasource com esse nome, senão `<default>`) — ver `NotificationProcessor#registerEntities` (Inferência sobre o risco de inconsistência) | Runtime | Decl.: `NotificationConfig#datasourceName()`. Consumo: `NotificationStartup#resolveDataSource` |
+
+### Worker / entrega
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `seedgrid.notification.poll-interval` | `String` (expressão `every` do Quarkus Scheduler) | duração do scheduler (`10s`, `PT10S`...) | `10s` | Não | Intervalo do `NotificationDispatcher#drain` (`concurrentExecution = SKIP`). | Frequência do worker | Cada execução processa até `batch-size` claims | Runtime (resolvido pelo scheduler na subida) | Decl./consumo: `NotificationDispatcher#drain` — `@Scheduled(every = "${seedgrid.notification.poll-interval:10s}")`. Não está em `NotificationConfig`. |
+| `seedgrid.notification.batch-size` | `int` | 1–1000 | `20` | Não | Máximo de claims por execução do worker. | Vazão | — | Runtime | Decl.: `NotificationConfig#batchSize()`. Consumo: `NotificationDispatcher#drain`; validação em `NotificationStartup` |
+| `seedgrid.notification.max-attempts` | `int` | 1–20 | `5` | Não | Tentativas por entrega; ao atingir, status `FAILED` (`ATTEMPTS_EXHAUSTED` no claim ou `TRANSPORT_FAILED` na última falha). | Limite de retry | Com `retry-delay` define a janela total de retry | Runtime | Decl.: `NotificationConfig#maxAttempts()`. Consumo: `NotificationQueue#claim`, `#complete` |
+| `seedgrid.notification.retry-delay` | `Duration` | > 0 | `PT30S` | Não | Base do backoff exponencial: próxima tentativa = agora + `retry-delay × 2^min(tentativas-1, 10)`. | Espaçamento entre tentativas | — | Runtime | Decl.: `NotificationConfig#retryDelay()`. Consumo: `NotificationQueue#complete` |
+| `seedgrid.notification.lease` | `Duration` | > 0 | `PT5M` | Não | Prazo de posse de uma entrega em `SENDING`; depois dele outro worker pode retomá-la. | Recuperação após queda do worker | Deve exceder o timeout máximo do transporte (SMTP/WhatsApp) com margem, senão há risco de envio duplicado (`docs/ARCHITECTURE.md`) | Runtime | Decl.: `NotificationConfig#lease()`. Consumo: `NotificationQueue#claim` |
+
+Total: **9 propriedades públicas** (8 em `NotificationConfig` + `poll-interval`).
+
+## 3. Propriedades de frameworks/bibliotecas usadas pela extension
+
+| Propriedade | Por quê | Fonte |
+|---|---|---|
+| `quarkus.mailer.security.*` (`from`, `host`, `port`, `mock`, `timeout`, `start-tls`, credenciais/TLS) | O transporte de e-mail injeta `@MailerName("security") Mailer`. Produção precisa de `mock=false` e timeouts finitos. | `NotificationTransport`; README; `docs/ARCHITECTURE.md` |
+| `seedgrid.whatsapp.api` e a configuração do provider (URL/credencial) | Envio WhatsApp via `WhatsAppApi` da extensão WhatsApp; a instância (`whatsappChannelId`) vem da regra. Ver [[SeedGrid/Extensions/whatsapp/Configuracao|configuração do whatsapp]]. | README; `integration-tests/.../application.properties` |
+| `quarkus.datasource.*` / `quarkus.datasource."master".*` | Datasource das migrations e da PU (`master` preferido). | `NotificationStartup`, `NotificationProcessor` |
+| `quarkus.scheduler.*` | O worker é um `@Scheduled`; nos ITs `quarkus.scheduler.start-mode=halted`. | `NotificationDispatcher` |
+
+A extension não registra defaults de framework (sem `microprofile-config.properties`).
+
+## 4. Propriedades usadas só em testes
+
+`integration-tests/src/main/resources/application.properties` e `NotificationContainers`:
+
+| Propriedade | Valor/observação |
+|---|---|
+| `quarkus.datasource.db-kind` | `postgresql` |
+| `quarkus.datasource.devservices.enabled` | `false` (containers próprios) |
+| `quarkus.hibernate-orm.schema-management.strategy` | `none` |
+| `quarkus.mailer.security.from` / `.mock` / `.start-tls` / `.timeout` | `notification@example.invalid`, `false`, `DISABLED`, `5S` |
+| `quarkus.mailer.security.host` / `.port` | injetados pelo `NotificationContainers` (MailHog) |
+| `quarkus.datasource.jdbc.url` / `.username` / `.password` | injetados pelo `NotificationContainers` |
+| `quarkus.scheduler.start-mode` | `halted` |
+| `quarkus.http.test-port` | `0` |
+| `seedgrid.notification.scope` | `notification-it` |
+| `seedgrid.notification.max-attempts` | `2` |
+| `seedgrid.whatsapp.api` | `evolution` |
+| 🔒 `seedgrid.whatsapp.evolution.api-key` | `<SEGREDO:evolution-api-key>` (valor local de teste não copiado) |
+| `quarkus.rest-client.evolution.url` / `.connect-timeout` / `.read-timeout` | URL do servidor simulado; `2000` / `2000` |
+| `test.mail.url` | lida por `@ConfigProperty` em `NotificationIT` (URL do MailHog) |
+
+## 5. Aliases, obsoletas, renomeações
+
+- Nenhum alias. O CHANGELOG `2026.10.13` registra que a escolha da persistence unit passou a ser feita no build "sem chave de configuração que possa divergir".
+- A migration antiga `V950` foi substituída por `V1000` antes da adoção (README).
+
+## 6. Configuração mínima
+
+Nada em `seedgrid.notification.*` é obrigatório. É preciso configurar o transporte:
+
+```properties
+quarkus.mailer.security.from=<REMETENTE>
+quarkus.mailer.security.host=<SMTP-HOST>
+quarkus.mailer.security.port=<SMTP-PORTA>
+quarkus.mailer.security.mock=false
+# WhatsApp (opcional): ver configuração do seedgrid-whatsapp
+seedgrid.whatsapp.api=<evolution|...>
+```
+
+## 7. Configuração completa comentada
+
+```properties
+# Namespace fixo da instalação (padrão: platform; não vazio, até 120 caracteres)
+seedgrid.notification.scope=platform
+# Liga enfileiramento e envio (padrão: true)
+seedgrid.notification.enabled=true
+# Liga só o worker de envio (padrão: true)
+seedgrid.notification.dispatch-enabled=true
+# Datasource das migrations (padrão: master se existir, senão o default)
+#seedgrid.notification.datasource-name=master
+# Intervalo do worker (padrão: 10s)
+seedgrid.notification.poll-interval=10s
+# Claims por execução (padrão: 20; 1-1000)
+seedgrid.notification.batch-size=20
+# Tentativas por entrega (padrão: 5; 1-20)
+seedgrid.notification.max-attempts=5
+# Base do backoff exponencial (padrão: PT30S; > 0)
+seedgrid.notification.retry-delay=PT30S
+# Posse de uma entrega pelo worker (padrão: PT5M; > 0; maior que o timeout do transporte)
+seedgrid.notification.lease=PT5M
+
+# Transporte de e-mail (mailer nomeado do security)
+quarkus.mailer.security.from=<REMETENTE>
+quarkus.mailer.security.host=<SMTP-HOST>
+quarkus.mailer.security.port=<SMTP-PORTA>
+quarkus.mailer.security.username=<USUARIO-SMTP>
+quarkus.mailer.security.password=<SEGREDO:smtp-password>
+quarkus.mailer.security.mock=false
+quarkus.mailer.security.timeout=30S
+```
+
+## 8. Receitas
+
+- **Manutenção do SMTP sem perder avisos**: `seedgrid.notification.dispatch-enabled=false` — a fila cresce; ao religar, o worker drena.
+- **Desligar notificações totalmente**: `seedgrid.notification.enabled=false` (eventos publicados nesse período não são enfileirados).
+- **Duas instalações no mesmo banco**: um `scope` distinto em cada uma.
+- **Transporte lento**: aumente `lease` acima do timeout do transporte; ajuste `retry-delay`/`max-attempts` (com padrão 5 tentativas e 30 s, as esperas são 30 s, 60 s, 120 s, 240 s).
+- **Host multi-datasource (subdomain-tenancy)**: a extension usa o datasource `master` automaticamente; `datasource-name` só se precisar de outro para as migrations.
+
+## 9. Dúvidas e lacunas
+
+- `poll-interval` aceita o formato de `every` do Quarkus Scheduler; se valores como `off`/`disabled` desligam o worker depende da versão do Quarkus (Não confirmado neste repositório).
+- Possível inconsistência entre `datasource-name` (migrations) e a PU escolhida no build (entidades) — Inferência, não testada.

package/seedgridKB/SeedGrid/Extensions/notification/Enums.md

@@ -0,0 +1,52 @@
+---
+tags: [seedgrid, extension, notification, enum]
+fonte: java/seedgrid-quarkus-ext-notification
+branch: main
+commit: b989a6248a
+analisado-em: 2026-10-14
+---
+
+# Notification (Quarkus) — enums
+
+Voltar: [[SeedGrid/Extensions/notification/Visao-geral|Visão geral do notification]] · [[SeedGrid/Extensions/notification/Configuracao|Configuração]]
+
+## Índice
+
+| Enum | Pacote/arquivo | Usado em | Público? |
+|---|---|---|---|
+| [[#Channel]] | `br.com.seedgrid.notification.config` — `runtime/src/main/java/br/com/seedgrid/notification/config/Channel.java` | `NotificationRule#channels`, `ConditionalRecipient#channel`, corpo do `PUT /admin/notifications/events/{code}`, resposta do `GET /admin/notifications/events`, coluna `sg_notification_delivery.channel` | Sim |
+
+O módulo `api` (`seedgrid-notification-api`) não define enums.
+
+## Channel
+
+FQN: `br.com.seedgrid.notification.config.Channel`.
+
+| Valor | Significado | Efeito / onde é tratado | Observações |
+|---|---|---|---|
+| `EMAIL` | Entrega por e-mail | `NotificationSubscriber` enfileira para `rule.emails()` (+ condicionais do canal); `NotificationTransport` envia com `Mailer` nomeado `security`; `RuleValidator` normaliza endereços (trim, minúsculas, validação) | Confirmado |
+| `WHATSAPP` | Entrega por WhatsApp | Enfileira para `rule.phones()` (+ condicionais), com `rule.whatsappChannelId()`; `NotificationTransport` usa `WhatsAppApi#sendTextMessage`; exige telefone E.164 e instância; resposta sem `messageId` é falha | Confirmado |
+
+- Sem campos nem métodos.
+- **JSON**: nome da constante, sensível a maiúsculas (padrão Jackson): `"channels": ["EMAIL","WHATSAPP"]`; `ConditionalRecipient.channel` idem (nulo → `IllegalArgumentException` "Canal do destinatario condicional obrigatorio", devolvido como `400`). `GET /admin/notifications/events` devolve `channels: Channel.values()` (lista dos canais suportados, **não** atesta credenciais válidas).
+- **Persistência**: a regra é gravada como JSON em `sg_notification_rule.rule_json`. A entrega grava `channel.name()` em `sg_notification_delivery.channel varchar(16)` com `CHECK (channel in ('EMAIL','WHATSAPP'))` (V1000) — **coerente** com as constantes. Em `NotificationTransport` o canal volta como string: valores fora de `EMAIL`/`WHATSAPP` lançam `IllegalStateException("Canal desconhecido")` (inalcançável com o CHECK).
+- Adicionar uma constante exige: novo ramo no `NotificationSubscriber` (não há laço genérico), `RuleValidator` (a lista usa `c == Channel.EMAIL ? emails : phones`, tratando tudo que não é EMAIL como telefone), `NotificationTransport` e o CHECK da tabela.
+- Usado em: sem propriedade de config; ver endpoints em [[SeedGrid/Extensions/notification/Visao-geral|Visão geral]].
+
+## Status de entrega (não é enum Java)
+
+`sg_notification_delivery.status` é `String` com `CHECK (status in ('PENDING','SENDING','SENT','FAILED'))` e constantes literais em `NotificationSubscriber`, `NotificationQueue` e `NotificationDeliveryRepository`; aparece em `GET /admin/notifications/deliveries`. Não existe enum Java para esses valores.
+
+```mermaid
+stateDiagram-v2
+    [*] --> PENDING: NotificationSubscriber (enqueue)
+    PENDING --> SENDING: NotificationQueue.claim (attempts+1, lease)
+    SENDING --> SENT: complete(success)
+    SENDING --> PENDING: complete(falha) e attempts < max-attempts (backoff)
+    SENDING --> FAILED: complete(falha) e attempts >= max-attempts
+    PENDING --> FAILED: claim com attempts >= max-attempts (ATTEMPTS_EXHAUSTED)
+```
+
+## Internos
+
+Nenhum.

package/seedgridKB/SeedGrid/Extensions/notification/Exemplos.md

@@ -0,0 +1,141 @@
+---
+tags: [seedgrid, extension, notification, exemplos]
+fonte: java/seedgrid-quarkus-ext-notification
+branch: main
+commit: b989a6248a
+analisado-em: 2026-10-14
+---
+
+# Notification (Quarkus) — exemplos
+
+Voltar: [[SeedGrid/Extensions/notification/Visao-geral|Visão geral do notification]] · [[SeedGrid/Extensions/notification/Configuracao|Configuração]]
+
+## 1. Dependências
+
+Fonte: `README.md` / poms.
+
+```xml
+<!-- Extensão produtora: só o contrato -->
+<dependency>
+    <groupId>br.com.seedgrid</groupId>
+    <artifactId>seedgrid-notification-api</artifactId>
+    <version>2026.10.15</version>
+</dependency>
+
+<!-- Produto que quer catálogo, API administrativa e entrega -->
+<dependency>
+    <groupId>br.com.seedgrid</groupId>
+    <artifactId>seedgrid-notification</artifactId>
+    <version>2026.10.15</version>
+</dependency>
+```
+
+## 2. Declarar eventos (extensão produtora)
+
+Fonte: `README.md`; assinatura de `EventDefinition(code, group, label, description, variables, subjectTemplate, bodyTemplate)`.
+
+```java
+import br.com.seedgrid.notification.api.EventDefinition;
+import br.com.seedgrid.notification.api.NotificationCatalogContributor;
+import jakarta.enterprise.context.ApplicationScoped;
+import java.util.Collection;
+import java.util.List;
+import java.util.Set;
+
+@ApplicationScoped
+public class PricingNotifications implements NotificationCatalogContributor {
+    @Override
+    public Collection<EventDefinition> events() {
+        return List.of(new EventDefinition(
+            "ai-pricing.approval-pending", "Preços de IA", "Aprovação pendente",
+            "Novos preços aguardam revisão", Set.of("quantity"),
+            "Preços aguardando aprovação", "Há {quantity} preços para revisar."));
+    }
+}
+```
+
+## 3. Publicar dentro da transação de negócio
+
+Fonte: `README.md`; `NotificationPublisher#publish(NotificationEvent)`; `NotificationEvent(id, code, variables)`.
+
+```java
+import br.com.seedgrid.notification.api.NotificationEvent;
+import br.com.seedgrid.notification.api.NotificationPublisher;
+
+@Inject NotificationPublisher notifications;
+
+@Transactional
+public void proporPrecos(...) {
+    // ... grava a proposta ...
+    // id estável da ocorrência (não gerar UUID novo a cada retry)
+    notifications.publish(new NotificationEvent(
+        proposalPublicId, "ai-pricing.approval-pending", Map.of("quantity", "3")));
+}
+```
+
+Evento operacional embutido (publicável por qualquer host): código `platform.email-delivery-failed`, variáveis `recipient`, `subject`, `cause`, `accumulated` (`OperationalNotificationCatalog`).
+
+## 4. Configurar uma regra (admin)
+
+Fonte: `docs/API.md`, `README.md`.
+
+```http
+PUT /admin/notifications/events/ai-pricing.approval-pending
+Content-Type: application/json
+Authorization: Bearer <JWT-COM-NOTIFICATION_UPDATE>
+
+{
+  "enabled": true,
+  "channels": ["EMAIL", "WHATSAPP"],
+  "emails": ["financeiro@example.com"],
+  "phones": ["+5511999999999"],
+  "whatsappChannelId": "administrativo",
+  "conditionalRecipients": [
+    {"channel": "WHATSAPP", "address": "+5511911111111", "attribute": "partnerPublicId", "value": "8f1c..."},
+    {"channel": "WHATSAPP", "address": "+5511922222222", "attribute": "partnerPublicId", "value": null}
+  ]
+}
+```
+
+E-mails são normalizados (trim, minúsculas, dedup); telefones em E.164; até 50 destinatários por canal (incondicionais + condicionais); WhatsApp exige `whatsappChannelId`.
+
+## 5. Destinatários condicionais: enricher do host
+
+Fonte: `README.md`; interface `NotificationEventEnricher` e `RoutingAttribute`.
+
+```java
+import br.com.seedgrid.notification.api.NotificationEvent;
+import br.com.seedgrid.notification.api.NotificationEventEnricher;
+import br.com.seedgrid.notification.api.RoutingAttribute;
+
+@ApplicationScoped
+public class PartnerRouting implements NotificationEventEnricher {
+    @Override
+    public Map<String, String> attributes(NotificationEvent event) {
+        String account = event.variables().get("accountPublicId");
+        String partner = account == null ? null : partners.partnerOf(account);
+        return partner == null ? Map.of() : Map.of("partnerPublicId", partner);
+    }
+
+    @Override
+    public List<RoutingAttribute> describe() {
+        return List.of(new RoutingAttribute("partnerPublicId", "Parceiro",
+                partners.list().stream()
+                        .map(p -> new RoutingAttribute.Option(p.publicId(), p.name())).toList()));
+    }
+}
+```
+
+Não anote o enricher com `@Transactional` (uma exceção marcaria a transação de negócio para rollback); exceções do enricher são logadas e ignoradas.
+
+## 6. Consultar histórico
+
+```http
+GET /admin/notifications/deliveries?page=0&size=30
+```
+
+Resposta: `{ items: [{id, eventCode, channel, status, attempts, createdAt, sentAt, lastError}], totalRecords, page, size }`.
+
+## 7. Configuração
+
+Ver [[SeedGrid/Extensions/notification/Configuracao|Configuração]] (mailer `quarkus.mailer.security.*`, `seedgrid.notification.*`).