@seedgrid/ai-toolkit 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,210 @@
+---
+tags: [seedgrid, extension, backup, exemplos]
+fonte: java/seedgrid-quarkus-ext-backup
+branch: main
+commit: 3bed4075ea
+analisado-em: 2026-10-14
+---
+
+# Exemplos — backup (Quarkus)
+
+Voltar: [[SeedGrid/Extensions/backup/Visao-geral|Visão geral do backup]] · Propriedades: [[SeedGrid/Extensions/backup/Configuracao|Configuração do backup]]
+
+Todos os exemplos usam tipos e assinaturas reais do runtime (`br.com.seedgrid.backup.*`). Fonte indicada em cada um.
+
+## 1. Dependência Maven
+
+Fonte: `runtime/pom.xml` (coordenadas reais).
+
+```xml
+<dependency>
+    <groupId>br.com.seedgrid</groupId>
+    <artifactId>seedgrid-backup</artifactId>
+    <version>2026.10.09</version>
+</dependency>
+```
+
+O host também precisa de: datasource PostgreSQL, um bean `CurrentUserProvider` (commons), um `UserContactProvider` (para o e-mail) e, para `@Audit` persistir, um provider de auditoria (ex. `seedgrid-audit-postgresql`) — ver [[SeedGrid/Extensions/audit/Visao-geral|audit]].
+
+## 2. Fluxo REST
+
+Fonte: `ExportController`, `ExportRequest`, `ExportResponse`, `README.md` (seção "Endpoints REST").
+
+```bash
+# Criar (BACKUP_CREATE) -> 201
+curl -X POST https://<host>/exports \
+  -H "Authorization: Bearer <SEGREDO:token>" \
+  -H "Content-Type: application/json" \
+  -d '{ "format": "CSV_ZIP", "scope": "DOMAIN" }'
+
+# Listar jobs do usuário corrente (BACKUP_READ)
+curl "https://<host>/exports?page=0&size=20" -H "Authorization: Bearer <SEGREDO:token>"
+
+# Status (BACKUP_READ) -> 200 / 404
+curl https://<host>/exports/<jobId> -H "Authorization: Bearer <SEGREDO:token>"
+
+# Download (BACKUP_DOWNLOAD) -> 200 application/zip / 404 não pronto / 410 expirado ou falho
+curl -OJ https://<host>/exports/<jobId>/download -H "Authorization: Bearer <SEGREDO:token>"
+
+# Cancelar ou excluir (BACKUP_DELETE) -> 204 / 404
+curl -X DELETE https://<host>/exports/<jobId> -H "Authorization: Bearer <SEGREDO:token>"
+```
+
+Valores aceitos: `format` = `CSV_ZIP` | `SQL_DUMP_ZIP`; `scope` = `DOMAIN` | `RAW`. Resposta de criação: `ExportResponse` com `status = QUEUED`, `progress = 0`.
+
+Conteúdo do ZIP `CSV_ZIP` (fonte: `CsvZipExporter#createZipArchive`): `data/<tabela-ou-entidade>.csv`, `manifest.json`, `checksums.txt`; nome `export_<schema>_<timestamp>.zip`, gravado sob o prefixo `<schema>/exports` do storage.
+
+## 3. Exporter customizado (SPI `BackupExporter`)
+
+Fonte: `spi/BackupExporter.java`, `spi/ExportContext.java`, `spi/ExportResult.java`; adaptado do `README.md` ("Implementar um BackupExporter"). Atenção: a extensão já registra exporters para `CSV_ZIP` e `SQL_DUMP_ZIP`; o `BackupExporterRegistry` lança `IllegalStateException` no startup se houver dois beans para o mesmo `BackupFormat`. Portanto um exporter próprio só pode coexistir se o default do mesmo formato for removido (ex. `quarkus.arc.exclude-types`) — **Inferência**; não há novos valores de `BackupFormat` além dos dois existentes.
+
+```java
+import java.util.List;
+
+import br.com.seedgrid.backup.domains.BackupFormat;
+import br.com.seedgrid.backup.domains.ExportScope;
+import br.com.seedgrid.backup.spi.BackupExporter;
+import br.com.seedgrid.backup.spi.ExportContext;
+import br.com.seedgrid.backup.spi.ExportException;
+import br.com.seedgrid.backup.spi.ExportResult;
+import br.com.seedgrid.backup.spi.ExportValidationException;
+import jakarta.enterprise.context.ApplicationScoped;
+
+@ApplicationScoped
+public class MySqlDumpExporter implements BackupExporter {
+
+    @Override
+    public BackupFormat format() {
+        return BackupFormat.SQL_DUMP_ZIP;
+    }
+
+    @Override
+    public void validate(ExportContext ctx) throws ExportValidationException {
+        if (ctx.getScope() != ExportScope.RAW) {
+            throw new ExportValidationException("só RAW é suportado");
+        }
+    }
+
+    @Override
+    public ExportResult export(ExportContext ctx) throws ExportException {
+        ctx.updateProgress(10, "extraindo dados");
+        byte[] zipBytes = buildZip(ctx);                       // sua lógica
+        String key = ctx.getStorageService().store("export.zip", zipBytes);
+        ctx.updateProgress(100, "concluído");
+
+        return ExportResult.builder()
+                .artifacts(List.of(ExportResult.ArtifactData.builder()
+                        .type(ExportResult.ArtifactType.ZIP)
+                        .storageKey(key)
+                        .filename("export.zip")
+                        .sizeBytes(zipBytes.length)
+                        .mimeType("application/zip")
+                        .build()))
+                .totalSizeBytes(zipBytes.length)
+                .build();
+    }
+
+    private byte[] buildZip(ExportContext ctx) {
+        throw new UnsupportedOperationException("implementar");
+    }
+}
+```
+
+`ExportContext` expõe (Lombok `@Data`): `getJobId()`, `getFormat()`, `getScope()`, `getDatabaseSchema()`, `getOptions()`, `getOption(key, default)` (mapa `options` do pedido; os exporters embutidos não o leem), `updateProgress(int, String)`, `getStorageService()` (`store`/`retrieve`/`delete`) e `getExportJob()` (pode ser `null` — o pipeline não o preenche mais).
+
+## 4. `TenantProvider` para host multitenant
+
+Fonte: `spi/TenantProvider.java`; default `configs/SingleTenantBackupProvider` (`@DefaultBean`, tenant `"public"`). O valor do tenant é usado como **schema PostgreSQL** (filtro de `information_schema`) e como prefixo do storage. Schedulers iteram `getAllTenants()` e não fazem nada se a lista vier vazia.
+
+```java
+import java.util.List;
+import java.util.Optional;
+
+import br.com.seedgrid.backup.spi.TenantProvider;
+import jakarta.enterprise.context.ApplicationScoped;
+
+@ApplicationScoped
+public class MyTenantBackupProvider implements TenantProvider {
+
+    private static final ThreadLocal<String> CURRENT = new ThreadLocal<>();
+
+    @Override
+    public Optional<String> getCurrentTenant() {
+        return Optional.ofNullable(CURRENT.get());   // ou resolver do contexto da requisição
+    }
+
+    @Override
+    public void setCurrentTenant(String tenantId) {
+        CURRENT.set(tenantId);
+    }
+
+    @Override
+    public void clearCurrentTenant() {
+        CURRENT.remove();
+    }
+
+    @Override
+    public List<String> getAllTenants() {
+        return List.of("tenant_a", "tenant_b");      // schemas existentes
+    }
+}
+```
+
+O teste `TestTenantProvider` usa o mesmo padrão com `@Alternative @Priority(1)`; a extensão `seedgrid-subdomain-tenancy` fornece um `MultiTenantBackupProvider` (`java/seedgrid-quarkus-ext-subdomain-tenancy/runtime/src/main/java/br/com/seedgrid/subdomaintenancy/backup/MultiTenantBackupProvider.java`).
+
+## 5. Reagir ao fim do export (`SgUserEvent`)
+
+Fonte: `ExportService#notifyRequester` e teste `services/ExportUserEventIT` (observer `AFTER_SUCCESS`).
+
+```java
+import br.com.seedgrid.commons.events.SgUserEvent;
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.enterprise.event.Observes;
+import jakarta.enterprise.event.TransactionPhase;
+
+@ApplicationScoped
+public class BackupFinishedListener {
+
+    void on(@Observes(during = TransactionPhase.AFTER_SUCCESS) SgUserEvent event) {
+        if (!"backup".equals(event.channel())) {
+            return;
+        }
+        // event.event(): "backup.finished.success" ou "backup.finished.error"
+        String jobId = (String) event.data().get("exportPublicId");
+        String status = (String) event.data().get("status");    // "DONE" ou "FAILED"
+        String user = event.userPublicId();
+        // ex.: empurrar notificação realtime ao usuário
+    }
+}
+```
+
+## 6. Trocar o canal de notificação (`ExportNotificationService`)
+
+Fonte: `spi/ExportNotificationService.java`; default `EmailExportNotificationService` é `@DefaultBean`, então basta declarar outro bean. O `NotificationSchedulerService` só chama `notifyReady` quando `isEnabled()` e `seedgrid.backup.notification.enabled` são `true`; exceção → `notificationError` gravado e nova tentativa após `retry-delay`, até `max-retries`.
+
+```java
+import br.com.seedgrid.backup.entities.ExportJob;
+import br.com.seedgrid.backup.spi.ExportNotificationService;
+import jakarta.enterprise.context.ApplicationScoped;
+
+@ApplicationScoped
+public class WebhookExportNotificationService implements ExportNotificationService {
+
+    @Override
+    public void notifyReady(ExportJob job) throws Exception {
+        String jobId = job.getPublicId();
+        String requester = job.getCreateUserPublicId();
+        // enviar para o canal desejado; lançar exceção para provocar retry
+    }
+}
+```
+
+## 7. Template do e-mail
+
+Fonte: `spi/impl/DefaultTemplateBackupProvider.java`. Sem código: coloque no classpath do host `templates/backup/ready-notification.html` (tem prioridade sobre `templates/backup-default/html/ready-notification.html`). Placeholders substituídos por `String.replace`: `{{jobId}}`, `{{format}}`, `{{scope}}`, `{{sizeBytes}}`, `{{finishedAt}}`.
+
+Ou implemente `TemplateBackupProvider#readyNotification(ExportJob)` em um bean próprio.
+
+## 8. Configuração
+
+Exemplos de `application.properties` (mínimo, completo e receitas) estão em [[SeedGrid/Extensions/backup/Configuracao|Configuração do backup]].

