@seedgrid/ai-toolkit 0.0.0-stage → 0.3.0

package/seedgridKB/SeedGrid/Extensions/subdomain-tenancy/Exemplos.md

@@ -0,0 +1,205 @@
+---
+tags: [seedgrid, extension, subdomain-tenancy, exemplos]
+fonte: java/seedgrid-quarkus-ext-subdomain-tenancy, java/examples/seedgrid-subdomain-tenancy-example
+branch: main
+commit: fe62530a29
+analisado-em: 2026-10-14
+---
+
+# subdomain-tenancy — Exemplos (Quarkus)
+
+Visão geral: [[SeedGrid/Extensions/subdomain-tenancy/Visao-geral|Visão geral do subdomain-tenancy]] · Catálogo de propriedades: [[SeedGrid/Extensions/subdomain-tenancy/Configuracao|Configuração do subdomain-tenancy]] · [[SeedGrid/Extensions/subdomain-tenancy/Rust|Porte Rust]]
+
+Fontes: app de exemplo `java/examples/seedgrid-subdomain-tenancy-example` (repositório git próprio, commit `cd83edd` — fora da tabela de commits da análise), `README.md` da extension e o código do runtime (commit `fe62530a29`). Outro consumidor no monorepo: `java/seedgrid-test-multitenancy`.
+
+## 1. Dependência
+
+```xml
+<dependency>
+    <groupId>br.com.seedgrid</groupId>
+    <artifactId>seedgrid-subdomain-tenancy</artifactId>
+    <version>2026.10.14-1</version>
+</dependency>
+```
+
+O exemplo usa a propriedade `seedgrid.subdomain-tenancy.version` (`2026.10.13` no pom dele) e importa o parent da extension como BOM para não pinar commons/security/billing… à mão (comentário no `pom.xml` do exemplo).
+
+## 2. Configuração do host (trecho real do exemplo)
+
+`java/examples/seedgrid-subdomain-tenancy-example/src/main/resources/application.properties` — segredos substituídos por placeholders e só com as chaves que têm efeito:
+
+```properties
+# Entidades do app somadas às da lib (reaproveita as chaves da extension)
+quarkus.hibernate-orm.packages=${seedgrid.subdomain-tenancy.tenant.entity-packages},br.com.seedgrid.security.entities,br.com.seedgrid.backup.entities,br.com.seedgrid.apikeys.entities
+quarkus.hibernate-orm.master.packages=${seedgrid.subdomain-tenancy.master.entity-packages},br.com.seedgrid.subdomaintenancy.entities
+
+seedgrid.subdomain-tenancy.product-prefix=${PRODUCT_PREFIX:kb}
+
+# Ponte do datasource dos TENANTS com env vars curtas (criadas pelo exemplo, não pela lib)
+seedgrid.subdomain-tenancy.tenant.datasource.jdbc.url=${SEEDGRID_SUBDOMAIN_TENANCY_TENANT_DB_URL:jdbc:postgresql://localhost:5439}
+seedgrid.subdomain-tenancy.tenant.datasource.username=${SEEDGRID_SUBDOMAIN_TENANCY_TENANT_DB_USERNAME:postgres}
+seedgrid.subdomain-tenancy.tenant.datasource.password=<SEGREDO:tenant-db-password>
+
+# Bootstrap de startup do security desligado (pressupõe banco único)
+seedgrid.security.bootstrap.enabled=false
+```
+
+Observação (**Confirmado** no código da extension): `domain-suffix`, `master.datasource.*`, `mailer.*`, `admin-user.*`, `cleanup.*` vêm do `microprofile-config.properties` da extension e são ajustadas por env vars `SEEDGRID_SUBDOMAIN_TENANCY_*` (lista em [[SeedGrid/Extensions/subdomain-tenancy/Configuracao|Configuração]]).
+
+## 3. Entidades e repositórios: master × tenant
+
+PU default = banco do tenant (resolvido pelo host). PU `master` = banco global. Exemplo real (`repository/PaymentPlanRepository.java`):
+
+```java
+@ApplicationScoped
+@PersistenceUnit("master")
+public class PaymentPlanRepository implements PanacheRepository<PaymentPlan> {
+
+    public List<PaymentPlan> findByDescription(String description) {
+        return list("LOWER(description) LIKE LOWER(?1)", "%" + description + "%");
+    }
+}
+```
+
+O `PersonRepository` (entidade `entity/tenant/Person`) não usa `@PersistenceUnit` e, portanto, opera no banco do tenant corrente.
+
+## 4. Recurso visível só em tenants (`@TenantOnly`)
+
+Trecho real de `resource/PersonResource.java`:
+
+```java
+@Path("/api/persons")
+@Produces(MediaType.APPLICATION_JSON)
+@Consumes(MediaType.APPLICATION_JSON)
+@Tag(name = "Persons", description = "Person management (TENANT)")
+@Tag(name = "tenant-only", description = "Endpoints disponíveis apenas no contexto de tenant")
+@SecurityRequirement(name = "bearerAuth")
+@TenantOnly
+@Blocking
+public class PersonResource {
+
+    final PersonService service;
+    public PersonResource(PersonService service) {
+        this.service = service;
+    }
+
+    @GET
+    @Operation(summary = "List all persons")
+    @Tag(name = "tenant-only")
+    public List<PersonDTO> listAll() {
+        return service.findAll();
+    }
+}
+```
+
+`@TenantOnly`/`@MasterOnly` só afetam o spec servido em `GET /public/tenant-openapi`; não bloqueiam acesso. O exemplo repete `@Tag(name = "tenant-only")` nos métodos — o filtro (`TenantOpenApiController#copyIfAllowed`) trabalha por operação, então a repetição garante que a tag chegue em cada operação do spec (**Inferência**: não foi verificado se a meta-anotação na classe é propagada pelo SmallRye OpenAPI).
+
+## 5. Sobrescrevendo uma SPI (PasswordEncoder)
+
+Exemplo real (`multitenancy/CustomPasswordEncoder.java`). Um bean normal vence o `BCryptPasswordEncoder` `@DefaultBean` da extension:
+
+```java
+@ApplicationScoped
+public class CustomPasswordEncoder implements PasswordEncoder {
+
+    private static final int SALT_ROUNDS = 12;
+
+    @Override
+    public String encode(String plainPassword) {
+        if (plainPassword == null) {
+            throw new IllegalArgumentException("Password cannot be null");
+        }
+        return BCrypt.hashpw(plainPassword, BCrypt.gensalt(SALT_ROUNDS));
+    }
+}
+```
+
+## 6. Canal próprio para o OTP (SubdomainTenancyNotificationService)
+
+Assinaturas reais: `void sendValidationNotification(TenantValidationNotification notification)`; o record tem `recipient`, `recipientName`, `tradeName`, `validationCode`, `expiryMinutes`, `subject`, `htmlContent`, `channelHint` (o `TenantService` envia `channelHint="email"`). Esboço (o corpo é do host):
+
+```java
+@ApplicationScoped
+public class WhatsAppValidationNotifier implements SubdomainTenancyNotificationService {
+
+    @Override
+    public void sendValidationNotification(TenantValidationNotification n) {
+        // enviar n.validationCode() para n.recipient(), válido por n.expiryMinutes() minutos
+    }
+}
+```
+
+Por ser bean normal, substitui o `MailerNotificationService` (`@DefaultBean`). Se `sendValidationNotification` lançar `RuntimeException`, o `TenantService` não desfaz o cadastro: a resposta do signup vem com `emailDelivered=false`.
+
+Para só trocar o HTML do e-mail padrão, coloque um template Qute em `src/main/resources/templates/subdomain-tenancy/confirmation.html` (ou `subdomain-tenancy/html/confirmation.html`) — o `DefaultTemplateSubdomainTenancyProvider` tenta esses caminhos antes do template embutido. Os dados passados ao template não foram detalhados aqui (ver `spi/impl/DefaultTemplateSubdomainTenancyProvider`).
+
+## 7. Migrations do host
+
+Estrutura real do exemplo:
+
+```text
+src/main/resources/db/migration/
+├── master/   V2000__create_payment_plans_table.sql, V2001__seed_payment_plans_permissions.sql, V2002__create_role_teste_apikey.sql
+└── tenant/   V1__create_persons_table.sql
+```
+
+`master/` roda no boot (history `flyway_schema_history_master`); `tenant/` roda no provisionamento e nas migrações por tenant (history `flyway_schema_history_tenant`). Para pastas extras use `seedgrid.subdomain-tenancy.{master,tenant}.migrations.location.additional` com versões que não colidam com a base.
+
+## 8. Ciclo de vida de um tenant (HTTP)
+
+Body conforme `TenantSignupRequest` (`subdomain` `^[a-z0-9_]{5,50}$`, `cnpj` com `@CNPJ`, `rootEmail` `@Email`, representante legal com nome/sobrenome/telefone obrigatórios). Fonte: README da extension, conferido com o DTO.
+
+```bash
+# 1) signup (público, 100/min por IP)
+curl -X POST https://crm.example.com/public/tenants \
+  -H "Content-Type: application/json" \
+  -d '{
+    "subdomain": "clientea",
+    "cnpj": "<cnpj>",
+    "corporateName": "Cliente A Ltda",
+    "tradeName": "Cliente A",
+    "rootEmail": "admin@clientea.example",
+    "plainRootPassword": "<SEGREDO:senha-root>",
+    "address": { "street": "Rua X", "number": "100", "city": "São Paulo", "state": "SP", "postalCode": "01000-000", "district": "Centro" },
+    "legalRepresentative": { "firstName": "Maria", "lastName": "Silva", "cpf": "<cpf>", "birthDate": "1990-01-01", "phone": "11999990000" }
+  }'
+# -> 201 {"status":"CREATED","emailDelivered":true,"result":"Email de confirmacao enviado para ..."}
+
+# 2) validar OTP (aceita 123456 ou 123-456) -> cria banco crm_clientea, migra, cria root, conta de billing
+curl -X POST https://crm.example.com/public/tenants/validate-email \
+  -H "Content-Type: application/json" -d '{"subdomain":"clientea","code":"123-456"}'
+
+# 3) reenviar OTP (5/h por IP)
+curl -X POST "https://crm.example.com/public/tenants/resend-email?subdomain=clientea"
+
+# 4) a partir daqui, o tenant é resolvido pelo host
+curl https://clientea.crm.example.com/api/persons -H "Authorization: Bearer <token>"
+```
+
+> Atenção: com `domain-suffix=crm.example.com`, um subdomínio com `_` passa no signup mas não é extraído do host (o extractor aceita só `[a-z0-9-]`). Prefira nomes sem `_`.
+
+## 9. Operação (contexto master)
+
+```bash
+# Forçar migração de um tenant
+curl -X POST "https://crm.example.com/internal/migrations/tenants/clientea/trigger?force=true" -H "Authorization: Bearer <token-master>"
+# Estado da migração
+curl https://crm.example.com/internal/migrations/tenants/clientea/status -H "Authorization: Bearer <token-master>"
+# Health do tenant (status HTTP derivado do código: OK, TENANT_INACTIVE, DATABASE_UNREACHABLE, MIGRATION_*...)
+curl https://crm.example.com/internal/health/tenants/clientea -H "Authorization: Bearer <token-master>"
+```
+
+Chamados a partir de um host de tenant, esses endpoints respondem `403 {"error":"master_scope_required"}`. Durante uma migração disparada pelo login, `POST /auth/login` no tenant recebe `503` com `Retry-After: 15` e `{"error":"tenant_migration_in_progress", ...}`.
+
+## 10. Lendo o tenant corrente no código do host
+
+`TenantContext` é `@RequestScoped` e preenchido pelo `TenantResolutionFilter`:
+
+```java
+@Inject
+TenantContext tenantContext;
+
+String tenant = tenantContext.getCurrentTenant(); // "master" quando o host não traz subdomínio
+```
+
+O `QuarkusTenantResolver` dá prioridade ao valor já gravado no `TenantContext`; portanto `setCurrentTenant("outro")` dentro da request muda o banco usado pelas **próximas** sessões Hibernate da PU default (**Inferência** a partir de `QuarkusTenantResolver#resolveTenantId`; não há exemplo/teste do host fazendo isso). `TenantScopedExecutor#call(Supplier<T>)` apenas abre uma transação `REQUIRES_NEW`.

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

