@seedgrid/ai-toolkit 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,66 @@
+---
+tags: [seedgrid, extension, audit, enum]
+fonte: java/seedgrid-quarkus-ext-audit
+branch: main
+commit: d5bf32e509
+analisado-em: 2026-10-14
+---
+
+# SeedGrid Audit — Enums
+
+Voltar: [[SeedGrid/Extensions/audit/Visao-geral|Visão geral do audit]] · [[SeedGrid/Extensions/audit/Configuracao|Configuração]] · [[SeedGrid/Extensions/audit/Rust|Porte Rust]]
+
+## Índice
+
+| Enum | Pacote/arquivo | Usado em | Público? |
+|---|---|---|---|
+| [[#AuditOperationEnum]] | `seedgrid-quarkus-ext-audit-core/runtime/src/main/java/br/com/seedgrid/audit/core/enums/AuditOperationEnum.java` | `@Audit(operation)`, `AuditLog.operation`, query param `operation` de `GET /audit-logs`, coluna `audit_log.operation`, campo Mongo `operation` | Sim |
+| [[#AuditPersistenceStrategy]] | `seedgrid-quarkus-ext-audit-core/runtime/src/main/java/br/com/seedgrid/audit/core/configs/AuditPersistenceStrategy.java` | propriedade `seedgrid.audit.persistence.strategy`, SPI `AuditPersistenceProvider#strategy()` | Sim |
+
+## AuditOperationEnum
+
+FQN: `br.com.seedgrid.audit.core.enums.AuditOperationEnum`. Sem campos, construtor ou métodos próprios.
+
+| Valor | Significado | Efeito / onde é tratado | Observações |
+|---|---|---|---|
+| `CREATE` | Criação de entidade | `AuditInterceptor#around`: captura só o estado **depois** (`afterState`), a partir do retorno ou de um novo lookup. **Confirmado** | — |
+| `UPDATE` | Alteração de entidade | Captura **antes** (lookup antes de `proceed()`) e **depois**. **Confirmado** | — |
+| `DELETE` | Exclusão de entidade | Captura só o estado **antes**. **Confirmado** | — |
+| `READ` | Leitura/consulta | Nenhum tratamento específico: registra o evento sem before/after. **Confirmado** | — |
+| `OTHER` | Operação genérica | Igual a `READ` (sem before/after). É o **padrão** de `@Audit(operation)`. **Confirmado** | — |
+
+Comportamento comum: quando `@Audit(description)` está vazia, a descrição gravada é `operation.name()` (ex.: `UPDATE`). **Confirmado** (`AuditInterceptor#around`).
+
+Serialização:
+- JSON (respostas de `/audit-logs`): nome da constante (Jackson padrão; sem `@JsonValue`). **Inferência** (nenhuma anotação Jackson no enum).
+- Query param `operation` em `GET /audit-logs`: convertido pelo JAX-RS pelo nome exato (`valueOf`), portanto case-sensitive; valor inválido falha a conversão do parâmetro. **Inferência** (comportamento padrão do JAX-RS; sem `ParamConverter` próprio).
+- PostgreSQL: `@Enumerated(EnumType.STRING)` em `AuditLogEntity#operation`; coluna `operation VARCHAR(50)` (V300) **sem CHECK constraint** — o banco aceita qualquer texto, mas a aplicação só grava as 5 constantes. **Confirmado**.
+- MongoDB: campo `operation` do documento `MongoAuditLogDocument` (coleção `audit_logs`), gravado pelo codec POJO como o nome da constante. **Inferência** (sem codec próprio no módulo).
+
+Onde é usado: anotação `@Audit` ([[SeedGrid/Extensions/audit/Exemplos|Exemplos]]), filtro `AuditFilter#operation` (JPQL/Criteria em `JpaAuditRepositoryImpl`, filtro Mongo em `MongoAuditLogRepositoryImpl`), índice `idx_audit_log_operation_date`.
+
+## AuditPersistenceStrategy
+
+FQN: `br.com.seedgrid.audit.core.configs.AuditPersistenceStrategy`. Sem campos/métodos próprios; `AuditConfig#isMongo()/isJpa()` comparam com as constantes.
+
+| Valor | Significado | Efeito / onde é tratado | Observações |
+|---|---|---|---|
+| `MONGODB` | Persistência documental no MongoDB | `AuditPersistenceRouter#resolveProvider()` escolhe o provider com `strategy() == MONGODB` (`MongoAuditPersistenceProvider`, módulo `seedgrid-audit-mongodb`). **Confirmado** | Default do módulo mongodb: `${AUDIT_STRATEGY:MONGODB}` |
+| `JPA` | Persistência relacional (PostgreSQL) via Hibernate/JPA | Escolhe `PostgreSqlAuditPersistenceProvider` (módulo `seedgrid-audit-postgresql`); habilita `seedgrid.audit.jpa.*` (`AuditConfig#effectiveJpa*`). **Confirmado** | `@WithDefault("JPA")`; default do módulo postgresql: `${AUDIT_STRATEGY:JPA}` |
+
+Se nenhum `AuditPersistenceProvider` do classpath retornar o valor configurado → `IllegalStateException("No audit persistence provider available for strategy ...")` na primeira injeção dos repositórios. **Confirmado**.
+
+Leitura da config: conversor de enum do SmallRye Config; o javadoc do código afirma que é case-insensitive (`jpa` aceito), com constantes canônicas `JPA` e `MONGODB`. **Confirmado** (javadoc de `AuditConfig.Persistence#strategy` e do enum). Não é persistido nem serializado em JSON.
+
+Onde é usado: [[SeedGrid/Extensions/audit/Configuracao|`seedgrid.audit.persistence.strategy`]]; SPI `AuditPersistenceProvider#strategy()`.
+
+## Internos
+
+| Enum | Arquivo |
+|---|---|
+| `AuditInterceptor.LookupType` (`NONE`, `BY_METHOD`, `BY_FIELDS`, `BY_ID`) | `seedgrid-quarkus-ext-audit-core/runtime/src/main/java/br/com/seedgrid/audit/core/interceptors/AuditInterceptor.java` |
+
+## Comparação com o porte Rust (informativo)
+
+- `AuditOperationEnum` ↔ `AuditOperation` (`rust/seedgrid-rust-crate-audit/src/models.rs`, `#[serde(rename_all = "UPPERCASE")]`): mesmos 5 valores, mesma grafia.
+- `AuditPersistenceStrategy` ↔ `AuditPersistenceStrategy` (`rust/seedgrid-rust-crate-audit/src/config.rs`, variantes `Jpa`/`Mongodb`): o `parse` do Rust também aceita os aliases `POSTGRES`, `POSTGRESQL` e `MONGO`, que o Java não aceita.

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

@@ -0,0 +1,151 @@
+---
+tags: [seedgrid, extension, audit, exemplos]
+fonte: java/seedgrid-quarkus-ext-audit
+branch: main
+commit: d5bf32e509
+analisado-em: 2026-10-14
+---
+
+# SeedGrid Audit — Exemplos
+
+Voltar: [[SeedGrid/Extensions/audit/Visao-geral|Visão geral do audit]] · [[SeedGrid/Extensions/audit/Configuracao|Configuração do audit]]
+
+Fontes: `java/seedgrid-quarkus-ext-audit/README.md` (seção "Como usar"), assinaturas em `seedgrid-quarkus-ext-audit-core/runtime/src/main/java/br/com/seedgrid/audit/core/**`. Configuração de propriedades: ver a nota de Configuração (não repetida aqui).
+
+## 1. Dependência Maven (strategy JPA)
+
+```xml
+<dependency>
+    <groupId>br.com.seedgrid</groupId>
+    <artifactId>seedgrid-audit-postgresql</artifactId>
+    <version>2026.09.25</version>
+</dependency>
+```
+Para MongoDB troque por `seedgrid-audit-mongodb`. Versão conforme pom no commit analisado.
+
+## 2. Auditar CREATE/UPDATE (README)
+
+```java
+import br.com.seedgrid.audit.core.annotations.Audit;
+import br.com.seedgrid.audit.core.enums.AuditOperationEnum;
+
+@ApplicationScoped
+public class UserService {
+
+    @Transactional
+    @Audit(entityFqcn = "br.com.seuapp.entities.User",
+           operation = AuditOperationEnum.CREATE,
+           description = "Cria novo usuário")
+    public User createUser(User user) {
+        return user; // estado "depois" capturado após proceed()
+    }
+
+    @Transactional
+    @Audit(entityFqcn = "br.com.seuapp.entities.User",
+           operation = AuditOperationEnum.UPDATE,
+           description = "Atualiza usuário")
+    public User updateUser(Long id, User user) { // antes (lookup por @Id Long) + depois
+        return user;
+    }
+}
+```
+O repository usado no lookup é derivado: `br.com.seuapp.entities.User` → `br.com.seuapp.repositories.UserRepository` (precisa expor `findByIdOptional`, ou `find(String, Object...)` para lookups por campo).
+
+## 3. Lookup explícito
+
+```java
+// Por método do repository
+@Audit(entityFqcn = "br.com.seuapp.entities.LegacyPerson",
+       operation = AuditOperationEnum.READ,
+       lookupMethod = "findByDocument")
+public LegacyPerson findByDocument(String document) { ... }
+
+// Por campos, na ordem dos argumentos: "tenantId = ?1 and publicId = ?2"
+@Audit(entityFqcn = "br.com.seuapp.entities.Customer",
+       operation = AuditOperationEnum.UPDATE,
+       lookups = { @AuditLookup(field = "tenantId"), @AuditLookup(field = "publicId") })
+public Customer update(String tenantId, String publicId, Customer input) { ... }
+```
+Usar `lookupMethod` e `lookups` juntos falha o build (`AuditProcessor`).
+
+## 4. Mascaramento (delegado ao seedgrid-privacy)
+
+```java
+import br.com.seedgrid.privacy.masking.MaskRule;
+import br.com.seedgrid.privacy.masking.MaskingStrategy;
+import br.com.seedgrid.privacy.masking.PersonalData;
+
+public class User {
+    @PersonalData(type = MaskingStrategy.PARTIAL, maskWith = "2")
+    private String cpf;
+}
+
+@Audit(entityFqcn = "br.com.seuapp.entities.User",
+       operation = AuditOperationEnum.UPDATE,
+       options = { @MaskRule(field = "password", remove = true) })
+public User update(Long id, User u) { ... }
+```
+Fonte: README e `AuditMaskingTest`. Detalhes das estratégias: [[SeedGrid/Extensions/privacy/Visao-geral|privacy]].
+
+## 5. Auditoria programática
+
+```java
+import br.com.seedgrid.audit.core.entities.AuditLog;
+import br.com.seedgrid.audit.core.enums.AuditOperationEnum;
+import br.com.seedgrid.audit.core.services.AuditEmitter;
+
+AuditLog log = new AuditLog();
+log.setOperation(AuditOperationEnum.OTHER);
+log.setEntity("Report");
+log.setDescription("Exportação de relatório");
+log.setUserName("job-scheduler");
+log.setOperationDateTime(java.time.Instant.now());
+AuditEmitter.emit(log); // best-effort: nunca lança; usa AuditGateway (enriquece + persiste)
+```
+Alternativa: injetar `AuditGateway` e chamar `persist(log)`. Fonte: `AuditEmitter`, `AuditGatewayImpl`, setters de `AuditLog`.
+
+## 6. Contribuir metadata (SPI)
+
+```java
+import br.com.seedgrid.audit.core.services.AuditMetadataContributor;
+
+@RequestScoped
+public class CompanyAuditMetadata implements AuditMetadataContributor {
+    @Inject JsonWebToken jwt;
+
+    @Override
+    public Map<String, String> contribute() {
+        String company = jwt.getClaim("companyPublicId"); // nome do claim é do host
+        return company == null ? Map.of() : Map.of("companyPublicId", company);
+    }
+}
+```
+Todas as implementações são mescladas (`AuditEnricher`); contribuidor que lança é ignorado. Filtro: `GET /audit-logs?metaKey=companyPublicId&metaValue=<uuid>`.
+
+## 7. Forçar escopo de leitura (SPI)
+
+```java
+import br.com.seedgrid.audit.core.spi.AuditReadScope;
+import br.com.seedgrid.audit.core.spi.AuditReadScopeProvider;
+
+@ApplicationScoped // sem @DefaultBean: vence DefaultAuditReadScopeProvider
+public class TenantAuditReadScope implements AuditReadScopeProvider {
+    @Override
+    public AuditReadScope resolveReadScope() {
+        String company = /* obter do contexto de segurança */ null;
+        return company == null ? AuditReadScope.unrestricted()
+                               : AuditReadScope.of("companyPublicId", company);
+    }
+}
+```
+Com escopo restrito, `AuditLogController` sobrescreve `metaKey/metaValue` do cliente e responde 404 em `/audit-logs/{id}` fora do escopo.
+
+## 8. Leitura REST
+
+```http
+GET /audit-logs?entity=User&operation=UPDATE&operationDateFrom=2026-06-01&page=0&size=20
+GET /audit-logs/42
+GET /audit-logs/entities
+GET /audit-logs/users
+```
+Exige permissão `LOG_READ`.

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

@@ -0,0 +1,120 @@
+---
+tags: [seedgrid, extension, audit, rust]
+fonte: rust/seedgrid-rust-crate-audit
+branch: main
+commit: be738a2d1e
+analisado-em: 2026-10-14
+---
+
+# audit — porte Rust (`seedgrid-rust-crate-audit`)
+
+Porte da extensão Quarkus `seedgrid-quarkus-ext-audit` (módulos `audit-core`, `audit-postgresql`, `audit-mongodb`). Lado Java: [[SeedGrid/Extensions/audit/Visao-geral|Visão geral do audit (Java)]] · [[SeedGrid/Extensions/audit/Configuracao|Configuração do audit (Java)]]. Configuração Rust: [[SeedGrid/Extensions/audit/Configuracao-Rust|Configuração Rust do audit]].
+
+Trilha de auditoria (snapshot *before/after*) com mascaramento de PII, backends PostgreSQL (sqlx) e MongoDB e um router Axum de leitura. **Confirmado** (`rust/seedgrid-rust-crate-audit/src/lib.rs`).
+
+## Identificação
+| Item | Valor |
+|---|---|
+| Pacote Cargo | `seedgrid-rust-crate-audit` (lib `seedgrid_audit`) |
+| Versão | herdada do workspace: `2026.10.14` (`rust/Cargo.toml` → `[workspace.package]`). |
+| Edição / MSRV | 2021 / 1.82 |
+| Features | `postgres` (default, `sqlx`), `mongodb` (`mongodb` + `bson`) |
+| Dependência SeedGrid | `seedgrid-rust-crate-privacy` (motor de mascaramento; o módulo `masking` re-exporta `seedgrid_privacy::masking`) |
+| Consumidores no workspace | security, backup, login-tenancy, subdomain-tenancy |
+
+## Arquitetura (diferença em relação ao Java)
+No Java a captura vem do interceptor CDI `@Audit`. Em Rust **não há interceptor**: o consumidor monta um `AuditEvent` e chama `Auditor::record`. A crate então: (1) deriva `entity` = nome simples do FQCN; (2) mascara `before_state`/`after_state` com as `MaskRule`s do evento; (3) preenche usuário, timestamp, origin, IP, user-agent e metadata pelos SPIs; (4) faz *upsert* dos índices `entities`/`users`; (5) persiste. Escritas são best-effort: erros são logados e engolidos. **Confirmado** (`src/lib.rs`, `src/state.rs`).
+
+As validações build-time do `AuditProcessor` do Quarkus (`@Audit(entityFqcn=...)`, `lookupMethod`/`lookups`) não existem em Rust; estão só como doc comments em `src/lib.rs`.
+
+## API pública principal
+| Símbolo | Papel | Fonte |
+|---|---|---|
+| `AuditConfig`, `AuditPersistenceStrategy`, `default_strategy()` | Config (ver [[SeedGrid/Extensions/audit/Configuracao-Rust\|Configuração Rust]]) | `src/config.rs` |
+| `AuditState::postgres(pool, cfg)` / `AuditState::mongodb(db, cfg)` | Construtores; retornam `Result` e validam que `cfg.strategy` casa com o backend (`validate_strategy`) | `src/state.rs` |
+| `AuditState::builder(config, repo, entities_repo, users_repo)` → `AuditStateBuilder` | Montagem com repositórios arbitrários; `.request_context(..)`, `.metadata_contributor(..)`, `.read_scope(..)`, `.read_authorizer(..)`, `.build()` | `src/state.rs` |
+| trait `Auditor` (`record(event, ctx)`) | Seam de escrita | `src/state.rs` |
+| `AuditEvent` (`new`, `description`, `before_state`, `after_state`, `mask_rule(s)`, `tech_operation`) | Evento montado pelo consumidor | `src/models.rs` |
+| `AuditContext` (`user`, `request`, `metadata`) | Contexto da escrita; `metadata` direta vence os contribuidores (adição do Rust, D8) | `src/state.rs` |
+| `AuditFilter`, `PageReq`, `PageResult` (serializa `items`) | Leitura/paginação | `src/models.rs` |
+| `migrate(&PgPool)` / `MIGRATOR` | Migrations `0300`–`0302`, histórico isolado `_sqlx_migrations_audit` | `src/lib.rs`, `src/migrations.rs` |
+| `router(state)` / `router_with_resolver(resolver, authorizer)` | Router Axum (único ou resolvido por tenant) | `src/routes.rs` |
+| `openapi()` | Spec utoipa da crate | `src/apidoc.rs` |
+| `AuditPlatform::assemble(Option<&PgPool>)` | Montagem "estilo CDI" a partir do ambiente (só com feature `postgres`) | `src/platform.rs` |
+| Repositórios `PgAuditLog*Repository`, `MongoAuditLog*Repository`; traits `AuditLogRepository`, `AuditLogEntitiesRepository`, `AuditLogUsersRepository` | Persistência | `src/postgres.rs`, `src/mongodb.rs`, `src/repo.rs` |
+
+### SPIs (todos com default, substituíveis no builder)
+| Trait | Default | Observação |
+|---|---|---|
+| `AuditRequestContextProvider` | `HttpAuditRequestContextProvider` | origin = `Origin` → `Referer` → `Host`; IP = 1º hop de `X-Forwarded-For` |
+| `AuditMetadataContributor` | nenhum | falhas ignoradas |
+| `AuditReadScopeProvider` | `DefaultAuditReadScopeProvider` (irrestrito) | pode forçar `metaKey`/`metaValue` (isolamento por company) |
+| `AuditReadAuthorizer` | **`DenyAllAuditReadAuthorizer`** (403) | porta `@PermissionsAllowed("LOG_READ")`; `AllowAllAuditReadAuthorizer` é opt-in inseguro |
+| `AuditStateResolver` | — | resolve o `AuditState` do tenant corrente; `None` → 503 |
+
+**Confirmado** (`src/spi.rs`).
+
+## Endpoints (router Axum)
+| Método | Path | Descrição |
+|---|---|---|
+| GET | `/audit-logs` | lista; com `page` ou `size` → `PageResult` (`{items,total,page,size}`); filtros `idFrom, idTo, entity, operation, description, operationDateFrom, operationDateTo, userName, metaKey, metaValue` |
+| GET | `/audit-logs/{id}` | 404 se fora do escopo de leitura |
+| GET | `/audit-logs/entities` | entidades distintas |
+| GET | `/audit-logs/users` | usuários distintos |
+
+Fonte: `src/routes.rs` → `router`, `router_with_resolver`.
+
+## Persistência
+- Postgres: migrations `migrations/0300_create_audit_tables.sql`, `0301_add_tech_operation.sql`, `0302_add_metadata.sql` (portadas de V300–V302); metadata em EAV `audit_log_metadata`.
+- Mongo: coleções `audit_logs`, `audit_log_entities`, `audit_log_users`; `sequentialId` via contador `counters` (`_id="audit_log_sequence"`).
+
+## Exemplo (de `rust/examples/seedgrid-audit-example/src/main.rs`)
+```rust
+use seedgrid_audit::{AuditConfig, AuditContext, AuditEvent, AuditOperation, Auditor, MaskRule};
+
+seedgrid_audit::migrate(&pool).await?;
+let state = seedgrid_audit::AuditState::postgres(pool.clone(), AuditConfig::from_env())?;
+
+let event = AuditEvent::new("br.com.seedgrid.example.Cliente", AuditOperation::Create)
+    .description("cadastro de cliente")
+    .after_state(serde_json::json!({ "cpf": "12345678900", "nome": "Joao Silva" }))
+    .mask_rule(MaskRule::format("cpf", "***.***.***-**"));
+state
+    .record(event, AuditContext::new().user("maria").metadata("companyPublicId", company))
+    .await; // best-effort: não retorna erro
+```
+Para expor a leitura: `axum::Router::new().merge(seedgrid_audit::router(state))` — lembrando que, sem `read_authorizer`, toda leitura responde 403.
+
+## Testes
+- Unitários em `src/*` (mascaramento, filtros, enum, `config` — default de estratégia por feature).
+- `tests/pg_metadata_it.rs` e `tests/mongo_metadata_it.rs`: `#[ignore]`, só rodam com `AUDIT_IT_PG_URL` / `AUDIT_IT_MONGO_URI`.
+- E2E Testcontainers no exemplo: `rust/examples/seedgrid-audit-example/tests/audit_e2e.rs`.
+- **Não executados** nesta análise.
+
+## Notas de comportamento
+
+- `enabled=false` faz `Auditor::record` virar no-op.
+- Leitura é deny-by-default.
+- O consumidor preenche `AuditEvent::tech_operation`.
+- A estratégia padrão deriva da feature Cargo; não há router dinâmico entre dois backends.
+
+## Lacunas
+- No modo JPA a conexão vem do `PgPool` do host; `SEEDGRID_AUDIT_DB_URL` só é usada por `AuditConfig::pg_connection_url()`, que nenhuma crate do workspace chama.
+
+## Enums
+Equivalentes Java e comparação detalhada: [[SeedGrid/Extensions/audit/Enums|Enums do audit (Java)]].
+
+| Enum | Arquivo | Java equivalente |
+|---|---|---|
+| `AuditOperation` | `src/models.rs` | [[SeedGrid/Extensions/audit/Enums#AuditOperationEnum\|AuditOperationEnum]] |
+| `AuditPersistenceStrategy` | `src/config.rs` | [[SeedGrid/Extensions/audit/Enums#AuditPersistenceStrategy\|AuditPersistenceStrategy]] |
+| `AuditError` | `src/error.rs` | exceções do audit (sem enum Java) |
+
+### AuditOperation
+Variantes: `Create`, `Update`, `Delete`, `Read`, `Other`. `#[serde(rename_all = "UPPERCASE")]` → JSON `"CREATE"`…`"OTHER"`. `name()`/`Display` devolvem o nome em maiúsculas (usado como `description` padrão); `FromStr` aceita qualquer caixa e erra com `AuditOperation invalida: X`. Persistida como `VARCHAR(50)` com o nome (sem CHECK constraint em `migrations/0300`); valor desconhecido lido do banco falha. Valores **iguais** ao Java (`@Enumerated(STRING)`).
+
+### AuditPersistenceStrategy
+Variantes: `Jpa` (padrão do enum), `Mongodb`. Sem serde. `parse(&str)` (trim, case-insensitive): `JPA`/`POSTGRES`/`POSTGRESQL` → `Jpa`; `MONGODB`/`MONGO` → `Mongodb`; outro → `None` (cai no default da feature). Lido de `AUDIT_STRATEGY` ([[SeedGrid/Extensions/audit/Configuracao-Rust|Configuração Rust]]). Nota: o Java só tem `JPA` e `MONGODB`; os aliases `POSTGRES`/`POSTGRESQL`/`MONGO` existem só no Rust. O default depende da feature compilada (`default_strategy()`).
+
+### AuditError
+`NotFound(i64)` e `OutOfScope` → 404; `Forbidden(String)` → 403; `Config`, `Json`, `Internal`, `Database` (feature `postgres`), `Mongo` (feature `mongodb`) → 500 (`AuditError::status`).

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

@@ -0,0 +1,114 @@
+---
+tags: [seedgrid, extension, audit]
+fonte: java/seedgrid-quarkus-ext-audit
+branch: main
+commit: d5bf32e509
+analisado-em: 2026-10-14
+---
+
+# SeedGrid Audit (Quarkus) — Visão geral
+
+Trilha de auditoria declarativa: um método (ou classe) anotado com `@Audit` é interceptado; a extensão registra quem, o quê, quando, de onde (origin/IP/User-Agent) e o estado **antes/depois** da entidade, com mascaramento de dados pessoais delegado à lib `seedgrid-privacy`. Persistência plugável em PostgreSQL (JPA) ou MongoDB e API REST de leitura. **Confirmado** (`AuditInterceptor`, `README.md`).
+
+- Configuração: [[SeedGrid/Extensions/audit/Configuracao|Configuração do audit]]
+- Exemplos: [[SeedGrid/Extensions/audit/Exemplos|Exemplos do audit]]
+- Enums: [[SeedGrid/Extensions/audit/Enums|Enums do audit]]
+- [[SeedGrid/Extensions/audit/Rust|Porte Rust]] (crate `seedgrid-rust-crate-audit`)
+
+## Módulos Maven e coordenadas
+
+Todos com `groupId` `br.com.seedgrid`. Agregador `seedgrid-audit` versão **`2026.09.25`** (parent `seedgrid-parent` 2026.07.02). **Confirmado** (`pom.xml`).
+
+| Módulo (pasta) | artifactId | Tipo |
+|---|---|---|
+| `seedgrid-quarkus-ext-audit-core/runtime` | `seedgrid-audit-core` | biblioteca runtime (sem deployment próprio, sem `quarkus-extension.properties`) |
+| `seedgrid-quarkus-ext-audit-postgresql/runtime` | `seedgrid-audit-postgresql` | extensão Quarkus (strategy `JPA`) |
+| `seedgrid-quarkus-ext-audit-postgresql/deployment` | `seedgrid-audit-postgresql-deployment` | deployment |
+| `seedgrid-quarkus-ext-audit-mongodb/runtime` | `seedgrid-audit-mongodb` | extensão Quarkus (strategy `MONGODB`) |
+| `seedgrid-quarkus-ext-audit-mongodb/deployment` | `seedgrid-audit-mongodb-deployment` | deployment |
+
+O host adiciona **apenas** o módulo da strategy (`seedgrid-audit-postgresql` ou `seedgrid-audit-mongodb`); ambos já dependem de `seedgrid-audit-core`.
+
+### Dependências SeedGrid e de framework
+- `seedgrid-commons` e `seedgrid-privacy` (core). Ver [[SeedGrid/Extensions/commons/Visao-geral|commons]] e [[SeedGrid/Extensions/privacy/Visao-geral|privacy]].
+- Core: `quarkus-arc`, `quarkus-jackson`, `quarkus-rest-jackson`, `quarkus-smallrye-jwt`, `quarkus-hibernate-validator`, `quarkus-smallrye-openapi`.
+- PostgreSQL: `quarkus-jdbc-postgresql`, `quarkus-flyway`. MongoDB: `quarkus-mongodb-panache`.
+- Integração opcional (por SPI, sem dependência Maven): `seedgrid-security` / `seedgrid-login-tenancy` (usuário corrente, metadata `companyPublicId`, escopo de leitura). **Inferência** a partir de comentários/README.
+
+## Arquitetura e fluxo
+
+```mermaid
+sequenceDiagram
+    participant C as Chamador
+    participant I as AuditInterceptor
+    participant M as Método @Audit
+    participant P as PersonalDataSanitizer (privacy)
+    participant E as AuditEnricher
+    participant S as AuditLogService (REQUIRES_NEW)
+    C->>I: invoca
+    I->>I: resolve entityFqcn, usuário (SecurityIdentity ou "anonymous")
+    alt UPDATE/DELETE
+        I->>I: lookup "antes" (repository derivado ou EntityManager)
+        I->>P: sanitizeToJson(antes)
+    end
+    I->>M: ctx.proceed()
+    alt CREATE/UPDATE
+        I->>P: sanitizeToJson(depois)
+    end
+    I->>E: enrich (origin/IP/UA + metadata SPI)
+    I->>S: persist(AuditLog)
+```
+
+- Interceptor: `@Audit` é `@InterceptorBinding`; `AuditInterceptor` tem `@Priority(APPLICATION + 200)`. Lê a anotação no método ou, em fallback, na classe. **Confirmado**.
+- Resolução do repositório: `entityFqcn` com pacote `.entities` → `.repositories` + sufixo `Repository`. Plano de lookup: `lookupMethod` → `lookups` → `publicId` (se herda `br.com.seedgrid.commons.persistence.BaseEntity`/`BaseEntityPanache`) → `@Id` compatível com o 1º argumento. Sem repository derivável, usa `EntityManager` (active-record). **Confirmado** (`AuditInterceptor#resolveLookupPlan`, `#findViaActiveRecord`).
+- Roteamento de persistência: `AuditPersistenceRouter` produz `AuditLogRepository`, `AuditLogUsersRepository`, `AuditLogEntitiesRepository` a partir do `AuditPersistenceProvider` cuja `strategy()` = `seedgrid.audit.persistence.strategy`. Sem provider → `IllegalStateException`. **Confirmado**.
+- `PostgreSqlAuditPersistenceProvider`: usa o `EntityManager` CDI do host se resolvível; senão cria um `EntityManagerFactory` standalone (`audit-pu`, `PGSimpleDataSource`, dialeto PostgreSQL) a partir de `seedgrid.audit.jpa.*`. **Confirmado**.
+- `MongoAuditPersistenceProvider`: usa `Instance<MongoDatabase>`; coleções `audit_logs`, `audit_log_users`, `audit_log_entities` e `counters` (sequência `audit_log_sequence`); índices criados de forma lazy. **Confirmado**. A extensão **não produz** um bean `MongoDatabase`: ele vem de `seedgrid-login-tenancy` (`LoginTenancyMongoAuditDatabaseProducer`, banco único, registrado só com o driver Mongo no classpath), de `seedgrid-subdomain-tenancy` (`TenantAwareMongoProducer`, banco por tenant), ambos `@DefaultBean`, ou de um producer da aplicação. **Confirmado**.
+- Validação em build (`AuditProcessor#validateAuditUsage`, idêntico nos dois deployments): falha o build se `entityFqcn` vazio/inexistente, se `lookupMethod` e `lookups` forem usados juntos, se um campo de `lookups` não existir, se houver mais lookups que parâmetros, ou se o lookup implícito por PK for incompatível; avisa (warn) quando o repository derivado não existe. **Confirmado**.
+
+## APIs públicas e pontos de integração
+
+| Tipo | Símbolo | Descrição |
+|---|---|---|
+| Anotação | `br.com.seedgrid.audit.core.annotations.Audit` | `operation` (`AuditOperationEnum`, padrão `OTHER`), `description`, `entityFqcn` (obrigatório), `lookupMethod`, `lookups` (`AuditLookup[]`), `options` (`MaskRule[]` do privacy) |
+| Anotação | `AuditLookup` | `field()` |
+| Enum | `AuditOperationEnum` | `CREATE, UPDATE, DELETE, READ, OTHER` |
+| Enum | `AuditPersistenceStrategy` | `MONGODB, JPA` |
+| SPI | `core.spi.AuditPersistenceProvider` | liga strategy aos repositórios (fornecido pelos módulos de store) |
+| SPI | `core.services.AuditMetadataContributor` | `Map<String,String> contribute()` mesclado em `AuditLog.metadata` |
+| SPI | `core.spi.AuditReadScopeProvider` | força filtro `metaKey/metaValue` na leitura; default `DefaultAuditReadScopeProvider` (`@DefaultBean`, irrestrito) |
+| SPI | `core.services.AuditRequestContextProvider` | origin/IP/UA; default `HttpAuditRequestContextProvider` (`@DefaultBean`; usa `Origin`→`Referer`→`Host`, `X-Forwarded-For`) |
+| Bean | `core.services.AuditGateway` / `AuditGatewayImpl` (`@DefaultBean`) | `persist(AuditLog)` para auditoria programática (enriquece e persiste) |
+| Utilitário | `core.services.AuditEmitter#emit(AuditLog)` | estático, best-effort (nunca lança) via `AuditGateway` |
+
+### Endpoints REST (`AuditLogController`, todos `@PermissionsAllowed("LOG_READ")`)
+
+| Método | Path | Descrição |
+|---|---|---|
+| GET | `/audit-logs` | lista; paginada se `page`/`size` (padrão de página 0, tamanho 10). Filtros: `idFrom`, `idTo`, `entity`, `operation`, `description`, `operationDateFrom`, `operationDateTo`, `userName`, `metaKey`, `metaValue` |
+| GET | `/audit-logs/{id}` | por id; 404 se fora do escopo do `AuditReadScopeProvider` |
+| GET | `/audit-logs/entities` | nomes de entidades (escopados) |
+| GET | `/audit-logs/users` | usuários (escopados) |
+
+**Confirmado** (`RestControllerPath`, `AuditLogController`). Os paths são fixos (não configuráveis).
+
+## Migrations (PostgreSQL)
+
+`seedgrid-quarkus-ext-audit-postgresql/runtime/src/main/resources/db/migration/audit/`: `V300__create_audit_tables.sql`, `V301__add_tech_operation.sql`, `V302__add_metadata.sql` (tabela `audit_log_metadata`), `V303__operation_date_time_timestamptz.sql` (converte `operation_date_time` para `TIMESTAMPTZ` usando `AT TIME ZONE 'UTC'`). Faixa **V300–V303**, tabela de histórico `flyway_schema_history_audit`. **Confirmado**. MongoDB não tem migrations.
+
+## Testes (não executados)
+
+| Local | Cobre |
+|---|---|
+| `audit-core/runtime/src/test/.../AuditInterceptorTest` | plano de lookup (publicId, lookups, lookupMethod, fallback por id) |
+| `audit-core/.../HttpAuditRequestContextProviderTest` | comportamento sem requisição HTTP e `X-Forwarded-For` |
+| `audit-core/.../AuditEnricherTest` | merge de metadata e tolerância a contribuidor com erro |
+| `audit-postgresql/deployment/src/test/.../AuditProcessorTest` | validação de lookup implícito por PK e derivação de repository |
+| `audit-postgresql/runtime/src/test/.../AuditMaskingTest` | mascaramento persistido no Postgres (Testcontainers) |
+| `audit-postgresql/runtime/src/test/.../JpaAuditMetadataIT` | metadata, filtros e paginação JPA (Testcontainers) |
+| `audit-mongodb/runtime/src/test/.../MongoAuditMetadataIT` | metadata em subdocumento e filtros (Testcontainers) |
+
+## Limitações
+- O standalone JPA só aceita URL `jdbc:postgresql:` (`IllegalArgumentException` caso contrário).
+- Se ambos os módulos (postgresql e mongodb) estiverem no classpath, os dois `microprofile-config.properties` definem `seedgrid.audit.persistence.strategy` com mesmo ordinal — resultado não determinado. **Não confirmado**.
+- Persistência em `REQUIRES_NEW`: o log é gravado mesmo que a transação principal falhe. Lookup que falha resulta em log sem before/after (warn/debug).

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

@@ -0,0 +1,136 @@
+---
+tags: [seedgrid, extension, backup, rust, configuracao]
+fonte: rust/seedgrid-rust-crate-backup
+branch: main
+commit: be738a2d1e
+analisado-em: 2026-10-14
+---
+
+# backup — Configuração Rust
+
+Visão do crate: [[SeedGrid/Extensions/backup/Rust|Porte Rust do backup]] · Java: [[SeedGrid/Extensions/backup/Configuracao|Configuração do backup (Java)]].
+
+## Cabeçalho
+| Item | Valor |
+|---|---|
+| Struct | `BackupConfig` (+ `NotificationConfig`, `MailerConfig`, `CsvConfig`, `FilesystemConfig`, `S3Config`, `MinioConfig`, `AzureBlobConfig`, `GoogleDriveConfig`, `OnedriveConfig`, `GcsConfig`) — `rust/seedgrid-rust-crate-backup/src/config.rs` |
+| Mecanismo | `BackupConfig::from_env()` parte de `BackupConfig::default()` e sobrescreve com env; ou struct montada pelo host |
+| Prefixo Java | `seedgrid.backup` (`BackupConfig.java`, `@ConfigMapping`) |
+| Quem chama `from_env` | `BackupPlatform::assemble` (`src/platform.rs`) |
+| Leitura | no boot, uma vez |
+
+Regras de leitura (`src/config.rs` → `env_any`): lista de nomes em ordem; vence o **primeiro nome com valor não vazio após `trim`**. Valor que não parseia (número, bool, duração) é ignorado e o default permanece. Booleanos (`env_bool_any`): `true/1/yes` e `false/0/no` (case-insensitive). Durações (`parse_duration`): `500ms`, `30s`, `5m`, `2h`, `1d` ou ISO-8601 `PT15M`, `P30D`, `P1DT2H` (sem anos/meses/semanas).
+
+## Habilitação (fora do `BackupConfig`)
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `SEEDGRID_BACKUP_ENABLED` / alias `BACKUP_ENABLED` | bool | `1`, `true`, `yes`, `on` (case-insensitive); qualquer outro = falso | falso (ausente) | Condicional: obrigatória `true` quando `BackupOverrides.require_opt_in` (default `true`) | sem opt-in, `BackupPlatform::assemble` devolve `Ok(None)` (backup desligado). Precedência: primeiro nome **definido** (mesmo vazio) | `BackupPlatform::assemble` | requer também `PgPool` | `assemble()` | `src/platform.rs` → `backup_opt_in` |
+
+Equivalente Java: não há `seedgrid.backup.enabled` no `BackupConfig.java` (**Confirmado** — o Java liga a extensão por presença no classpath).
+
+## Geral
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `BACKUP_RETENTION_DAYS` / alias `SEEDGRID_BACKUP_RETENTION_DAYS` (Java `seedgrid.backup.retention-days`) | i64 | inteiro | `7` | Não | `expires_at = agora + N dias` | `ExportService` (`src/service.rs`) | limpeza no scheduler | `from_env()` | `config.rs`; consumo `service.rs` |
+| `BACKUP_MAX_CONCURRENT_EXPORTS` / `SEEDGRID_BACKUP_MAX_CONCURRENT_EXPORTS` (Java `max-concurrent-exports`) | i64 | inteiro | `1` | Não | limite de exports simultâneos | `BackupScheduler::process_queued_exports` | — | `from_env()` | `scheduler.rs` |
+| `BACKUP_STORAGE` / `SEEDGRID_BACKUP_STORAGE` (Java `storage`, `${SEEDGRID_BACKUP_STORAGE:filesystem}`) | String | `filesystem`, `s3`, `minio`, `azure-blob`, `google-drive`, `onedrive`, `gcs` (case-insensitive) | `filesystem` | Não | outro valor → erro `Unknown storage type` em `build_storage_config` | `exporter.rs`, `storage.rs` | escolhe o bloco de storage | `from_env()` | `config.rs` → `build_storage_config` |
+| `BACKUP_QUEUE_POLL_INTERVAL` / `SEEDGRID_BACKUP_QUEUE_POLL_INTERVAL` (Java `queue-poll-interval`) | Duration | ver durações | `30s` | Não | intervalo do loop de fila | `BackupScheduler::spawn` | — | `from_env()` | `scheduler.rs` |
+| `BACKUP_ASYNC_ENABLED` / `SEEDGRID_BACKUP_ASYNC_ENABLED` (Java `async-enabled`) | bool | `true/1/yes`, `false/0/no` | `true` | Não | dispara worker assíncrono após criar o job | `ExportService::create_export_job` | — | `from_env()` | `service.rs` |
+
+## Notificação
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `BACKUP_NOTIFICATION_ENABLED` / `SEEDGRID_BACKUP_NOTIFICATION_ENABLED` (Java `notification.enabled`) | bool | idem | `true` | Não | desliga o loop de notificação e `is_enabled()` | `scheduler.rs`, `notification.rs` | exige `mailer.from` e `mailer.host` | `from_env()` | `config.rs` |
+| `BACKUP_NOTIFICATION_POLL_INTERVAL` / `SEEDGRID_BACKUP_NOTIFICATION_POLL_INTERVAL` (Java `notification.poll-interval`) | Duration | idem | `5m` | Não | intervalo do loop | `BackupScheduler::spawn` | — | `from_env()` | `scheduler.rs` |
+| `BACKUP_NOTIFICATION_MAX_RETRIES` / `SEEDGRID_BACKUP_NOTIFICATION_MAX_RETRIES` (Java `notification.max-retries`) | i32 (lido como i64) | inteiro | `3` | Não | máx. tentativas de e-mail | `process_notifications` | — | `from_env()` | `scheduler.rs`, `repo.rs` |
+| `BACKUP_NOTIFICATION_RETRY_DELAY` / `SEEDGRID_BACKUP_NOTIFICATION_RETRY_DELAY` (Java `notification.retry-delay`) | Duration | idem | `PT15M` | Não | atraso mínimo entre tentativas | `process_notifications` | — | `from_env()` | `scheduler.rs` |
+
+## Mailer (SMTP)
+Precedência invertida: **`SEEDGRID_BACKUP_MAILER_*` primeiro**, `BACKUP_MAILER_*` como alias (igual às `${...}` do `microprofile-config.properties` Java — **Confirmado**). Só sobrescreve o default quando a env existe e não é vazia.
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `SEEDGRID_BACKUP_MAILER_FROM` / `BACKUP_MAILER_FROM` (Java `mailer.from`) | `Option<String>` | e-mail | `noreply@example.com` | Não | remetente; ausente → erro no envio | `notification.rs` | entra em `is_enabled()` | `from_env()` | `config.rs`, `notification.rs` |
+| `SEEDGRID_BACKUP_MAILER_HOST` / `BACKUP_MAILER_HOST` (Java `mailer.host`) | `Option<String>` | host | `smtp.gmail.com` | Não | host SMTP | `SmtpMailer::from_config`, `is_enabled()` | — | `from_env()` | `email_smtp.rs` |
+| `SEEDGRID_BACKUP_MAILER_PORT` / `BACKUP_MAILER_PORT` (Java `mailer.port`) | `Option<u16>` | 1–65535 | `587` | Não | `465` → TLS implícito; senão STARTTLS | `SmtpMailer::from_config` | `start_tls` | `from_env()` | `email_smtp.rs` |
+| `SEEDGRID_BACKUP_MAILER_START_TLS` / `BACKUP_MAILER_START_TLS` (Java `mailer.start-tls`) | `Option<String>` | `REQUIRED`, `OPTIONAL`, `DISABLED` | `REQUIRED` | Não | só `DISABLED` muda o comportamento (texto puro) | `SmtpMailer::from_config` | — | `from_env()` | `email_smtp.rs` |
+| `SEEDGRID_BACKUP_MAILER_USERNAME` / `BACKUP_MAILER_USERNAME` (Java `mailer.username`) | `Option<String>` | texto | — | Condicional (para `MailerConfig::is_configured()`) | credencial SMTP | `SmtpMailer::from_config` | — | `from_env()` | `email_smtp.rs` |
+| 🔒 `SEEDGRID_BACKUP_MAILER_PASSWORD` / `BACKUP_MAILER_PASSWORD` (Java `mailer.password`) | `Option<String>` | texto | — | Condicional (idem) | credencial SMTP | `SmtpMailer::from_config` | — | `from_env()` | `email_smtp.rs` |
+
+`MailerConfig::is_configured()` = host + from + username + password presentes; usado por hosts para decidir `SmtpMailer` vs `LoggingMailer` (comentário em `src/email_smtp.rs`; o auto-wire fica no subdomain-tenancy — **Não confirmado** nesta análise).
+
+## CSV e filesystem
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `BACKUP_CSV_DELIMITER` / `SEEDGRID_BACKUP_CSV_DELIMITER` (Java `csv.delimiter`) | String | 1º byte é usado | `,` | Não | delimitador do CSV e do manifest | `exporter.rs` | — | `from_env()` | `exporter.rs` |
+| `BACKUP_CSV_QUOTE_CHAR` / `SEEDGRID_BACKUP_CSV_QUOTE_CHAR` (Java `csv.quote-char`) | String | 1º byte é usado | `"` | Não | aspas do CSV | `exporter.rs` | — | `from_env()` | `exporter.rs` |
+| `BACKUP_FILESYSTEM_BASE` / `SEEDGRID_BACKUP_FILESYSTEM_BASE_PATH` (Java `filesystem.base-path`) | String | caminho | `/var/seedgrid/files` | Não | `base-path` do storage filesystem | `build_storage_config("filesystem")` | — | `from_env()` | `config.rs` |
+
+## MinIO
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `BACKUP_MINIO_BUCKET` / `SEEDGRID_BACKUP_MINIO_BUCKET` (Java `minio.bucket`) | `Option<String>` | nome | — | Condicional (`storage=minio`) | chave `bucket` | `build_storage_config("minio")` | validação no filemanagement | `from_env()` | `config.rs` |
+| `BACKUP_MINIO_REGION` / `SEEDGRID_BACKUP_MINIO_REGION` (Java `minio.region`) | `Option<String>` | região | — (Java: `us-east-1`) | Não | chave `region` | idem | — | `from_env()` | `config.rs` |
+| 🔒 `BACKUP_MINIO_ACCESS_KEY` / `SEEDGRID_BACKUP_MINIO_ACCESS_KEY` | `Option<String>` | texto | — | Condicional | chave `access-key` | idem | — | `from_env()` | `config.rs` |
+| 🔒 `BACKUP_MINIO_SECRET_KEY` / `SEEDGRID_BACKUP_MINIO_SECRET_KEY` | `Option<String>` | texto | — | Condicional | chave `secret-key` | idem | — | `from_env()` | `config.rs` |
+| `BACKUP_MINIO_ENDPOINT` / `SEEDGRID_BACKUP_MINIO_ENDPOINT` | `Option<String>` | URL | — | Condicional | chave `endpoint` | idem | — | `from_env()` | `config.rs` |
+
+## Storages só por struct (sem env)
+`s3` (`bucket`, `region`, `access_key` 🔒, `secret_key` 🔒, `endpoint`), `azure_blob` (`connection_string` 🔒, `container`, `account_name`, `account_key` 🔒), `google_drive` (`root_folder_id`, `credentials_file`, `credentials_json` 🔒), `onedrive` (`client_id`, `client_secret` 🔒, `tenant_id`, `root_folder_path` = `/seedgrid/files`), `gcs` (`bucket`, `project_id`, `credentials_file`, `credentials_json` 🔒). Todos `None` por padrão; `from_env()` **não** os lê (**Confirmado**). Viram mapa `kebab-case` em `build_storage_config` para a crate filemanagement.
+
+## Features Cargo
+Nenhuma.
+
+## Somente testes / exemplos
+| Variável | Onde |
+|---|---|
+| `BACKUP_TEST_DATABASE_URL` | `tests/common/mod.rs` (ITs `#[ignore]`) |
+| `DATABASE_URL`, `RUST_LOG` | `examples/seedgrid-backup-example` (lidas pelo exemplo) |
+
+## Aliases de nome
+
+- O Rust lê `BACKUP_*` primeiro e `SEEDGRID_BACKUP_*` como alias (exceto mailer).
+- Base do filesystem: aceita `BACKUP_FILESYSTEM_BASE` e `SEEDGRID_BACKUP_FILESYSTEM_BASE_PATH`, **não** `SEEDGRID_BACKUP_FILESYSTEM_BASE`.
+- `minio.region` não tem default no Rust.
+- Sem equivalente no Rust: `seedgrid.backup.excluded-domain-entity-packages` e `seedgrid.backup.mailer.auth-methods` (`SEEDGRID_BACKUP_MAILER_AUTH_METHODS`).
+
+## Configuração mínima
+```dotenv
+SEEDGRID_BACKUP_ENABLED=true          # opt-in exigido por BackupPlatform::assemble
+```
+
+## Configuração completa comentada
+```dotenv
+SEEDGRID_BACKUP_ENABLED=true
+BACKUP_RETENTION_DAYS=7
+BACKUP_MAX_CONCURRENT_EXPORTS=1
+BACKUP_STORAGE=filesystem                 # filesystem|minio (s3/azure/gcs/drive/onedrive só via struct)
+BACKUP_QUEUE_POLL_INTERVAL=30s
+BACKUP_ASYNC_ENABLED=true
+BACKUP_FILESYSTEM_BASE=/var/seedgrid/files
+BACKUP_CSV_DELIMITER=,
+BACKUP_CSV_QUOTE_CHAR='"'
+BACKUP_NOTIFICATION_ENABLED=true
+BACKUP_NOTIFICATION_POLL_INTERVAL=5m
+BACKUP_NOTIFICATION_MAX_RETRIES=3
+BACKUP_NOTIFICATION_RETRY_DELAY=PT15M
+SEEDGRID_BACKUP_MAILER_FROM=<remetente@dominio>
+SEEDGRID_BACKUP_MAILER_HOST=<smtp-host>
+SEEDGRID_BACKUP_MAILER_PORT=587
+SEEDGRID_BACKUP_MAILER_START_TLS=REQUIRED
+SEEDGRID_BACKUP_MAILER_USERNAME=<usuario>
+SEEDGRID_BACKUP_MAILER_PASSWORD=<SEGREDO:backup-smtp-password>
+# MinIO (BACKUP_STORAGE=minio)
+BACKUP_MINIO_ENDPOINT=http://<host>:9000
+BACKUP_MINIO_BUCKET=<bucket>
+BACKUP_MINIO_REGION=us-east-1
+BACKUP_MINIO_ACCESS_KEY=<SEGREDO:minio-access-key>
+BACKUP_MINIO_SECRET_KEY=<SEGREDO:minio-secret-key>
+```
+
+## Receitas
+- **Filesystem local**: só `SEEDGRID_BACKUP_ENABLED=true` (+ `BACKUP_FILESYSTEM_BASE`).
+- **MinIO**: `BACKUP_STORAGE=minio` + bloco `BACKUP_MINIO_*`.
+- **S3/Azure/GCS/Drive/OneDrive**: montar `BackupConfig` no host preenchendo o sub-struct (não há env).
+- **Sem e-mail**: `BACKUP_NOTIFICATION_ENABLED=false`.
+- **Sem opt-in**: `BackupOverrides { require_opt_in: false, ..Default::default() }`.