package/seedgridKB/SeedGrid/Extensions/backup/Rust.md

@@ -0,0 +1,135 @@
+---
+tags: [seedgrid, extension, backup, rust]
+fonte: rust/seedgrid-rust-crate-backup
+branch: main
+commit: be738a2d1e
+analisado-em: 2026-10-14
+---
+
+# backup — porte Rust (`seedgrid-rust-crate-backup`)
+
+Porte da extensão Quarkus `seedgrid-quarkus-ext-backup`. Lado Java: [[SeedGrid/Extensions/backup/Visao-geral|Visão geral do backup (Java)]] · [[SeedGrid/Extensions/backup/Configuracao|Configuração do backup (Java)]]. Configuração Rust: [[SeedGrid/Extensions/backup/Configuracao-Rust|Configuração Rust do backup]].
+
+Motor de **export** de dados de tenant: dump do Postgres para CSV compactado em ZIP, rastreio de jobs no banco, storage plugável (via filemanagement), auditoria (via audit), rate limit no create (via resilience) e notificação por e-mail. **Não** é backup de arquivos/SO e **não** tem restore. **Confirmado** (`src/lib.rs`).
+
+## Identificação
+| Item | Valor |
+|---|---|
+| Pacote Cargo | `seedgrid-rust-crate-backup` (lib `seedgrid_backup`) |
+| Versão | workspace `2026.10.14` |
+| Edição / MSRV | 2021 / 1.82 |
+| Features Cargo | nenhuma |
+| Dependências SeedGrid | `seedgrid-rust-crate-filemanagent` (lib `seedgrid_filemanagement`), `seedgrid-rust-crate-audit`, `seedgrid-rust-crate-resilience`, `seedgrid-rust-crate-cache`, `seedgrid-runtime` (eventos `UserEventSink`) |
+
+## Fluxo
+1. `ExportService::create_export_job` grava o job `QUEUED`; com `async_enabled`, dispara worker `tokio`: claim (`RUNNING`) → exporter → `DONE` (ou `FAILED`).
+2. `ExtractDataService`: escopo **RAW** lê `information_schema.tables` (exclui `flyway_%` e tabelas internas `export_jobs`, `export_artifacts`, `audit_log*`) e faz `SELECT <col>::text`; **DOMAIN** usa o SPI `DomainDatasetProvider` do host (default vazio); **CUSTOM** gera erro.
+3. `CsvZipExporter` (único exporter): ZIP nível 9 com `manifest.json`, `checksums.txt` (formato `sha256sum`) e `data/<nome>.csv` por dataset não vazio.
+4. Retenção: `expires_at = agora + retention_days`; `BackupScheduler::clean_expired_exports` apaga expirados.
+5. `BackupScheduler::spawn` roda `process_queued_exports` (a cada `queue_poll_interval`, respeita `max_concurrent_exports`) e `process_notifications` (a cada `notification.poll_interval`, com `max_retries`/`retry_delay`).
+6. Notificação `EmailExportNotificationService`: `is_enabled = notification.enabled && mailer.from && mailer.host`; envio pelo SPI `Mailer` (default `LoggingMailer`; `SmtpMailer::from_config` para SMTP real via lettre).
+
+Fonte: `src/service.rs`, `src/extract.rs`, `src/exporter.rs`, `src/scheduler.rs`, `src/notification.rs`, `src/email_smtp.rs`.
+
+## API pública principal
+| Símbolo | Papel |
+|---|---|
+| `BackupConfig` | config ([[SeedGrid/Extensions/backup/Configuracao-Rust\|Configuração Rust]]) |
+| `BackupPlatform::assemble(Option<&PgPool>, BackupOverrides)` → `Option<Arc<BackupAssembly>>` | montagem a partir do ambiente (opt-in + migrations) |
+| `BackupAssembly::build_service(pool)` / `config()` | `ExportService` por banco (single-DB ou por tenant) |
+| `BackupOverrides { domain_provider, require_opt_in, auditor, user_events }` | seams do host; `Default`: `EmptyDomainDatasetProvider`, `require_opt_in = true`, `NoopAuditor`, sink no-op |
+| `ExportService` | `create_export_job`, `get_export_status`, `list_export_jobs`, `cancel_export_job`, `delete_export_job`, `download_export_file`, `execute_export_async`… |
+| `BackupScheduler` | `spawn`, `clean_expired_exports`, `process_queued_exports`, `process_notifications` |
+| `router(BackupApiState)` / `router_with_resolver(...)` | rotas `/exports` |
+| `rest::export_create_rate_limit()` | `SeedGridRateLimit` (`export-create`, 10/hora) para o host acoplar |
+| `migrate(&PgPool)` / `MIGRATOR` | migrations `0400`–`0402`, histórico `_sqlx_migrations_backup` |
+| `openapi()` | spec utoipa |
+| SPIs: `BackupExporter`, `DomainDatasetProvider`, `TenantProvider` (default `SingleTenantBackupProvider` → `public`), `CurrentUserProvider`, `PermissionGuard` (default `AllowAllPermissionGuard`), `ExportNotificationService`, `Mailer`, `TemplateBackupProvider`, `UserContactProvider` | `src/spi.rs`, `src/rest.rs` |
+
+## Endpoints
+| Método | Path | Permissão (host-enforced via `PermissionGuard`) |
+|---|---|---|
+| POST | `/exports` | `BACKUP_CREATE` (+ rate limit `export-create`) |
+| GET | `/exports?page&size` | `BACKUP_READ` |
+| GET | `/exports/{jobId}` | `BACKUP_READ` |
+| DELETE | `/exports/{jobId}` | `BACKUP_DELETE` |
+| GET | `/exports/{jobId}/download` | `BACKUP_DOWNLOAD` (410 para terminal expirado/falho) |
+
+Fonte: `src/rest.rs` → `router`. O guard default (`AllowAllPermissionGuard`) libera tudo; as permissões `BACKUP_*` são aplicadas pelo host.
+
+## Exemplo (de `rust/examples/seedgrid-backup-example/src/main.rs`)
+```rust
+let mut config = BackupConfig { async_enabled, storage: "filesystem".to_string(), ..BackupConfig::default() };
+config.filesystem.base_path = base_path.to_string();
+let config = Arc::new(config);
+let fs_registry = Arc::new(FileStorageRegistry::new(BuiltInStorageFactories::all()).expect("storage registry"));
+let extract = Arc::new(ExtractDataService::new(pool.clone(), Arc::new(EmptyDomainDatasetProvider)));
+let exporter = Arc::new(CsvZipExporter::new(fs_registry.clone(), extract, config.clone()));
+let exporter_registry = Arc::new(BackupExporterRegistry::new(vec![exporter as Arc<dyn BackupExporter>]).expect("exporter registry"));
+let service = ExportService::new(exporter_registry, ExportJobRepository::new(pool), fs_registry,
+    Arc::new(SingleTenantBackupProvider::new()), config, Arc::new(NoopAuditor));
+```
+O exemplo constrói `BackupConfig` à mão (não chama `from_env`).
+
+## Testes
+- Unitários em `src/*` (checksum, manifest, CSV/ZIP, config/durações).
+- ITs `tests/csv_zip_exporter_it.rs`, `export_async_flow_it.rs`, `export_resource_it.rs`, `extract_data_it.rs`, `user_event_it.rs` com gate `BACKUP_TEST_DATABASE_URL` (`tests/common/mod.rs`).
+- E2E Testcontainers: `rust/examples/seedgrid-backup-example/tests/`.
+- **Não executados.**
+
+## Limitações conhecidas
+
+- `SQL_DUMP_ZIP` não tem exporter e `CUSTOM` retorna erro.
+- `includeAttachments` é ignorado e `appVersion` é fixo em `1.0.0`.
+- O mailer de notificação vem ligado por padrão.
+
+## Enums
+Equivalentes Java: [[SeedGrid/Extensions/backup/Enums|Enums do backup (Java)]].
+
+| Enum | Arquivo | Java equivalente |
+|---|---|---|
+| `ExportStatus` | `src/enums.rs` | [[SeedGrid/Extensions/backup/Enums#ExportStatus\|ExportStatus]] |
+| `ExportScope` | `src/enums.rs` | [[SeedGrid/Extensions/backup/Enums#ExportScope\|ExportScope]] |
+| `BackupFormat` | `src/enums.rs` | [[SeedGrid/Extensions/backup/Enums#BackupFormat\|BackupFormat]] |
+| `ArtifactType` | `src/enums.rs` | [[SeedGrid/Extensions/backup/Enums#ArtifactType\|ArtifactType]] (aninhado em `ExportArtifact`/`ExportResult` no Java) |
+| `ExportError` | `src/error.rs` | exceções do backup |
+
+Todos usam `#[serde(rename_all = "SCREAMING_SNAKE_CASE")]` (JSON igual ao nome Java) e são gravados como `VARCHAR` com o nome em maiúsculas (`as_str()`; leitura por `from_db`, que falha em valor desconhecido). `code()`/`from_code()` usam o código curto (`"done-notified"`, `"csv-zip"`…), case-insensitive.
+
+### ExportStatus
+| Valor | `as_str` / `code` | Efeito no Rust |
+|---|---|---|
+| `Requested` | `REQUESTED` / `requested` | estado inicial da entidade; o claim aceita `Requested` ou `Queued` (`service.rs`) |
+| `Queued` | `QUEUED` / `queued` | gravado por `create_export_job`; `process_queued_exports` lê `status='QUEUED'` |
+| `Running` | `RUNNING` / `running` | gravado no claim; `max_concurrent_exports` conta `status='RUNNING'` |
+| `Done` | `DONE` / `done` | fim com sucesso; `process_notifications` lê `status='DONE'`; baixável |
+| `DoneNotified` | `DONE_NOTIFIED` / `done-notified` | gravado pelo scheduler após o e-mail; baixável e terminal |
+| `Failed` | `FAILED` / `failed` | falha no export; terminal |
+| `Expired` | `EXPIRED` / `expired` | **existe no enum, mas nenhum código o atribui** (a limpeza de retenção apaga o job); terminal |
+| `Cancelled` | `CANCELLED` / `cancelled` | gravado por `cancel_export_job`; terminal |
+
+Métodos: `is_downloadable` (`Done`, `DoneNotified`), `is_terminal` (`DoneNotified`, `Failed`, `Expired`, `Cancelled`), `is_in_progress` (`Requested`, `Queued`, `Running`), `display_name`. Coluna `export_jobs.status VARCHAR(20)` (o comentário da migration lista os mesmos 8 valores; **sem CHECK constraint**). Valores iguais ao Java.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Queued: create_export_job
+    Queued --> Running: claim
+    Running --> Done: sucesso
+    Running --> Failed: erro
+    Done --> DoneNotified: e-mail enviado
+    Queued --> Cancelled: cancel
+    Running --> Cancelled: cancel
+```
+`cancel_export_job` cancela qualquer job em andamento (`Requested`, `Queued` ou `Running`); fora disso devolve `false`. Transições conferidas em `service.rs` e `scheduler.rs`.
+
+### ExportScope
+`Domain` (`DOMAIN`/`domain`), `Raw` (`RAW`/`raw`), `Custom` (`CUSTOM`/`custom`). `Domain` usa o `DomainDatasetProvider` do host; `Raw` dumpa as tabelas do schema; `Custom` falha com `CUSTOM scope not implemented` (`exporter.rs`). Coluna `export_jobs.scope VARCHAR(20)`. Iguais ao Java.
+
+### BackupFormat
+`CsvZip` (`CSV_ZIP`/`csv-zip`), `SqlDumpZip` (`SQL_DUMP_ZIP`/`sql-dump-zip`); `mime_type()` sempre `application/zip`. `SqlDumpZip` existe, mas não há exporter registrado (o `BackupExporterRegistry` falha se pedido). Coluna `export_jobs.format VARCHAR(20)`. Iguais ao Java.
+
+### ArtifactType
+`Zip`, `Manifest`, `Checksums`, `Log` (`ZIP`, `MANIFEST`, `CHECKSUMS`, `LOG`); coluna `export_artifacts.artifact_type VARCHAR(20)`. Só `Zip` é criado (`exporter.rs`) e consultado no download (`service.rs`); os demais existem no enum e no schema, sem código que os produza. Iguais ao Java.
+
+### ExportError
+`Export` → HTTP 500; `Validation` → 422; `Retrieval`, `Checksum`, `Storage`, `Database`, `Serde`, `Io` (mapeamento HTTP em `rest.rs`).

package/seedgridKB/SeedGrid/Extensions/backup/Visao-geral.md

@@ -0,0 +1,150 @@
+---
+tags: [seedgrid, extension, backup]
+fonte: java/seedgrid-quarkus-ext-backup
+branch: main
+commit: 3bed4075ea
+analisado-em: 2026-10-14
+---
+
+# Backup (extension Quarkus)
+
+Extensão Quarkus para **exportação/backup de dados por tenant e por usuário** (portabilidade LGPD/GDPR): recebe pedidos via REST, cria jobs de export, executa-os de forma assíncrona, gera um ZIP (dados + `manifest.json` + `checksums.txt`), grava o artefato num storage plugável (via `seedgrid-filemanagement`), notifica o solicitante e expira o artefato após um período de retenção.
+
+- Configuração: [[SeedGrid/Extensions/backup/Configuracao|Configuração do backup]]
+- Exemplos: [[SeedGrid/Extensions/backup/Exemplos|Exemplos do backup]]
+- Enums: [[SeedGrid/Extensions/backup/Enums|Enums do backup]] (`ExportStatus`, `ExportScope`, `BackupFormat`, `ArtifactType`)
+- [[SeedGrid/Extensions/backup/Rust|Porte Rust]] (crate `rust/seedgrid-rust-crate-backup`)
+
+## Funcionalidades (Confirmado)
+
+| Funcionalidade | Onde |
+|---|---|
+| REST `/exports` (criar, listar, status, download, cancelar/excluir) | `runtime/.../controllers/ExportController.java` |
+| Ciclo de vida do job `QUEUED → RUNNING → DONE/DONE_NOTIFIED/FAILED/CANCELLED` (`REQUESTED` e `EXPIRED` existem no enum, ver [[SeedGrid/Extensions/backup/Enums#ExportStatus|ExportStatus]]) | `domains/ExportStatus.java`, `services/ExportService.java` |
+| Execução assíncrona em thread de plataforma daemon por job (`Thread.ofPlatform().daemon()`), com transações curtas (claim → export sem transação → gravação final) | `ExportService#createExportJob`, `ExportService#executeExport` |
+| Fila: jobs `QUEUED` iniciados pelo scheduler respeitando teto global de jobs `RUNNING` | `schedulers/BackupSchedulerService#processQueuedExports` |
+| Retenção: limpeza diária (cron fixo `0 1 0 * * ?`, 00:01) de jobs com `expiresAt` vencido + artefatos | `BackupSchedulerService#cleanExpiredExports`, `ExportJobRepositoryImpl#findExpiredJobs` |
+| Notificação "backup pronto" por e-mail (Vert.x Mail) com retry | `schedulers/NotificationSchedulerService`, `services/EmailExportNotificationService` |
+| Evento CDI `SgUserEvent` (canal `backup`, eventos `backup.finished.success` / `backup.finished.error`) disparado dentro da transação final (observers `AFTER_SUCCESS` recebem após o commit) | `ExportService#notifyRequester`, teste `ExportUserEventIT` |
+| Exporters embutidos `CSV_ZIP` e `SQL_DUMP_ZIP` (INSERTs por tabela) | `exporters/CsvZipExporter.java`, `exporters/SqlDumpZipExporter.java` |
+| Escopos `DOMAIN` (entidades JPA do metamodel) e `RAW` (tabelas do schema via `information_schema`) | `services/ExtractDataService.java`, `validate()` dos exporters |
+| Isolamento por dono: status/download/cancel/delete/listagem filtram por `createUserPublicId` → não-dono recebe 404 | `ExportService#findOwnedJob`, `ExportJobRepository#findByPublicIdAndUser` |
+| Rate limit no `POST /exports`: `@SeedGridRateLimit(configKey = "export-create", permits = 10, window = 1, windowUnit = HOURS)` | `ExportController#createExport` |
+| Auditoria `@Audit` em criar/cancelar/excluir/download | `ExportService` |
+| Mapeamento de exceções: `ExportValidationException` → 422, `ExportException` → 500 (Problem Details) | `exceptions/BackupExceptionExtension.java` |
+
+## Módulos Maven e coordenadas (Confirmado — `pom.xml`)
+
+| Módulo | groupId:artifactId | Versão |
+|---|---|---|
+| parent (pom) | `br.com.seedgrid:seedgrid-backup-parent` | `2026.10.09` |
+| runtime | `br.com.seedgrid:seedgrid-backup` | `2026.10.09` |
+| deployment | `br.com.seedgrid:seedgrid-backup-deployment` | `2026.10.09` |
+
+Parent: `br.com.seedgrid:seedgrid-parent:2026.07.02`. O host depende só do runtime; o deployment é ligado via `quarkus-extension-maven-plugin` (`META-INF/quarkus-extension.properties`).
+
+## Dependências SeedGrid (Confirmado — `runtime/pom.xml`)
+
+| Artefato | Versão | Uso |
+|---|---|---|
+| `seedgrid-commons` | 2026.10.08 | `CurrentUserProvider`, `UserContactProvider`, `BaseEntity`, `PageReq`, `SgUserEvent`, `ApiExceptionExtension` |
+| `seedgrid-privacy` | 2026.07.08 | fixa convergência de versão (comentário no pom) |
+| `seedgrid-filemanagement` | 2026.07.08 | `FileStorageRegistry`, `FileStorage`, `StorageKey`, `StorageOptions` |
+| `seedgrid-resilience-core` (+ `-deployment` no deployment) | 2026.07.08 | `@SeedGridRateLimit` |
+| `seedgrid-audit-core` | 2026.07.08 | `@Audit` (o provider de persistência de auditoria é escolha do host) |
+| `seedgrid-audit-postgresql` | 2026.07.08 | **somente `test`** |
+
+Links: [[SeedGrid/Extensions/filemanagement/Visao-geral|filemanagement]], [[SeedGrid/Extensions/resilience/Visao-geral|resilience]], [[SeedGrid/Extensions/audit/Visao-geral|audit]], [[SeedGrid/Extensions/commons/Visao-geral|commons]].
+
+Quarkus/terceiros: `quarkus-arc`, `vertx-mail-client`, `quarkus-qute`, `quarkus-hibernate-orm-panache`, `quarkus-jdbc-postgresql`, `quarkus-flyway`, `quarkus-rest-jackson`, `quarkus-scheduler`, `quarkus-hibernate-validator`, `quarkus-smallrye-openapi`, `commons-csv 1.11.0`, `commons-compress 1.26.0`, Lombok (provided). O e-mail usa `vertx-mail-client` diretamente (não há `quarkus-mailer`).
+
+## Deployment (Confirmado — `deployment/.../BackupProcessor.java`)
+
+- Feature `seedgrid-backup`.
+- `ConfigMappingBuildItem(BackupConfig.class, "seedgrid.backup")`.
+- Beans unremovable: `ExportService`, `ExtractDataService`, `BackupSchedulerService`, `NotificationSchedulerService`, `EmailExportNotificationService`, `BackupExporterRegistry`, `CsvZipExporter`, `SqlDumpZipExporter`, `DefaultTemplateBackupProvider`, `SingleTenantBackupProvider`, `ExportController`.
+- Recurso nativo: `templates/backup-default/html/ready-notification.html`.
+- Não há `*BuildTimeConfig`/`@ConfigRoot`.
+
+## Arquitetura e fluxo
+
+```mermaid
+sequenceDiagram
+    participant C as Cliente
+    participant API as ExportController (/exports)
+    participant S as ExportService
+    participant W as Thread daemon / BackupSchedulerService
+    participant E as BackupExporter (CSV_ZIP / SQL_DUMP_ZIP)
+    participant FS as FileStorageRegistry (filemanagement)
+    participant N as NotificationSchedulerService
+    C->>API: POST /exports {format, scope}
+    API->>S: createExportJob (grava QUEUED)
+    alt seedgrid.backup.async-enabled=true
+        S->>W: thread daemon executeExportAsync
+    else false
+        W->>S: processQueuedExports (a cada queue-poll-interval)
+    end
+    W->>S: claimJob → RUNNING
+    S->>E: validate + export(ExportContext)
+    E->>FS: store(zip) em <schema>/exports
+    S->>S: DONE, expiresAt = agora + retention-days, SgUserEvent
+    N->>C: e-mail "backup pronto" (retry) → DONE_NOTIFIED
+    C->>API: GET /exports/{jobId}/download
+```
+
+Observação (Confirmado): mesmo com `async-enabled=true`, o scheduler de fila também enxerga jobs `QUEUED`; `claimJob` só executa jobs em `REQUESTED`/`QUEUED`, o que evita dupla execução sequencial, mas não há lock pessimista explícito — concorrência entre os dois caminhos é **Não confirmado**.
+
+## APIs públicas e pontos de integração
+
+### Endpoints REST (Confirmado — `ExportController`, `RestControllerPath`)
+
+| Método | Path | Permissão (`@PermissionsAllowed`) | Respostas |
+|---|---|---|---|
+| POST | `/exports` | `BACKUP_CREATE` | 201 + `ExportResponse`; rate limit `export-create` |
+| GET | `/exports?page=&size=` | `BACKUP_READ` | 200 lista do usuário corrente |
+| GET | `/exports/{jobId}` | `BACKUP_READ` | 200 / 404 |
+| GET | `/exports/{jobId}/download` | `BACKUP_DOWNLOAD` | 200 `application/zip` / 404 (não pronto ou não-dono) / 410 (terminal não baixável) |
+| DELETE | `/exports/{jobId}` | `BACKUP_DELETE` | 204 / 404 (cancela se em progresso; senão exclui job + artefatos) |
+
+### SPIs e beans substituíveis (Confirmado)
+
+| Tipo | Default | Como substituir |
+|---|---|---|
+| `spi.BackupExporter` | `CsvZipExporter` (`CSV_ZIP`), `SqlDumpZipExporter` (`SQL_DUMP_ZIP`) | novo bean CDI; `BackupExporterRegistry` falha no startup se houver 2 para o mesmo `BackupFormat` |
+| `spi.TenantProvider` | `configs.SingleTenantBackupProvider` (`@DefaultBean`, tenant fixo `"public"`) | bean próprio (hosts multitenant) |
+| `spi.ExportNotificationService` | `services.EmailExportNotificationService` (`@DefaultBean`) | bean próprio |
+| `spi.TemplateBackupProvider` | `spi.impl.DefaultTemplateBackupProvider` (`@DefaultBean`; usa `templates/backup/ready-notification.html` do host, senão `templates/backup-default/html/ready-notification.html`; placeholders `{{jobId}}`, `{{format}}`, `{{scope}}`, `{{sizeBytes}}`, `{{finishedAt}}`) | bean próprio ou template no classpath do host |
+| `commons.persistence.spi.CurrentUserProvider` | nenhum na extensão | **o host deve fornecer** |
+| `commons.spi.UserContactProvider` | nenhum na extensão | necessário para o e-mail (destinatário via `provideByPublicId`) — Inferência: o host/commons fornece |
+
+### Eventos
+- `SgUserEvent(userPublicId, "backup", "backup.finished.success" | "backup.finished.error", {exportPublicId, status})` — só quando o job tem `createUserPublicId`.
+
+## Persistência e migrations (Confirmado)
+
+`runtime/src/main/resources/db/migration/backup/`, tabela de histórico Flyway `flyway_schema_history_backup` (via `microprofile-config.properties`):
+
+| Versão | Conteúdo |
+|---|---|
+| V400 | `export_jobs`, `export_artifacts` (PostgreSQL, `TIMESTAMPTZ`, FK `ON DELETE CASCADE`) |
+| V401 | Insere permissões `BACKUP_CREATE/READ/DOWNLOAD/DELETE` em `permissions` e vincula ao papel `ADMIN` (`roles`, `role_permissions`) — exige tabelas da extensão de segurança |
+| V402 | Coluna `active` nas duas tabelas |
+| V403 | `audience = null` nas permissões de backup (se `permissions` existir) |
+
+## Testes (não executados)
+
+`runtime/src/test/java/br/com/seedgrid/backup/` (Quarkus DevServices PostgreSQL 16, migrations de teste em `db/testdata/backup`):
+- `controllers/ExportResourceIT` — endpoints REST; `controllers/ExportAsyncFlowIT` — pipeline assíncrono real com `SingleTenantBackupProvider` (perfil com `async-enabled=true`).
+- `exporters/CsvZipExporterIT`, `exporters/SqlDumpZipExporterIT` — geração de ZIP.
+- `services/ExtractDataServiceIT` — extração RAW/DOMAIN e exclusões; `services/ExportUserEventIT` — `SgUserEvent` após commit (sucesso/falha).
+- `configs/SingleTenantBackupProviderTest`, `utils/ChecksumUtilTest` — unitários.
+- Suporte: `TestTenantProvider` (`@Alternative @Priority(1)`), `TestCurrentUserProvider`, `support/SampleDomainEntity`.
+
+## Limitações
+
+- `options` do `ExportRequest` (mapa livre) é serializado no job e repassado ao `ExportContext` (`getOptions()`/`getOption(key, default)`); os exporters embutidos não leem nenhuma opção — só exporters customizados podem usá-lo. **Confirmado** (`ExportService#buildExportContext`).
+- Limpeza por retenção tem cron fixo (`0 1 0 * * ?`), não configurável. **Confirmado**.
+- Banco: PostgreSQL (migrations, `information_schema`, `gen_random_uuid()`).
+- `generateDownloadUrl` (URL assinada) lança `UnsupportedOperationException` no adapter padrão; download passa os bytes pela API.
+- Notificação por e-mail fica **ativa por padrão** apontando para `smtp.gmail.com` sem credenciais (fallbacks do `microprofile-config.properties`) — ver [[SeedGrid/Extensions/backup/Configuracao|Configuração]].
+- `appVersion("1.0.0")` fixo no manifest (TODO no código).

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

@@ -0,0 +1,86 @@
+---
+tags: [seedgrid, extension, billing, rust, configuracao]
+fonte: rust/seedgrid-rust-crate-billing
+branch: main
+commit: be738a2d1e
+analisado-em: 2026-10-14
+---
+
+# billing — Configuração Rust
+
+Visão do crate: [[SeedGrid/Extensions/billing/Rust|Porte Rust do billing]] · Java: [[SeedGrid/Extensions/billing/Configuracao|Configuração do billing (Java)]].
+
+## Cabeçalho
+| Item | Valor |
+|---|---|
+| Struct | `StripeConfig` (prefixo Java `seedgrid.billing.stripe`) — `rust/seedgrid-rust-crate-billing/src/config.rs` |
+| Mecanismo | `StripeConfig::from_env()` (`std::env::var`), ou struct montada pelo host |
+| Quem chama | `BillingPlatform::assemble` chama `StripeConfig::from_env()` |
+| Leitura | no boot (uma vez) |
+
+Helpers: `opt(name)` faz `trim` e trata vazio como ausente; `opt_any(names)` devolve o primeiro não vazio (primário antes do alias). `from_env` nunca falha: `api_key`/`webhook_secret` ausentes viram `""`.
+
+## Stripe
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| 🔒 `SEEDGRID_BILLING_STRIPE_APIKEY` / alias `SEEDGRID_BILLING_STRIPE_API_KEY` (Java `seedgrid.billing.stripe.apiKey`) | String | chave secreta Stripe | `""` | Sim para habilitar via `BillingPlatform` (vazio → `Ok(None)`, billing desligado) | `Authorization: Bearer`; prefixo `sk_test` habilita Test Clock | `stripe/provider.rs` (transporte, Test Clock), `platform.rs` | `test_clock_enabled` | `StripeConfig::from_env()` | `config.rs`; `platform.rs` → `assemble` |
+| 🔒 `SEEDGRID_BILLING_STRIPE_WEBHOOK_SECRET` (Java `webhookSecret`) | String | segredo `whsec_...` | `""` | Sim (na prática): sem ele a verificação de assinatura falha | verifica assinatura do webhook | `stripe/provider.rs` → `signature::construct_event` | — | `from_env()` | `config.rs`, `stripe/signature.rs` |
+| `SEEDGRID_BILLING_STRIPE_DEFAULT_SUCCESS_URL` / alias `SEEDGRID_BILLING_STRPE_DEFAULT_SUCCESS_URL` (Java `defaultSuccessUrl`) | String | URL | `""` | Não | usada no checkout quando o request não traz URL | `stripe/provider.rs` | grafia correta tem precedência (teste `default_success_url_accepts_strpe_typo_alias_with_stripe_precedence`) | `from_env()` | `config.rs` |
+| `SEEDGRID_BILLING_STRIPE_DEFAULT_CANCEL_URL` (Java `defaultCancelUrl`) | String | URL | `""` | Não | idem para cancelamento | `stripe/provider.rs` | — | `from_env()` | `config.rs` |
+| `SEEDGRID_BILLING_STRIPE_TEST_CLOCK_ENABLED` (Java `test-clock-enabled`) | bool | `true`/`false` (parse `bool`, após `trim`) | `true` | Não | com chave `sk_test`, cria a assinatura sob um Test Clock | `stripe/provider.rs` | `api_key` | `from_env()` | `config.rs`, `provider.rs` |
+| `SEEDGRID_BILLING_STRIPE_PRODUCT` (Java `seedgrid.billing.stripe.product`) | `Option<String>` | id de produto | — | Não | `ensure_product_bootstrap` garante o produto se definido | `stripe/bootstrap.rs` (host precisa chamar) | `product_name` | `from_env()` | `config.rs`, `bootstrap.rs` |
+| `SEEDGRID_BILLING_STRIPE_PRODUCT_NAME` (Java `product-name`) | `Option<String>` | texto | — | Não | nome do produto no bootstrap | `stripe/bootstrap.rs` | `product` | `from_env()` | idem |
+| `SEEDGRID_BILLING_STRIPE_API_BASE` | String | URL | `https://api.stripe.com` (`DEFAULT_STRIPE_API_BASE`) | Não | base da API (útil em testes/mocks) | `stripe/provider.rs` | sem equivalente Java | `from_env()` | `config.rs` |
+
+Mapeamento Java ↔ env: os nomes Java vêm de `@ConfigProperty` em `java/seedgrid-quarkus-ext-billing/seedgrid-billing-stripe/runtime/.../StripeBillingProvider.java` e `StripeProductBootstrap.java` (**Confirmado**). Os nomes de env do Rust **não** seguem exatamente a regra MicroProfile para chaves camelCase (ex.: `apiKey` → `SEEDGRID_BILLING_STRIPE_APIKEY`), são convenção do projeto (doc de `config.rs`).
+
+## Structs
+| Campo | `Default` |
+|---|---|
+| `StripeConfig.api_key`, `webhook_secret`, `default_success_url`, `default_cancel_url` | `""` |
+| `StripeConfig.test_clock_enabled` | `true` |
+| `StripeConfig.product`, `product_name` | `None` |
+| `StripeConfig.api_base` | `https://api.stripe.com` |
+
+## Features Cargo
+| Feature | Padrão | Efeito |
+|---|---|---|
+| `postgres` | sim | `PgBillingEventRepository`, `migrate`, `MIGRATOR` |
+| `stripe` | sim | módulo `stripe` (provider, assinatura, bootstrap) |
+| `postgres` + `stripe` | — | habilitam `BillingPlatform`/`BillingOverrides` |
+
+## Configuração não-env
+- `BillingApiStateBuilder::authorizer(...)` (default `AllowAllBillingAuthorizer`).
+- Rate limits fixos em código (`checkout_rate_limit`, `portal_rate_limit`, `webhook_rate_limit`); ver [[SeedGrid/Extensions/resilience/Configuracao-Rust|Configuração Rust do resilience]].
+
+## Somente testes
+| Variável | Onde |
+|---|---|
+| `BILLING_IT_PG_URL` | `tests/pg_billing_events_it.rs` |
+| `BILLING_STRIPE_IT_BASE`, 🔒 `BILLING_STRIPE_IT_KEY` | `tests/stripe_transport_it.rs` |
+
+## Configuração mínima
+```dotenv
+SEEDGRID_BILLING_STRIPE_APIKEY=<SEGREDO:stripe-api-key>
+SEEDGRID_BILLING_STRIPE_WEBHOOK_SECRET=<SEGREDO:stripe-webhook-secret>
+```
+
+## Configuração completa comentada
+```dotenv
+SEEDGRID_BILLING_STRIPE_APIKEY=<SEGREDO:stripe-api-key>          # alias: SEEDGRID_BILLING_STRIPE_API_KEY
+SEEDGRID_BILLING_STRIPE_WEBHOOK_SECRET=<SEGREDO:stripe-webhook-secret>
+SEEDGRID_BILLING_STRIPE_DEFAULT_SUCCESS_URL=https://<app>/assinatura?ok=1   # alias legado: ..._STRPE_...
+SEEDGRID_BILLING_STRIPE_DEFAULT_CANCEL_URL=https://<app>/assinatura?cancel=1
+SEEDGRID_BILLING_STRIPE_TEST_CLOCK_ENABLED=true   # só tem efeito com chave sk_test
+SEEDGRID_BILLING_STRIPE_PRODUCT=<id-produto>      # bootstrap (host chama ensure_product_bootstrap)
+SEEDGRID_BILLING_STRIPE_PRODUCT_NAME=<nome>
+# SEEDGRID_BILLING_STRIPE_API_BASE=https://api.stripe.com
+```
+
+## Receitas
+- **Habilitar com Stripe**: definir a API key e o webhook secret; `BillingPlatform::assemble(Some(&pool), BillingOverrides::default())`; montar `router(state)` e acoplar os rate limits.
+- **Testes E2E com tempo avançado**: chave `sk_test_...` e `SEEDGRID_BILLING_STRIPE_TEST_CLOCK_ENABLED=true`.
+- **Mock do Stripe**: `SEEDGRID_BILLING_STRIPE_API_BASE=http://localhost:<porta>`.
+
+## Dúvidas e lacunas
+- Grupos de config do billing-core Java atual (`trial`, `catalog`, `checkout`, `portal`, `access-gate`, `feature-gate`, `reconciliation`, `api`, `business-timezone`, `currency`, …) **não existem** no Rust.