@@ -0,0 +1,161 @@
+---
+tags: [seedgrid, extension, subdomain-tenancy, rust]
+fonte: rust/seedgrid-rust-crate-subdomain-tenancy
+branch: main
+commit: be738a2d1e
+analisado-em: 2026-10-14
+---
+
+# `seedgrid-rust-crate-subdomain-tenancy` — porte Rust
+
+Lado Java: [[SeedGrid/Extensions/subdomain-tenancy/Visao-geral|Visão geral do subdomain-tenancy (Quarkus)]] · [[SeedGrid/Extensions/subdomain-tenancy/Configuracao|Configuração Java]]
+Configuração deste crate: [[SeedGrid/Extensions/subdomain-tenancy/Configuracao-Rust|Configuração Rust do subdomain-tenancy]]
+
+## Objetivo
+
+Porte da extensão `seedgrid-quarkus-ext-subdomain-tenancy` (antiga *multitenancy*): multitenancy **por subdomínio**, modelo **SILO** (um banco Postgres por tenant). Principais capacidades (Confirmado em `README.md`, `src/lib.rs`, `src/orchestrator.rs`):
+
+- Resolução do tenant pelo host `{tenant}.{domain-suffix}` (prioriza `X-Forwarded-Host`; fallback `master`).
+- Registro de tenants no banco **master** (`tenants`, `tenant_validation_tokens`, `tenant_migration_state`).
+- Signup público de tenant com OTP por e-mail, validação e **provisionamento** (`CREATE DATABASE` + migrations security/tenant/audit/backup/apikeys + admin root).
+- **Coordenação de migrations por tenant** (lock com lease/fencing token, heartbeat, concorrência limitada) e **gate de login** enquanto o tenant migra.
+- Pools por tenant com LRU (`max-active-datasources`) e circuit breaker; middleware que devolve 404 para tenant inexistente/inativo.
+- Schedulers de cleanup de tenants não validados e de trial.
+- Orquestrador `assemble_all`: monta tenancy + security + billing + audit + backup, injeta os hooks de tenancy no security e devolve `Router` e OpenAPI agregados.
+- PII at-rest do `Tenant` via `CryptoProvider` global do `seedgrid-privacy`; auditoria de criação de tenant.
+
+## Coordenadas
+
+| Item | Valor |
+|---|---|
+| Diretório / pacote / lib | `rust/seedgrid-rust-crate-subdomain-tenancy` / `seedgrid-rust-crate-subdomain-tenancy` / `seedgrid_subdomain_tenancy` |
+| Versão | `version.workspace = true` → `2026.10.14` |
+| Features | `default = ["postgres"]`, `postgres = ["dep:sqlx"]` |
+| Reexporta | `seedgrid_apikeys`, `seedgrid_audit`, `seedgrid_backup`, `seedgrid_billing`, `seedgrid_cache`, `seedgrid_privacy`, `seedgrid_resilience`, `seedgrid_security` (usa também `seedgrid_runtime::events`) |
+
+## API pública (principais)
+
+| Símbolo | Papel |
+|---|---|
+| `SubdomainTenancyConfig` (+ `from_env`, `apply_datasource_env`) | ver [[SeedGrid/Extensions/subdomain-tenancy/Configuracao-Rust\|Configuração Rust]] |
+| `assemble_all(Arc<SubdomainTenancyConfig>, Option<PgPool>, PlatformOverrides)` → `AssembledPlatform { tenancy, security, billing, audit_scoped, backup_scoped, router, openapi }` | "CDI" do host |
+| `TenancyPlatform::assemble(...)` → `AssembledTenancy` (`provisioning_router()`, `shutdown_schedulers()`), `HostOverrides` | montagem só da tenancy |
+| `TenantService`, `TenantProvisioner`, `TenantProvisioningService`, `TenantRepository`, `TenantValidationTokenRepository` | signup/validação/provisionamento |
+| `TenantMigrationCoordinator` (em `migration`), `PgTenantMigrationStore`, `DefaultTenantSchemaMigrator`, `TenantBusinessSchemaMigrator` | migração por tenant |
+| `TenantPoolProvider`, `TenantConnectionResolver`, `TenantScoped`/`TenantStateFactory`, `TenantContext` | roteamento de pools/estado por tenant |
+| `tenant_migration_gate` / `TenantMigrationGateState`, `tenant_middleware::*` | middlewares |
+| `TenantJwtTokenCustomizer`, `TenantScopeResolver` (`spi`) | hooks para o security |
+| `TenantHealthService`, `TenantHealthReport` | health por tenant |
+| `extract_tenant_from_host`, `resolve_host_header`, `resolve_tenant` | resolução |
+| `spawn_backup_scheduler`, `schedulers::*` | jobs |
+| `migrate(&PgPool)` / `migrate_startup(...)` / `MIGRATOR` | migrations do master `0100..0109` |
+| `router(SubdomainTenancyState)`, `provisioning_router(TenantProvisioningApiState)`, `openapi()` | rotas |
+
+## Endpoints (Confirmado em `src/routes.rs` e `src/provisioning_routes.rs`)
+
+| Método | Path |
+|---|---|
+| POST | `/public/tenants` (signup) |
+| POST | `/public/tenants/validate-email` |
+| POST | `/public/tenants/resend-email` |
+| GET | `/internal/health/tenants/{tenantId}` |
+| POST | `/internal/migrations/tenants/{tenantId}/trigger` |
+| GET | `/internal/migrations/tenants/{tenantId}/status` |
+| POST | `/internal/tenants/{tenantId}/provision` (`provisioning_router`) |
+| GET | `/tenants`, `/tenants/{subdomain}` (`provisioning_router`; resumo do registro master) |
+
+Rotas restritas ao contexto master respondem 403 `master_scope_required` quando chamadas sob outro tenant (`src/routes.rs`).
+
+O `router` agregado do `assemble_all` inclui ainda security, billing, `/audit-logs` e `/exports` (backup), com middleware de resolução de tenant, gate de migração e auth admin via security.
+
+## Exemplos
+
+Montagem completa (Inferência a partir das assinaturas de `assemble_all` e `SubdomainTenancyConfig`; não há exemplo no repositório usando `assemble_all`):
+
+```rust
+use std::sync::Arc;
+use seedgrid_subdomain_tenancy::{assemble_all, PlatformOverrides, SubdomainTenancyConfig};
+
+async fn boot(master_url: &str) -> Result<(), Box<dyn std::error::Error>> {
+    let mut cfg = SubdomainTenancyConfig::from_env();
+    cfg.apply_datasource_env(Some(master_url));
+    let master_pool = sqlx::PgPool::connect(master_url).await?;
+    let assembled = assemble_all(Arc::new(cfg), Some(master_pool), PlatformOverrides::default())
+        .await
+        .map_err(|e| e.to_string())?;
+    let app = axum::Router::new().nest("/api/v1", assembled.router);
+    let _ = app;
+    Ok(())
+}
+```
+
+Exemplo executável (Confirmado): `rust/examples/seedgrid-subdomain-tenancy-example/src/main.rs` — monta à mão `TenantPoolProvider`, `DefaultTenantSchemaMigrator`, `TenantMigrationCoordinator`, `TenantProvisioningService` e `TenantService` (trial 14 dias, OTP 10 min, `NoopPasswordEncoder` só para dev) e percorre signup → validação → provisionamento. Usa envs próprias do exemplo (`DATABASE_URL`, `TENANT_URL_PATTERN`, `TENANT_DB_USER`, `TENANT_DB_PASSWORD`, `EXAMPLE_TENANT`).
+
+## Migrations (master)
+
+`0100_create_tenants_table.sql` … `0109_privacy_search_hashes.sql` (10 arquivos): tenants, root user, trial, snapshot de usuário, `tenant_migration_state` (+ fencing token), índices, `tenant_validation_tokens` (+ base entity), hashes de privacidade. Os bancos de tenant recebem as migrations de security/audit/backup/apikeys + negócio via `DefaultTenantSchemaMigrator`.
+
+## Testes
+
+Unitários em `src/**` (config, resolver, gate, service...) e `tests/db_it.rs` (Testcontainers). **Não executados** nesta análise.
+
+## Notas de comportamento
+
+- O crate lê `SEEDGRID_MULTITENANCY_*` (o módulo Java usa `SEEDGRID_SUBDOMAIN_TENANCY_*`) — ver [[SeedGrid/Extensions/subdomain-tenancy/Configuracao-Rust|Configuração Rust]].
+- Gate de login mais permissivo (`ends_with` e bypass do `default_tenant`).
+- `validate_tenant` provisiona antes de marcar tokens usados.
+- O admin do master é semeado pelo bootstrap do security (envs `SEEDGRID_SECURITY_FIRST_ADMIN_USER_*`), não por `subdomain-tenancy.admin-user.*`.
+
+## Enums
+
+Equivalentes Java em [[SeedGrid/Extensions/subdomain-tenancy/Enums|Enums (Quarkus)]].
+
+| Enum | Arquivo | Usado em | Equivalente Java |
+|---|---|---|---|
+| `TenantMigrationStatus` | `src/migration/mod.rs` | coluna `tenant_migration_state.status`; corpo de `/internal/migrations/...` | [[SeedGrid/Extensions/subdomain-tenancy/Enums#TenantMigrationStatus\|TenantMigrationStatus]] |
+| `TenantMigrationDecision` | `src/migration/mod.rs` | `TenantMigrationOutcome`; gate de login | [[SeedGrid/Extensions/subdomain-tenancy/Enums#TenantMigrationDecision\|TenantMigrationDecision]] |
+| `TenantHealthStatus` | `src/health.rs` | corpo de `GET /internal/health/tenants/{tenantId}` | [[SeedGrid/Extensions/subdomain-tenancy/Enums#TenantHealthStatus\|TenantHealthStatus]] |
+| `TenantHealthCode` | `src/health.rs` | idem | [[SeedGrid/Extensions/subdomain-tenancy/Enums#TenantHealthCode\|TenantHealthCode]] |
+| `SignupOutcome` | `src/service.rs` | resposta de `POST /public/tenants` | [[SeedGrid/Extensions/subdomain-tenancy/Enums#SignupOutcome\|SignupOutcome]] |
+| `StateEnum` | `src/models/embeddables.rs` | `state` do endereço do signup e do tenant | `StateEnum` da lib commons |
+| `TenantAccess` | `src/pool_resolver.rs` | resultado do gate de tenant no middleware | sem equivalente (específico do Rust) |
+| `TenantServiceError`, `ProvisioningError`, `AssemblyError` | `service.rs`, `provisioning.rs`, `platform.rs` | erros | exceções do Java |
+
+### TenantMigrationStatus
+
+`Pending` → `PENDING`, `Ready` → `READY`, `Migrating` → `MIGRATING`, `Failed` → `FAILED` (via `name()`). Coluna `status VARCHAR(20) NOT NULL DEFAULT 'PENDING'`, sem CHECK (`migrations/0104_create_tenant_migration_state.sql`). `parse(Option<&str>)` é tolerante: apara, ignora caixa e transforma qualquer valor desconhecido ou ausente em `Pending`. Java: mesmos 4 valores na mesma ordem.
+
+### TenantMigrationDecision
+
+`Ready` → `READY`, `InProgress` → `IN_PROGRESS`, `Failed` → `FAILED`. Não é persistido. No gate de login, `Ready` deixa passar; qualquer outra decisão responde **503** com `Retry-After: 15` e `error` = `tenant_migration_in_progress` ou `tenant_migration_failed`. Java: mesmos 3 valores.
+
+### TenantHealthStatus e TenantHealthCode
+
+- `TenantHealthStatus`: `Up` (`UP`), `Down` (`DOWN`), `OutOfService` (`OUT_OF_SERVICE`).
+- `TenantHealthCode`: `Ok`, `InvalidTenant`, `TenantNotFound`, `TenantInactive`, `DatabaseUnreachable`, `MigrationPending`, `MigrationRunning`, `MigrationFailed`. O `name()` sai em SCREAMING_SNAKE (`OK`, `INVALID_TENANT`, ...).
+- HTTP do health (`resolve_health_status`): `UP` → 200; `INVALID_TENANT` → 400; `TENANT_NOT_FOUND` → 404; os demais → 503.
+- Java: mesmos valores e mesma ordem nos dois enums. Não são persistidos; o corpo JSON usa `name()`.
+
+### SignupOutcome
+
+`Created` → `CREATED` e `UpdatedPending` → `UPDATED_PENDING`, com resposta 201 e 200, respectivamente, em `POST /public/tenants`. Java: `CREATED`, `UPDATED_PENDING`, idêntico.
+
+### StateEnum (subdomain-tenancy)
+
+27 UFs com variantes em maiúsculas (`AC` ... `TO`), com `Serialize`/`Deserialize` por derive: serializa e desserializa **somente a sigla exata em maiúsculas**. **Atenção:** o `StateEnum` do login-tenancy Rust também aceita minúsculas e o nome completo do estado (como o `fromJson` do Java); este aqui não.
+
+### TenantAccess
+
+`Master` (escopo master, segue no pool master), `Active` (tenant existente e ativo, pool aquecido) e `Rejected` (inexistente ou inativo: o middleware responde 404, fail-closed). Sem equivalente Java.
+
+### Erros
+
+- `TenantServiceError`: `SubdomainAlreadyExists`, `CnpjAlreadyExists`, `TenantNotFound`, `TenantAlreadyActive`, `ValidationCodeExpired`, `Db`, `OtpGeneration`, `Provisioning`, `WeakPassword(Vec<String>)`.
+- `ProvisioningError`: `Locked(String)` (lock de provisionamento já tomado) e `Db(String)`.
+- `AssemblyError`: `Migration(MigrateError)`.
+
+### Internos
+
+| Enum | Arquivo |
+|---|---|
+| `SchedulerStep` (`Cleanup`, `Queue`, `Notify`) | `src/backup_scheduler.rs` |

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

@@ -0,0 +1,142 @@
+---
+tags: [seedgrid, extension, subdomain-tenancy]
+fonte: java/seedgrid-quarkus-ext-subdomain-tenancy
+branch: main
+commit: fe62530a29
+analisado-em: 2026-10-14
+---
+
+# subdomain-tenancy — Visão geral (Quarkus)
+
+Configuração: [[SeedGrid/Extensions/subdomain-tenancy/Configuracao|Configuração do subdomain-tenancy]] · Enums: [[SeedGrid/Extensions/subdomain-tenancy/Enums|Enums do subdomain-tenancy]] · Exemplos: [[SeedGrid/Extensions/subdomain-tenancy/Exemplos|Exemplos do subdomain-tenancy]] · [[SeedGrid/Extensions/subdomain-tenancy/Rust|Porte Rust]]
+
+> [!note] Fontes
+> Lido no código do commit `fe62530a29`. O `README.md` e os `docs/` da extension foram revisados contra o código em 2026-10-14. Os relatórios `AJUSTES_REALIZADOS.md`, `AUDITORIA_FINAL_CONFORMIDADE.md`, `CORRECOES_FINALIZADAS.md`, `IMPLEMENTATION_SUMMARY.md`, `RELATORIO_CONFORMIDADE.md`, `REVISAO_FINAL_CONFORMIDADE.md` e `SETUP_ENVIRONMENT.md` (raiz do repo) são históricos.
+
+## Objetivo
+
+Multi-tenancy **um banco PostgreSQL por tenant**, com o tenant identificado pelo **subdomínio** do host (`cliente1.crm.example.com` → tenant `cliente1`). Inclui:
+
+- Resolução de tenant por request (`X-Forwarded-Host`/`Host`) e `TenantResolver`/`TenantConnectionResolver` do Hibernate ORM em modo `DATABASE`.
+- Banco **master** (persistence unit `master`) com o catálogo `tenants`, security, billing, apikeys e afins.
+- **Signup self-service** com validação por OTP de 6 dígitos por e-mail e **provisionamento** automático (CREATE DATABASE + migrations + usuário root).
+- Cache de pools JDBC por tenant com limite, evicção por TTL/LRU e **circuit breaker** por tenant.
+- **Orquestração de migrations por tenant** (sob demanda no login, manual, ou todas no boot) com lock distribuído e heartbeat.
+- Health por tenant, OpenAPI filtrado por contexto (master × tenant), métricas Micrometer e spans OpenTelemetry.
+- Bootstrap do admin global no master, limpeza de cadastros não validados, integração com billing (conta + trial), audit, backup e security.
+
+## Módulos e coordenadas Maven
+
+| Módulo | Coordenada | Observação |
+|---|---|---|
+| parent | `br.com.seedgrid:seedgrid-subdomain-tenancy-parent:2026.10.14-1` (pom) | Parent: `br.com.seedgrid:seedgrid-parent:2026.07.02` (Quarkus 3.30.8). Centraliza as versões da foundation em `<properties>` e `dependencyManagement` |
+| runtime | `br.com.seedgrid:seedgrid-subdomain-tenancy:2026.10.14-1` | O que o host declara |
+| deployment | `br.com.seedgrid:seedgrid-subdomain-tenancy-deployment:2026.10.14-1` | `SubdomainTenancyProcessor` |
+
+**Confirmado** em `pom.xml`, `runtime/pom.xml`, `deployment/pom.xml`.
+
+### Dependências SeedGrid (versões do parent)
+
+| Artefato | Versão | Uso aqui |
+|---|---|---|
+| `seedgrid-commons` | 2026.10.08 | `BaseEntity`, `commons.spi.TenantProvider`, `SchemaUtils`, `ApiExceptionExtension` |
+| `seedgrid-security` | 2026.10.14 | Usuários/papéis, JWT, `PasswordService`, SPIs `JwtTokenCustomizer`, `JwtTokenValidator`, `SecurityScopeResolverProvider`, `SecurityLinkBuilder` |
+| `seedgrid-privacy` | 2026.07.27 | Mascaramento/criptografia de PII do `Tenant` |
+| `seedgrid-audit-core` | 2026.09.25 | `AuditMetadataContributor`, `AuditReadScopeProvider` (`seedgrid-audit-postgresql` só em teste) |
+| `seedgrid-backup` | 2026.10.09 | `backup.spi.TenantProvider` |
+| `seedgrid-billing-core` | 2026.10.14-1 | Conta/trial por tenant, SPIs `CurrentAccountResolver`, `AccountMembersGateway` (`seedgrid-billing-stripe` só em `dependencyManagement`) |
+| `seedgrid-apikeys` | 2026.10.14 | Schema de API keys no master e nos tenants |
+| `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-resilience-core` | 2026.10.13 | `@SeedGridRateLimit` nos endpoints públicos |
+
+Quarkus no runtime: `arc`, `hibernate-orm(-panache)`, `jdbc-postgresql`, `agroal`, `flyway`, `rest-jackson`, `hibernate-validator`, `smallrye-openapi`, `opentelemetry`, `micrometer(-registry-prometheus)`, `smallrye-fault-tolerance`, `mailer`, `qute`, `quarkus-mongodb-client` (**optional**), além de `jbcrypt`. O deployment acrescenta `quarkus-scheduler-deployment`, `quarkus-virtual-threads-deployment` e `quarkus-grpc-common-deployment`.
+
+Extensions relacionadas: [[SeedGrid/Extensions/security/Visao-geral|security]], [[SeedGrid/Extensions/billing/Visao-geral|billing]], [[SeedGrid/Extensions/audit/Visao-geral|audit]], [[SeedGrid/Extensions/backup/Visao-geral|backup]], [[SeedGrid/Extensions/apikeys/Visao-geral|apikeys]], [[SeedGrid/Extensions/resilience/Visao-geral|resilience]], [[SeedGrid/Extensions/privacy/Visao-geral|privacy]], [[SeedGrid/Extensions/commons/Visao-geral|commons]]. Alternativa com banco compartilhado/login: [[SeedGrid/Extensions/login-tenancy/Visao-geral|login-tenancy]].
+
+## Arquitetura e fluxo
+
+```mermaid
+flowchart LR
+    R[Request] --> F1[TenantResolutionFilter<br/>prio AUTHENTICATION-1]
+    F1 -->|host -> tenant| C[(TenantContext<br/>RequestScoped)]
+    F1 --> F2[TenantMigrationGateFilter<br/>prio AUTHENTICATION]
+    F2 -->|login-paths| MC[TenantMigrationCoordinator]
+    C --> QR[QuarkusTenantResolver]
+    QR --> H[Hibernate PU default<br/>multitenant=DATABASE]
+    H --> TCR[TenantConnectionResolverImpl]
+    TCR -->|master| MDS[(DataSource master)]
+    TCR -->|tenant| POOL[Pool por tenant<br/>cache + LRU + circuit breaker]
+    POOL --> TDB[(banco prefix_tenant)]
+```
+
+- **Resolução** (Confirmado): `TenantResolutionFilter` lê `X-Forwarded-Host` (prioritário) ou `Host`, extrai o tenant com `TenantHostExtractor` e grava no `TenantContext` e no MDC (`tenantId`); sem tenant → `master`. O Javadoc do filtro deixa explícito que o default para `master` **não** é fronteira de segurança: o isolamento vem do JWT/API key serem resolvidos no banco do próprio tenant.
+- **JWT**: `SubdomainTenancyJwtTokenCustomizer` adiciona as claims `subdomain` e `audience` (`platform`/`client`); `SubdomainTenancyJwtTokenValidator` rejeita token cujo `subdomain` difere do host.
+- **Conexões**: `TenantConnectionResolverImpl` verifica no master se o tenant existe e está ativo (`TenantNotFoundException` caso contrário), cria `SimpleDriverDataSource` por tenant, aplica limite/evicção e circuit breaker. Detalhes dos parâmetros em [[SeedGrid/Extensions/subdomain-tenancy/Configuracao|Configuração]].
+- **Startup** (`MigrationService#onStart`, `@Priority(APPLICATION)`): no master roda, em ordem, security → audit (se `jpa`) → backup → billing → apikeys → ai-pricing/exchange (se habilitados) → subdomain-tenancy → `db/migration/master` (+ additional), depois `AdminUserBootstrapService#seedAdminUserIfNeeded`. Tenants não migram no boot por padrão.
+- **Signup → provisionamento**: `POST /public/tenants` grava o tenant pendente e envia OTP; `POST /public/tenants/validate-email` valida o código e chama `TenantProvisioningService#createTenantWithAdmin` (lock local + `pg_try_advisory_lock`, `CREATE DATABASE` idempotente, migrations security → tenant → audit → backup → apikeys, usuário root; rollback com `DROP DATABASE` se o banco foi criado no fluxo), depois `SubdomainBillingAccounts#ensureFor` (conta + trial no billing) e ativa o tenant.
+- **Migração por tenant**: `TenantMigrationCoordinator` com estado em `tenant_migration_state` (`PENDING`/`MIGRATING`/`READY`/`FAILED`), lock com fencing token e heartbeat. Gatilhos: login (gate devolve `503` + `Retry-After: 15`), endpoint manual, ou boot.
+- **Limpeza**: `TenantCleanupScheduler` remove do master os cadastros não validados mais velhos que o TTL (não remove o banco — ver Limitações).
+
+## APIs públicas e pontos de integração
+
+### Endpoints REST
+
+| Método e path | Classe | Acesso | Observação |
+|---|---|---|---|
+| `POST /public/tenants` | `TenantSignupController#signupTenant` | público, rate limit `tenant-signup` (100/min) | `201` CREATED ou `200` UPDATED_PENDING; corpo traz `emailDelivered` |
+| `POST /public/tenants/validate-email` | `#validateEmail` | público, `tenant-validate-email` (10/min) | Body `{subdomain, code}`; dispara o provisionamento |
+| `POST /public/tenants/resend-email?subdomain=` | `#resendEmail` | público, `tenant-resend-email` (5/h) | `400` sem `subdomain` |
+| `GET /public/tenant-openapi` | `TenantOpenApiController#getFilteredOpenApi` | `@PermitAll` + permissão HTTP `permit` no `MPC` | Remove tag `tenant-only` no master; `master-only` + `master-only-paths` nos tenants |
+| `POST /internal/migrations/tenants/{tenantId}/trigger?force=` | `TenantMigrationController#triggerMigration` | só contexto master (`403 master_scope_required`) | Não há `@RolesAllowed` na classe; a autenticação depende da política global do security (**Não confirmado**) |
+| `GET /internal/migrations/tenants/{tenantId}/status` | `#migrationStatus` | idem | — |
+| `GET /internal/health/tenants/{tenantId}` | `TenantHealthController#tenantHealth` | idem | Códigos `OK`, `INVALID_TENANT`, `TENANT_NOT_FOUND`, `TENANT_INACTIVE`, `DATABASE_UNREACHABLE`, `MIGRATION_PENDING/RUNNING/FAILED` |
+
+Paths centralizados em `RestControllerPath`. Exceções mapeadas por `SubdomainTenancyExceptionExtension` (`ApiExceptionExtension` do commons): `TenantNotFoundException` → 404, `SubdomainAlreadyExistsException`/`CnpjAlreadyExistsException` → 409, `TenantAlreadyActiveException`/`ValidationCodeExpiredException` → 400.
+
+### Anotações
+- `@MasterOnly` / `@TenantOnly` (`annotations/`): meta-anotações com `@Tag("master-only")`/`@Tag("tenant-only")` — **só documentação/OpenAPI**, não controlam acesso.
+
+### SPIs para o host
+
+| Interface | Default fornecido | Uso |
+|---|---|---|
+| `spi.SubdomainTenancyNotificationService#sendValidationNotification(TenantValidationNotification)` | `MailerNotificationService` (`@DefaultBean`, mailer `subdomaintenancy`) | Entrega do OTP |
+| `spi.TemplateSubdomainTenancyProvider#buildValidationEmail(...)` | `DefaultTemplateSubdomainTenancyProvider` (`@DefaultBean`, Qute: procura `templates/subdomain-tenancy/confirmation.html` ou `subdomain-tenancy/html/confirmation.html` do host e cai em `subdomaintenancy-default/html/confirmation.html` da extension) | HTML do OTP quando não há `EmailTemplateProvider` |
+| `spi.EmailTemplateProvider#buildConfirmationEmailHtml(...)`, `#getConfirmationEmailSubject(...)` | nenhum | Opcional; se resolvível, define assunto/HTML |
+| `spi.PasswordEncoder#encode(String)` | `BCryptPasswordEncoder` (`@DefaultBean`) | Injetado como `Instance<PasswordEncoder>` em `TenantService`/`TenantProvisioningService` |
+
+Com os defaults `@DefaultBean`, o envio do OTP funciona só com o SMTP configurado (**Confirmado**).
+
+### Beans CDI úteis ao host
+- `TenantContext` (`@RequestScoped`): `getCurrentTenant()`, `setCurrentTenant(String)`, `clear()`.
+- `TenantScopedExecutor#call(Supplier<T>)`: executa em nova transação (`REQUIRES_NEW`).
+- `TenantHostExtractor#extractTenantFromHost(String)`.
+- `TenantAwareMongoProducer` (`@Produces @DefaultBean MongoDatabase`, banco `<prefix>_<tenant>_audit_db`) e `MongoTenantResolverProducer` → `MongoTenantResolver` quando há `MongoClient`.
+- Implementações de SPIs de outras extensions: `MultiTenantProvider` (commons), `MultiTenantBackupProvider` (backup), `TenantAuditScopeProvider` (audit), `SubdomainCurrentAccountResolver`/`SubdomainAccountMembersGateway` (billing), `SubdomainTenancySecurityScopeResolver`, `TenantSecurityLinks` (`@Alternative @Priority(1)`, reescreve links de e-mail do security para `<tenant>.<host>`).
+
+### Métricas (Micrometer)
+`seedgrid.subdomain-tenancy.tenant.datasource.provisioning.failures`, `…connection.failures`, `…connection.circuit.open`, `…active.pools`, `…active.connections.total`, `…connections.active{tenant}`, `…evictions{reason=ttl|lru}`, `seedgrid.subdomain-tenancy.migration.failures`.
+
+## Migrations
+
+| Location | Versões | History | Onde roda |
+|---|---|---|---|
+| `db/migration/subdomain-tenancy` | `V100`–`V110` (tenants, root user, campos de trial legados, snapshots, `tenant_migration_state`, fencing token, índices, `tenant_validation_tokens`, hashes de busca de privacy, conta de billing) | `flyway_schema_history_subdomain_tenancy` | master |
+| `db/migration/tenancy` | `V706__timestamps_com_fuso.sql` | — | **Não aplicada** pela extension (nenhuma location aponta para ela). `java/MIGRATION_RANGES.md` documenta a faixa 100–199 e trata a V706 como exceção legada |
+| `db/migration/master` / `db/migration/tenant` (do host) | livres | `flyway_schema_history_master` / `_tenant` | master no boot / tenant no provisionamento e migração |
+
+## Testes
+
+`runtime/src/test/java/br/com/seedgrid/subdomaintenancy/` — 17 classes, ~76 métodos `@Test`. **Não executados** nesta análise.
+
+- Unitários (Mockito): `TenantHostExtractorTest` (10), `TenantsRepositoryTest` (7), `TenantHealthServiceTest`, `TenantProvisioningServiceTest`, `TenantServiceTest`, `TenantMigrationCoordinatorTest`, `TenantMigrationStateStoreTest`, `TenantResolutionFilterTest`, `TenantHealthControllerTest`, `TenantOpenApiControllerFilterTest`, `TenantAuditScopeProviderTest`, `TenantSecurityLinksTest`, `TenantToStringMaskingTest`.
+- `@QuarkusTest` com Postgres via Testcontainers (`SubdomainTenancyPostgresTestResource`): `TenantRegisterResourceIntegrationTest` (9), `TenantsRepositoryIntegrationTest` (6), `TenantBillingIntegrationTest`, `TenantEncryptedFieldsTest` (perfil com criptografia de privacy).
+- Há também `perf/jmeter/login-concurrency.jmx` (carga de login concorrente).
+
+## Limitações
+
+- **Somente PostgreSQL** (`CREATE DATABASE`, `pg_try_advisory_lock`, `pg_terminate_backend`); o usuário de tenant precisa de `CREATE DATABASE`.
+- **Subdomínios com `_`**: o signup aceita `^[a-z0-9_]{5,50}$`, mas o extractor só aceita `^[a-z0-9-]+$` → esses tenants caem em `master` pelo host (**Confirmado**; ver Dúvidas na Configuração).
+- Teto de `max-active-datasources` sem pool ocioso → `TenantProvisioningException` na resolução.
+- `TenantCleanupScheduler` remove só o registro em `tenants`, não o banco físico (contradiz o Javadoc). Se houver banco criado para cadastro não validado, ele fica órfão (o provisionamento só ocorre após validação, então na prática isso só acontece em cenários de falha — **Inferência**).
+- Vários literais `"master"` fixos: `default-tenant` diferente de `master` não é consistente.

package/seedgridKB/SeedGrid/Extensions/whatsapp/Configuracao-Rust.md

@@ -0,0 +1,75 @@
+---
+tags: [seedgrid, extension, whatsapp, rust, configuracao]
+fonte: rust/seedgrid-rust-crate-whatsapp
+branch: main
+commit: be738a2d1e
+analisado-em: 2026-10-14
+---
+
+# whatsapp — Configuração Rust
+
+Visão do crate: [[SeedGrid/Extensions/whatsapp/Rust|Porte Rust do whatsapp]] · Java: [[SeedGrid/Extensions/whatsapp/Configuracao|Configuração do whatsapp (Java)]].
+
+## Cabeçalho
+| Item | Valor |
+|---|---|
+| Struct | `WhatsAppConfig` — `rust/seedgrid-rust-crate-whatsapp/src/config.rs` |
+| Mecanismo | `WhatsAppConfig::from_env()` (`std::env::var`) ou struct do host |
+| Prefixo Java | `seedgrid.whatsapp` |
+| Quem chama `from_env` | security (`src/state.rs`, para o canal 2FA WhatsApp) |
+| Leitura | quando `from_env()` é chamado (boot); sem recarga |
+
+Os nomes de env são exatamente os das expressões `${...}` de `java/seedgrid-quarkus-ext-whatsapp/seedgrid-whatsapp-core/src/main/resources/META-INF/microprofile-config.properties` (**Confirmado**), com os mesmos padrões.
+
+## Variáveis de ambiente
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `SEEDGRID_WHATSAPP_API` (Java `seedgrid.whatsapp.api`) | String | `default`, `evolution`, `whatsapp-cloud` (case-insensitive, com `trim`); vazio/desconhecido → `default` | `default` | Não | escolhe o provider em `create_whatsapp_api` | `factory.rs`; `enums.rs` → `WhatsAppProvider::from_config` | define quais variáveis abaixo importam | `from_env()` | `config.rs` → `from_env` |
+| `SEEDGRID_WHATSAPP_REST_CLIENT_EVOLUTION_URL` (Java `seedgrid.whatsapp.rest-client.evolution.url`) | `Option<String>` | URL base da Evolution API | — (vira `""` no transporte) | Condicional: `api=evolution` | base das requisições | `EvolutionWhatsAppApi::new` | `EVOLUTION_API_KEY` | `from_env()` | `evolution.rs` |
+| 🔒 `SEEDGRID_WHATSAPP_EVOLUTION_API_KEY` (Java `seedgrid.whatsapp.evolution.api-key`) | `Option<String>` | texto | — | Condicional: `api=evolution` | ausente/branco → `is_configured() = false` e `IllegalState` na chamada | `EvolutionWhatsAppApi::require_api_key` | — | `from_env()` | `evolution.rs` |
+| `SEEDGRID_WHATSAPP_REST_CLIENT_CLOUD_URL` (Java `seedgrid.whatsapp.rest-client.cloud.url`) | String | URL | `https://graph.facebook.com/v21.0` (`DEFAULT_CLOUD_URL`; vazio → padrão) | Não | base da Graph API | `OfficialCloudWhatsAppApi::new` | — | `from_env()` | `config.rs`, `cloud.rs` |
+| 🔒 `SEEDGRID_WHATSAPP_CLOUD_ACCESS_TOKEN` (Java `seedgrid.whatsapp.cloud.access-token`) | `Option<String>` | token Meta | — | Condicional: `api=whatsapp-cloud` | `Authorization: Bearer`; ausente → `is_configured() = false` e `IllegalState` na chamada | `cloud.rs` | — | `from_env()` | `cloud.rs` |
+
+Valores em branco contam como ausentes (`opt_env`), exceto `SEEDGRID_WHATSAPP_API`, que é lido cru (o branco cai em `default` pela fábrica).
+
+## Struct `WhatsAppConfig`
+| Campo | `Default` |
+|---|---|
+| `api` | `"default"` |
+| `evolution_api_key` | `None` |
+| `cloud_access_token` | `None` |
+| `evolution_url` | `None` |
+| `cloud_url` | `DEFAULT_CLOUD_URL` |
+
+## Features Cargo
+Nenhuma.
+
+## Relação com a security
+O canal 2FA por WhatsApp na security usa também `SEEDGRID_SECURITY_2F_WHATSAPP_CHANNEL_ID` (citado em `rust/seedgrid-rust-crate-security/src/state.rs`); essa variável pertence à configuração da security, fora desta nota.
+
+## Somente testes
+Nenhuma variável de ambiente lida em `tests/`.
+
+## Configuração mínima
+```dotenv
+# Evolution
+SEEDGRID_WHATSAPP_API=evolution
+SEEDGRID_WHATSAPP_REST_CLIENT_EVOLUTION_URL=https://<evolution-host>
+SEEDGRID_WHATSAPP_EVOLUTION_API_KEY=<SEGREDO:evolution-api-key>
+```
+
+## Configuração completa comentada
+```dotenv
+SEEDGRID_WHATSAPP_API=whatsapp-cloud            # default | evolution | whatsapp-cloud
+# Evolution
+SEEDGRID_WHATSAPP_REST_CLIENT_EVOLUTION_URL=https://<evolution-host>
+SEEDGRID_WHATSAPP_EVOLUTION_API_KEY=<SEGREDO:evolution-api-key>
+# Cloud oficial
+SEEDGRID_WHATSAPP_REST_CLIENT_CLOUD_URL=https://graph.facebook.com/v21.0
+SEEDGRID_WHATSAPP_CLOUD_ACCESS_TOKEN=<SEGREDO:meta-access-token>
+```
+
+## Receitas
+- **Desligado/dev**: não definir nada → `default` (no-op que loga; `is_configured()` falso).
+- **Evolution**: três variáveis do bloco Evolution.
+- **Cloud oficial**: `SEEDGRID_WHATSAPP_API=whatsapp-cloud` + access token.