@seedgrid/ai-toolkit 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,36 @@
+---
+tags: [seedgrid, library, cache, enum]
+fonte: java/seedgrid-quarkus-lib-cache
+branch: main
+commit: 14bd916a09
+analisado-em: 2026-10-14
+---
+
+# SeedGrid Cache — Enums
+
+Voltar: [[SeedGrid/Extensions/cache/Visao-geral|Visão geral do cache]] · [[SeedGrid/Extensions/cache/Configuracao|Configuração do cache]]
+
+| Enum | Pacote/arquivo | Usado em | Público? |
+|---|---|---|---|
+| `CacheProviderFailSoft.Level` | `br.com.seedgrid.cache.core.commons.spi.CacheProviderFailSoft` | tipo lógico da propriedade `seedgrid.cache.if-provider-is-down` | Sim (enum aninhado `public`) |
+
+## Level
+
+Arquivo: `java/seedgrid-quarkus-lib-cache/seedgrid-cache-core/src/main/java/br/com/seedgrid/cache/core/commons/spi/CacheProviderFailSoft.java` — FQN `br.com.seedgrid.cache.core.commons.spi.CacheProviderFailSoft.Level`.
+
+| Valor | Significado | Efeito / onde é tratado | Observações |
+|---|---|---|---|
+| `WARN` | Fail-soft: o backend distribuído falhou, a request continua. | `CacheProviderFailSoft#onFailure` loga WARN e retorna; `get` devolve o `fallback` (`Optional.empty()`, `0L`) e `run` vira no-op. **Confirmado.** | Padrão. Valor desconhecido ou ausente também resulta em `WARN`. |
+| `ERROR` | Fail-closed: a request falha junto com o backend. | `onFailure` loga ERROR e relança a `RuntimeException` original. **Confirmado.** | Sem equivalente no Rust (lá ambos os níveis degradam). |
+
+**Atributos/métodos:** sem campos; `static Level parse(String v)` — `null`/vazio/desconhecido → `WARN`; só `"ERROR"` (trim, case-insensitive) → `ERROR`.
+
+**Leitura da configuração:** a propriedade é lida como `String` (`ConfigProvider.getConfig().getOptionalValue(PROP, String.class)`) e convertida por `Level.parse`, **não** pelo conversor de enum do SmallRye. Logo é **case-insensitive** e **valores inválidos não geram erro** (viram `WARN`). Relida a cada falha.
+
+**Persistência / JSON:** não é persistido nem serializado.
+
+**Onde é usado:** [[SeedGrid/Extensions/cache/Configuracao|seedgrid.cache.if-provider-is-down]]; consumido por `SeedGridCacheRedis`, `SeedGridCacheValkey` e `SeedGridCacheDragonfly` via `CacheProviderFailSoft.get/run`. Não se aplica ao `withLock` nem ao `DefaultSeedGridCache`.
+
+## Internos
+
+Nenhum.

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

@@ -0,0 +1,149 @@
+---
+tags: [seedgrid, library, cache, exemplos]
+fonte: java/seedgrid-quarkus-lib-cache, java/examples/seedgrid-cache-example
+branch: main
+commit: 14bd916a09
+analisado-em: 2026-10-14
+---
+
+# SeedGrid Cache — Exemplos
+
+Voltar: [[SeedGrid/Extensions/cache/Visao-geral|Visão geral do cache]] · [[SeedGrid/Extensions/cache/Configuracao|Configuração do cache]]
+
+## Dependências (core + no máximo um provider)
+
+```xml
+<dependency>
+    <groupId>br.com.seedgrid</groupId>
+    <artifactId>seedgrid-cache-core</artifactId>
+    <version>2026.10.13</version>
+</dependency>
+<!-- opcional, escolha UM: seedgrid-cache-redis | seedgrid-cache-valkey | seedgrid-cache-dragonfly -->
+<dependency>
+    <groupId>br.com.seedgrid</groupId>
+    <artifactId>seedgrid-cache-redis</artifactId>
+    <version>2026.10.13</version>
+</dependency>
+```
+
+Fonte: `pom.xml` dos módulos (versão atual) + `README.md` (padrão de instalação).
+
+## API básica
+
+Fonte: `README.md` e assinaturas de `SeedGridCacheProvider`.
+
+```java
+@Inject
+SeedGridCacheProvider cache;
+
+cache.putString("user:42:name", "João", Duration.ofMinutes(10));
+Optional<String> name = cache.getString("user:42:name");
+
+cache.putBytes("img:42", bytes, Duration.ofHours(1));
+Optional<byte[]> img = cache.getBytes("img:42");
+
+cache.putLong("quota:42", 100L, null);   // ttl null/zero/negativo = sem expiração
+OptionalLong quota = cache.getLong("quota:42");
+
+long hits = cache.increment("hits:42", Duration.ofMinutes(1)); // TTL só na 1ª chamada (janela)
+cache.delete("user:42:name");
+
+// Lock exclusivo por chave (distribuído nos providers RESP; JVM-local no default)
+String result = cache.withLock("job:import", Duration.ofSeconds(30), () -> {
+    // seção crítica
+    return "ok";
+});
+```
+
+`withLock` lança `IllegalStateException` se o lock já estiver tomado (providers RESP) — não há espera.
+
+## Cache-aside (exemplo real)
+
+Fonte: `java/examples/seedgrid-cache-example/src/main/java/br/com/seedgrid/cacheexample/service/CatalogService.java` (trecho).
+
+```java
+@ApplicationScoped
+public class CatalogService {
+    private static final String KEY_PREFIX = "catalog:item:";
+    private final SeedGridCacheProvider cache;
+    private final Duration ttl;
+
+    @Inject
+    public CatalogService(
+            SeedGridCacheProvider cache,
+            @ConfigProperty(name = "seedgrid.cache.example.item-ttl", defaultValue = "PT30S") Duration ttl) {
+        this.cache = cache;
+        this.ttl = ttl;
+    }
+
+    public ItemLookup get(String id) {
+        String key = KEY_PREFIX + id;
+        Optional<String> cached = cache.getString(key);
+        if (cached.isPresent()) {
+            return new ItemLookup(id, cached.get(), true, realExecutions.get());
+        }
+        String value = expensiveLookup(id);
+        cache.putString(key, value, ttl);
+        return new ItemLookup(id, value, false, realExecutions.get());
+    }
+
+    public void evict(String id) {
+        cache.delete(KEY_PREFIX + id);
+    }
+}
+```
+
+O exemplo roda só com `seedgrid-cache-core` (in-memory). `seedgrid.cache.example.item-ttl` é propriedade **do exemplo**.
+
+## Configuração por cenário
+
+```properties
+# Redis/Valkey/Dragonfly (mesmo esquema redis://)
+seedgrid.cache.hosts=redis://<host>:6379
+seedgrid.cache.password=<SEGREDO:cache-password>
+
+# Falhar a request quando o backend cair, em vez de degradar
+seedgrid.cache.if-provider-is-down=ERROR
+```
+
+Detalhes e padrões: [[SeedGrid/Extensions/cache/Configuracao|Configuração do cache]].
+
+## Teste com Testcontainers só via alias
+
+Fonte: `seedgrid-cache-redis/src/test/java/.../RedisAliasTestResource.java` e `SeedGridCacheRedisConfigAliasIT.java`.
+
+```java
+public class RedisAliasTestResource implements QuarkusTestResourceLifecycleManager {
+    private final GenericContainer<?> redis =
+        new GenericContainer<>("redis:7-alpine").withExposedPorts(6379);
+
+    @Override
+    public Map<String, String> start() {
+        redis.start();
+        String hosts = "redis://" + redis.getHost() + ":" + redis.getMappedPort(6379);
+        return Map.of("seedgrid.cache.hosts", hosts);
+    }
+
+    @Override
+    public void stop() { redis.stop(); }
+}
+
+@QuarkusTest
+@QuarkusTestResource(RedisAliasTestResource.class)
+class SeedGridCacheRedisConfigAliasIT {
+    @Inject SeedGridCacheRedis cache;
+
+    @Test
+    void providerWorksThroughAliasConfiguredDataSource() {
+        cache.putString("k", "via-alias", Duration.ofSeconds(30));
+        assertEquals("via-alias", cache.getString("k").orElseThrow());
+    }
+}
+```
+
+Com `src/test/resources/application.properties`:
+
+```properties
+quarkus.redis.devservices.enabled=false
+quarkus.arc.selected-alternatives=br.com.seedgrid.cache.redis.commons.spi.SeedGridCacheRedis
+```

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

@@ -0,0 +1,81 @@
+---
+tags: [seedgrid, extension, cache, rust]
+fonte: rust/seedgrid-rust-crate-cache
+branch: main
+commit: be738a2d1e
+analisado-em: 2026-10-14
+---
+
+# cache — porte Rust (`seedgrid-rust-crate-cache`)
+
+Porte da lib Java `seedgrid-quarkus-lib-cache` (módulos `cache-core`, `cache-redis`, `cache-valkey`, `cache-dragonfly`). Lado Java: [[SeedGrid/Extensions/cache/Visao-geral|Visão geral do cache (Java)]] · [[SeedGrid/Extensions/cache/Configuracao|Configuração do cache (Java)]]. Configuração Rust: [[SeedGrid/Extensions/cache/Configuracao-Rust|Configuração Rust do cache]].
+
+Cache independente de provedor: uma API (`SeedGridCacheProvider`) sobre Redis, Valkey ou Dragonfly (todos via protocolo RESP, uma única implementação `RedisCache`) e um backend **in-memory**, que é o padrão. **Confirmado** (`src/lib.rs`, `src/factory.rs`).
+
+## Identificação
+| Item | Valor |
+|---|---|
+| Pacote Cargo | `seedgrid-rust-crate-cache` (lib `seedgrid_cache`) |
+| Versão | workspace `2026.10.14` |
+| Dependências SeedGrid | nenhuma |
+| Consumidores (Cargo.toml) | runtime, backup, login-tenancy, resilience, security, subdomain-tenancy |
+
+## API pública
+| Símbolo | Papel | Fonte |
+|---|---|---|
+| trait `SeedGridCacheProvider` | `get_string`/`put_string`, `get_bytes`/`put_bytes`, `get_long`/`put_long`, `increment`, `increment_ttl`, `delete`, `acquire_lock`, `release_lock` (TTL opcional) | `src/provider.rs` |
+| trait `SeedGridCacheProviderExt` | `with_lock(key, ttl, closure)` (libera o lock mesmo em panic) | `src/provider.rs` |
+| `InMemoryCache::new()` | backend local (default) | `src/memory.rs` |
+| `RedisCache::connect(&CacheConfig)`, `connect_url(url)`, `from_connection(conn)`, `with_provider_down_log(mode)` | backend RESP; aliases `ValkeyCache`, `DragonflyCache`; enum `DistributedFlavor` (informativo) | `src/redis_backend.rs` |
+| `CacheBackend::{InMemory, Distributed{flavor, config}}`, `build(backend)`, `default_cache()` | fábrica | `src/factory.rs` |
+| `CacheConfig`, `ProviderDownLog` | config | `src/config.rs` |
+| `CacheError`, `CacheResult` | erros | `src/error.rs` |
+
+## Comportamento
+- Operações do backend distribuído são **fail-soft**: em falha, devolvem ausência/`0`/no-op e logam em `WARN` ou `ERROR` conforme `ProviderDownLog`. No Java, `ERROR` é fail-closed (relança); no Rust é sempre fail-soft.
+- Só o primeiro host de `hosts` é usado.
+- O lock in-memory não é reentrante (`tokio::Mutex`), ao contrário do `ReentrantLock` Java (intencional).
+
+## Exemplo (de `rust/examples/seedgrid-cache-example/src/main.rs`)
+```rust
+let config = CacheConfig::from_env();
+let cache = RedisCache::connect(&config).await?;
+cache.put_string(&k_str, "olá seedgrid", None).await;
+let got = cache.get_string(&k_str).await;
+cache.put_string(&k_ttl, "efêmero", Some(Duration::from_secs(1))).await;
+let a = cache.increment(&k_ctr).await;
+```
+Em memória (doc de `src/lib.rs`):
+```rust
+let cache = InMemoryCache::new();
+let hits = cache.increment_ttl("hits:42", Some(Duration::from_secs(60))).await;
+let out = cache.with_lock("job:import", Duration::from_secs(30), || async { 42 }).await.unwrap();
+```
+
+## Testes
+- `tests/in_memory.rs`, `tests/java_behavior_parity.rs`, `tests/redis_backend.rs` (Redis real via `SEEDGRID_CACHE_TEST_URL`, `#[ignore]`); testes de alias em `src/config.rs` (porte de `SeedGridCacheConfigRelocateInterceptorTest`).
+- E2E no exemplo: `rust/examples/seedgrid-cache-example/tests/redis_e2e.rs`.
+- **Não executados.**
+
+## Notas de comportamento
+
+- `timeout` é aplicado à conexão e à resposta; durações `PTnS` são aceitas.
+- Com URL com esquema, a senha é injetada na conexão.
+- Operações do backend distribuído são sempre fail-soft (ver `ProviderDownLog`).
+- Lock reentrante; o lock é liberado mesmo em panic.
+- Com múltiplos hosts, só o primeiro é usado.
+- A superfície de configuração é de 4 propriedades.
+
+## Enums
+Java: [[SeedGrid/Extensions/cache/Enums|Enums do cache (Java)]].
+
+| Enum | Arquivo | Java equivalente |
+|---|---|---|
+| `ProviderDownLog` | `src/config.rs` | [[SeedGrid/Extensions/cache/Enums#Level\|Level]] (`seedgrid.cache.if-provider-is-down`) |
+| `CacheBackend` (`InMemory`, `Distributed{flavor, config}`) | `src/factory.rs` | seleção por módulo no classpath |
+| `DistributedFlavor` (`Redis`, `Valkey`, `Dragonfly`) | `src/redis_backend.rs` | módulos `cache-redis`/`-valkey`/`-dragonfly`; **informativo** (mesma implementação) |
+| `LockGuard` (`InMemory`, `Distributed{lock_key, token}`) | `src/provider.rs` | interno (retorno de `acquire_lock`) |
+| `CacheError` (`LockNotAcquired`, `Backend`, `Other`) | `src/error.rs` | — |
+
+### ProviderDownLog
+`Warn` (padrão), `Error`. `from_config_value`: trim, case-insensitive; `ERROR` → `Error`, **qualquer outro valor** → `Warn`. Lido de `SEEDGRID_CACHE_IF_PROVIDER_IS_DOWN` (sem fallback `QUARKUS_REDIS_*`). **Comportamento**: no Rust os dois valores degradam (fail-soft) e só mudam o nível do log; no Java `ERROR` é fail-closed e relança a exceção.

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

@@ -0,0 +1,90 @@
+---
+tags: [seedgrid, library, cache]
+fonte: java/seedgrid-quarkus-lib-cache
+branch: main
+commit: 14bd916a09
+analisado-em: 2026-10-14
+---
+
+# SeedGrid Cache — Visão geral
+
+> [!info] Library, não extension Quarkus
+> `seedgrid-quarkus-lib-cache` é uma **library Java** (jars comuns com índice Jandex), **não** uma extension Quarkus com módulos `runtime`/`deployment`. Não há `@ConfigRoot`, build steps nem processors. Está documentada nesta estrutura apenas por uniformidade.
+
+Configuração: [[SeedGrid/Extensions/cache/Configuracao|Configuração do cache]] · Enums: [[SeedGrid/Extensions/cache/Enums|Enums do cache]] · Exemplos: [[SeedGrid/Extensions/cache/Exemplos|Exemplos do cache]] · [[SeedGrid/Extensions/cache/Rust|Porte Rust]]
+
+## Objetivo
+
+Cache **agnóstico de provider**: uma única API (`SeedGridCacheProvider`) sobre Redis, Valkey ou Dragonfly (todos falam RESP e usam o mesmo `quarkus-redis-client`), com fallback in-memory quando nenhum provider distribuído está no classpath. O backend é escolhido **pela dependência** adicionada, não por propriedade. **Confirmado** (`pom.xml` raiz, `README.md`).
+
+Funcionalidades (**Confirmado** em `SeedGridCacheProvider`):
+- key/value `String`, `byte[]` e `long` com TTL (`Duration`);
+- contador atômico `increment(key)` e `increment(key, ttl)` (INCR + EXPIRE só na 1ª chamada, via Lua);
+- `delete(key)`;
+- lock exclusivo por chave `withLock(key, ttl, Supplier)` — JVM `ReentrantLock` no default, `SET NX PX` + unlock por token (Lua) nos providers RESP;
+- política de falha do backend configurável (`seedgrid.cache.if-provider-is-down`, WARN fail-soft / ERROR fail-closed);
+- fachada de configuração `seedgrid.cache.*` como alias de `quarkus.redis.*`.
+
+## Módulos Maven e coordenadas
+
+| Módulo | groupId:artifactId | Versão | Papel |
+|---|---|---|---|
+| (agregador, `pom`) | `br.com.seedgrid:seedgrid-cache` | `2026.10.13` | parent dos módulos; importa `quarkus-bom` 3.30.8; parent `seedgrid-parent` 2026.07.02 |
+| `seedgrid-cache-core` | `br.com.seedgrid:seedgrid-cache-core` | `2026.10.13` | SPI, `DefaultSeedGridCache` (in-memory), `CacheProviderFailSoft`, `SeedGridCacheConfigRelocateInterceptor` |
+| `seedgrid-cache-redis` | `br.com.seedgrid:seedgrid-cache-redis` | `2026.10.13` | `SeedGridCacheRedis` |
+| `seedgrid-cache-valkey` | `br.com.seedgrid:seedgrid-cache-valkey` | `2026.10.13` | `SeedGridCacheValkey` |
+| `seedgrid-cache-dragonfly` | `br.com.seedgrid:seedgrid-cache-dragonfly` | `2026.10.13` | `SeedGridCacheDragonfly` |
+
+Fonte: `java/seedgrid-quarkus-lib-cache/pom.xml` e `*/pom.xml`. **Confirmado.**
+
+Dependências relevantes: `core` → `quarkus-arc` (provided), `smallrye-config-core` (provided). Providers → `seedgrid-cache-core`, `quarkus-redis-client` (compile). Nenhuma dependência de outras libs/extensions SeedGrid. **Confirmado.**
+
+## Arquitetura
+
+```mermaid
+flowchart LR
+    APP["App<br/>@Inject SeedGridCacheProvider"] --> SPI["SeedGridCacheProvider"]
+    SPI -->|"sem provider no classpath<br/>@DefaultBean"| MEM["DefaultSeedGridCache<br/>(ConcurrentHashMap)"]
+    SPI -->|"@Alternative @Priority(1)"| R["SeedGridCacheRedis / Valkey / Dragonfly"]
+    R --> FS["CacheProviderFailSoft<br/>(seedgrid.cache.if-provider-is-down)"]
+    FS --> DS["RedisDataSource (@Default)<br/>quarkus-redis-client"]
+    CFG["seedgrid.cache.*"] -. "RelocateConfigSourceInterceptor<br/>(ServiceLoader)" .-> QR["quarkus.redis.*"]
+    QR --> DS
+```
+
+- **Seleção do bean** (**Confirmado** pelas anotações): `DefaultSeedGridCache` é `@ApplicationScoped @DefaultBean`; cada provider é `@ApplicationScoped @Alternative @Priority(1)` (alternativa habilitada globalmente). Colocar **dois** providers no classpath gera resolução ambígua — **Confirmado** como aviso em `README.adoc` ("colocar mais de um simultaneamente causa resolução ambígua"); não há teste que comprove.
+- **Fail-soft** (**Confirmado**, `CacheProviderFailSoft`): `get/put/increment/delete` dos providers RESP são envolvidos; em `RuntimeException` do backend, `WARN` loga e devolve fallback (`Optional.empty()`, `0L`, no-op), `ERROR` loga e relança. `withLock` **não** é envolvido: falha de conexão propaga sempre, e lock não adquirido lança `IllegalStateException("Could not acquire lock: ...")` (sem espera/retry).
+- **Alias de config** (**Confirmado**, `SeedGridCacheConfigRelocateInterceptor` + `META-INF/services/io.smallrye.config.ConfigSourceInterceptor`): `@Priority(Priorities.LIBRARY + 200)`, reloca todo nome `quarkus.redis.<x>` para `seedgrid.cache.<x>` e só cai no nome original se o relocado não tiver valor.
+- Chaves de lock: `<key>:lock`. TTL `null`/zero/negativo = sem expiração (SET em vez de SETEX). `getLong` devolve vazio se o valor não for numérico. **Confirmado.**
+- `DefaultSeedGridCache`: TTL em milissegundos com limpeza preguiçosa na leitura; `getBytes`/`putBytes` fazem cópia defensiva; `withLock` ignora o `ttl` (lock JVM local). **Confirmado.**
+
+## APIs públicas e pontos de integração
+
+| Tipo | Símbolo | Observação |
+|---|---|---|
+| Interface SPI | `br.com.seedgrid.cache.core.commons.spi.SeedGridCacheProvider` | `getString/putString`, `getBytes/putBytes`, `getLong/putLong`, `increment(key)`, `increment(key, ttl)`, `delete`, `<T> withLock(key, ttl, Supplier<T>)` |
+| Bean CDI default | `...core.commons.spi.impl.DefaultSeedGridCache` | in-memory, `@DefaultBean` |
+| Beans CDI alternativos | `SeedGridCacheRedis`, `SeedGridCacheValkey`, `SeedGridCacheDragonfly` | injetam `RedisDataSource` padrão (`@Default`) |
+| Utilitário público | `CacheProviderFailSoft` (`get`, `run`, `Level.parse`, constante `PROP`) | usado pelos providers; reutilizável por quem implementar outro provider |
+| SmallRye `ConfigSourceInterceptor` | `...core.config.SeedGridCacheConfigRelocateInterceptor` | registrado via ServiceLoader |
+
+Não há endpoints REST, eventos CDI, migrations nem anotações próprias.
+
+## Testes existentes (não executados)
+
+| Local | Tipo | Cobre |
+|---|---|---|
+| `seedgrid-cache-core/src/test/.../SeedGridCacheConfigRelocateInterceptorTest` | unit | alias `seedgrid.cache.*` → `quarkus.redis.*`, fallback e precedência |
+| `seedgrid-cache-{redis,valkey,dragonfly}/src/test/.../*ConfigAliasIT` + `*AliasTestResource` | `@QuarkusTest` + Testcontainers | prova end-to-end que só `seedgrid.cache.hosts` configura o `RedisDataSource` |
+| `seedgrid-cache-{redis,valkey,dragonfly}/src/test/.../*IT` | integração (Testcontainers) | operações reais contra o servidor |
+| `SeedGridCacheValkeyTest`, `SeedGridCacheDragonflyTest` | unit (Mockito) | seleção set/setex, INCR vs EVAL |
+
+Nenhum teste cobre `seedgrid.cache.if-provider-is-down` (busca por `FailSoft`/`if-provider` em `src/test` sem resultado). Testes **não executados** nesta análise.
+
+## Limitações
+
+- Só o `RedisDataSource` `@Default` é usado; clientes nomeados não são suportados pelos providers. **Confirmado** (injeção sem qualifier).
+- `withLock` não é fail-soft e não tem espera; `DefaultSeedGridCache.withLock` é local à JVM.
+- Não há API genérica de objetos (apenas `String`/`byte[]`/`long`); serialização fica a cargo do app. **Confirmado** (comentário em `CatalogService` do exemplo).
+- No Java `ERROR` é fail-closed; no Rust ambos os níveis são fail-soft. Ver [[SeedGrid/Extensions/cache/Rust|Porte Rust]].
+- Clientes nomeados: `quarkus.redis.<nome>.*` também é relocado para `seedgrid.cache.<nome>.*` (relocate por prefixo) — ver [[SeedGrid/Extensions/cache/Configuracao|Configuração do cache]].

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

@@ -0,0 +1,107 @@
+---
+tags: [seedgrid, library, commons, configuracao]
+fonte: java/seedgrid-quarkus-lib-commons
+branch: main
+commit: fa49c344db
+analisado-em: 2026-10-14
+---
+
+# SeedGrid Commons — Configuração
+
+Voltar: [[SeedGrid/Extensions/commons/Visao-geral|Visão geral do commons]] · [[SeedGrid/Extensions/commons/Exemplos|Exemplos do commons]]
+
+## 1. Cabeçalho
+
+| Item | Valor |
+|---|---|
+| Prefixos | `seedgrid.app.*`, `seedgrid.web.cors.*`, `seedgrid.show-dev-message`, `app.build.version` (sem prefixo `seedgrid`) |
+| Classes de config | Nenhuma `@ConfigMapping`/`@ConfigRoot`. `@ConfigProperty` em beans CDI: `BusinessTimeZone`, `CorsConfig`, `ApiExceptionHandler`, `StartupBannerLogger`. `ConfigProvider` em `ValidEmailValidator` (só lê `quarkus.profile`) |
+| Arquivos de config da lib | Nenhum (`src/main/resources` não existe; sem `microprofile-config.properties`) |
+| Fase | Runtime — valores injetados na criação de cada bean (`@ApplicationScoped`: na primeira utilização; `StartupBannerLogger`: no `StartupEvent`). Não há releitura posterior |
+
+Investigado: `@ConfigMapping`, `@ConfigRoot`, `@ConfigProperty`, `ConfigProvider`, `System.getenv/getProperty`, `@IfBuildProperty`/`@LookupIfProperty`, resources. Nenhum teste da lib define propriedades (testes unitários instanciam as classes diretamente).
+
+## 2. Propriedades próprias
+
+### 2.1 Fuso de negócio
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `seedgrid.app.business-timezone` | `String` → `ZoneId` | qualquer ID aceito por `ZoneId.of` (ex.: `America/Sao_Paulo`, `UTC`) | `America/Sao_Paulo` | Não | Valor vazio **ou inválido** cai silenciosamente para `America/Sao_Paulo` (sem log) | `BusinessTimeZone#zoneId()` — converter instantes em datas civis (ciclos de cobrança/consumo) | Consumido por extensions que injetam `BusinessTimeZone` (ex.: billing — **Inferência** pelo Javadoc) | Runtime (construtor do bean) | `java/seedgrid-quarkus-lib-commons/src/main/java/br/com/seedgrid/commons/core/time/BusinessTimeZone.java` → construtor + `resolve(String)` |
+
+### 2.2 CORS (`CorsFilter`)
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `seedgrid.web.cors.allow-origins` | `List<String>` (separada por vírgula) | origens exatas (`esquema://host[:porta]`); comparação por igualdade exata, sem curinga | `http://localhost:3000,http://localhost:4200` | Não (mas em produção o padrão só libera localhost) | Preflight `OPTIONS` de origem fora da lista → **403**; requisição não-preflight de origem fora da lista segue sem headers CORS; origem `"null"` → 403 sempre | `CorsFilter#filter(request)` e `#filter(request, response)` via `CorsConfig#getAllowOrigins()` | Independente de `quarkus.http.cors.*` (interação não verificada) | Runtime | `.../commons/web/cors/CorsConfig.java` → campo `allowOrigins`; consumo `.../web/cors/CorsFilter.java` |
+| `seedgrid.web.cors.allow-methods` | `String` | lista de métodos HTTP separada por vírgula (copiada literalmente no header) | `GET,POST,PUT,PATCH,DELETE,OPTIONS` | Não | Valor de `Access-Control-Allow-Methods` na resposta ao preflight; **não** é usado para bloquear métodos | `CorsFilter#filter(request)` (preflight) via `CorsConfig#getAllowMethods()` | — | Runtime | `CorsConfig.java` → campo `allowMethods` |
+
+Headers fixos (não configuráveis): `Access-Control-Allow-Headers`, `Access-Control-Allow-Credentials: true`, `Access-Control-Max-Age: 0`, `Access-Control-Expose-Headers: Location,Link`. **Confirmado.**
+
+### 2.3 Tratamento de exceções
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `seedgrid.show-dev-message` | `boolean` | `true`/`false` | `false` | Não | `true` preenche `devMessage` no Problem Details (mensagem técnica da exceção / violações); `false` devolve `devMessage` vazio. Valor é logado em INFO na criação do handler | `ApiExceptionHandler#resolveDevMessage` (todas as respostas do handler, inclusive via `ConstraintViolationExceptionMapper`) | Recomendado `false` em produção (evita vazar detalhes) — **Inferência** | Runtime | `.../commons/web/exceptions/ApiExceptionHandler.java` → construtor |
+
+### 2.4 Banner de inicialização
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `app.build.version` | `String` | livre | `dev` | Não | Impresso em `System.out` como `Versao: <valor>` após o `banner.txt` do classpath (se existir) | `StartupBannerLogger#onStart(StartupEvent)` | Convenção dos hosts: `app.build.version=${APP_VERSION:dev}` (comentário no código) | Runtime (startup) | `.../commons/core/startup/StartupBannerLogger.java` → campo `buildVersion` |
+
+Variáveis de ambiente pela regra MP (**Inferência**, nomes sem ambiguidade na leitura por nome exato): `SEEDGRID_APP_BUSINESS_TIMEZONE`, `SEEDGRID_WEB_CORS_ALLOW_ORIGINS`, `SEEDGRID_WEB_CORS_ALLOW_METHODS`, `SEEDGRID_SHOW_DEV_MESSAGE`, `APP_BUILD_VERSION`.
+
+## 3. Propriedades de frameworks lidas
+
+| Propriedade | Como é lida | Efeito | Origem |
+|---|---|---|---|
+| `quarkus.profile` | Ordem: system property `quarkus.profile` → env `QUARKUS_PROFILE` (lida diretamente via `System.getenv`) → `ConfigProvider` | `@ValidEmail` bloqueia domínios descartáveis (lista fixa no código: yopmail, mailinator, 10minutemail etc.) **somente** se `LaunchMode.current() == NORMAL` **e** o perfil for `prod` ou não estiver definido | `.../core/validators/ValidEmailValidator.java` → `shouldBlockDisposableDomains()`, `resolveNormalProfile()` |
+
+A lib também precisa, no host, de Hibernate ORM configurado se usar `BaseEntity`/embeddables, e de `quarkus-rest-jackson` (dependência *optional* aqui) para `CorsFilter`/`ApiExceptionHandler` — **Inferência** pelo escopo `optional` no pom.
+
+## 4. Propriedades só de testes/exemplos
+
+Nenhuma (os testes não usam `application.properties`).
+
+## 5. Aliases, obsoletas, renomeações
+
+Nenhuma encontrada.
+
+## 6. Configuração mínima
+
+Nenhuma propriedade é obrigatória. Para produção, o mínimo sensato:
+
+```properties
+seedgrid.web.cors.allow-origins=https://<app.seudominio>
+```
+
+## 7. Configuração completa comentada
+
+```properties
+# Fuso usado para converter instantes em datas civis (ZoneId válido; inválido volta ao padrão)
+seedgrid.app.business-timezone=America/Sao_Paulo
+
+# CORS do CorsFilter da lib (origens exatas, separadas por vírgula)
+seedgrid.web.cors.allow-origins=https://<app.seudominio>,https://<admin.seudominio>
+seedgrid.web.cors.allow-methods=GET,POST,PUT,PATCH,DELETE,OPTIONS
+
+# Expor detalhes técnicos em devMessage do Problem Details (padrão false)
+seedgrid.show-dev-message=false
+
+# Versão exibida no banner de startup (padrão "dev")
+app.build.version=${APP_VERSION:dev}
+```
+
+## 8. Receitas
+
+- **Front em outro domínio**: liste a origem exata em `seedgrid.web.cors.allow-origins` (inclua porta em dev).
+- **Depurar erros 500 em dev**: `%dev.seedgrid.show-dev-message=true` (perfil MP) e mantenha `false` em prod.
+- **Operação fora do Brasil**: `seedgrid.app.business-timezone=<ZoneId>`.
+- **Aceitar e-mails descartáveis em homologação**: rode com `quarkus.profile` ≠ `prod` (ex.: `QUARKUS_PROFILE=staging`).
+
+## 9. Dúvidas e lacunas
+
+- Valor inválido de `seedgrid.app.business-timezone` é ignorado sem aviso — risco de configuração silenciosa.
+- Interação entre `CorsFilter` e `quarkus.http.cors` não documentada/testada.
+- A lib depende de `seedgrid-privacy`; as propriedades `seedgrid.privacy.*` afetam `Address`/`Contact`, mas pertencem à lib privacy: [[SeedGrid/Extensions/privacy/Configuracao|Configuração do privacy]].

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

@@ -0,0 +1,105 @@
+---
+tags: [seedgrid, library, commons, enum]
+fonte: java/seedgrid-quarkus-lib-commons
+branch: main
+commit: fa49c344db
+analisado-em: 2026-10-14
+---
+
+# SeedGrid Commons — Enums
+
+Voltar: [[SeedGrid/Extensions/commons/Visao-geral|Visão geral do commons]] · [[SeedGrid/Extensions/commons/Configuracao|Configuração do commons]]
+
+| Enum | Pacote/arquivo | Usado em | Público? |
+|---|---|---|---|
+| `StateEnum` | `br.com.seedgrid.commons.core.enums.StateEnum` | `Address.state` (coluna), DTOs de cadastro de outras extensions | Sim |
+| `StateEnum.Regiao` | aninhado em `StateEnum.java` | atributo `regiao` de `StateEnum` | Sim |
+| `ProblemType` | `br.com.seedgrid.commons.web.exceptions.ProblemType` | campo `type` do Problem Details | Sim |
+
+## StateEnum
+
+Arquivo: `java/seedgrid-quarkus-lib-commons/src/main/java/br/com/seedgrid/commons/core/enums/StateEnum.java`.
+
+Os 27 valores são as UFs; cada um tem `sigla` (igual ao nome da constante), `nome`, `regiao` e `ibge` (código IBGE). **Confirmado** (código).
+
+| Valor | Nome | Região | IBGE |
+|---|---|---|---|
+| `AC` | Acre | NORTE | 12 |
+| `AL` | Alagoas | NORDESTE | 27 |
+| `AP` | Amapá | NORTE | 16 |
+| `AM` | Amazonas | NORTE | 13 |
+| `BA` | Bahia | NORDESTE | 29 |
+| `CE` | Ceará | NORDESTE | 23 |
+| `DF` | Distrito Federal | CENTRO_OESTE | 53 |
+| `ES` | Espírito Santo | SUDESTE | 32 |
+| `GO` | Goiás | CENTRO_OESTE | 52 |
+| `MA` | Maranhão | NORDESTE | 21 |
+| `MT` | Mato Grosso | CENTRO_OESTE | 51 |
+| `MS` | Mato Grosso do Sul | CENTRO_OESTE | 50 |
+| `MG` | Minas Gerais | SUDESTE | 31 |
+| `PA` | Pará | NORTE | 15 |
+| `PB` | Paraíba | NORDESTE | 25 |
+| `PR` | Paraná | SUL | 41 |
+| `PE` | Pernambuco | NORDESTE | 26 |
+| `PI` | Piauí | NORDESTE | 22 |
+| `RJ` | Rio de Janeiro | SUDESTE | 33 |
+| `RN` | Rio Grande do Norte | NORDESTE | 24 |
+| `RS` | Rio Grande do Sul | SUL | 43 |
+| `RO` | Rondônia | NORTE | 11 |
+| `RR` | Roraima | NORTE | 14 |
+| `SC` | Santa Catarina | SUL | 42 |
+| `SP` | São Paulo | SUDESTE | 35 |
+| `SE` | Sergipe | NORDESTE | 28 |
+| `TO` | Tocantins | NORTE | 17 |
+
+**Métodos:** `getSigla()`, `getNome()`, `getRegiao()`, `getIbge()`; `fromSigla(String)` (trim + maiúsculas; `Optional`); `fromNome(String)` (trim, ignora caixa; `Optional`); `toJson()`; `fromJson(String)` (tenta sigla, depois nome; `null` → `null`; desconhecido → `IllegalArgumentException("UF inválida: ...")`).
+
+**Serialização:**
+- **JSON:** `@JsonValue toJson()` → sempre a **sigla** (`"SP"`). Entrada via `@JsonCreator fromJson` aceita sigla (qualquer caixa) **ou** nome por extenso (`"São Paulo"`). **Confirmado.**
+- **Persistência:** em `Address.state` é `@Enumerated(EnumType.STRING)` (grava o nome da constante, igual à sigla). A lib não traz migrations nem `CHECK`; a coluna e seus valores aceitos são do host. **Confirmado.**
+- **Conversão fora do Jackson:** `valueOf(String)` aceita só a sigla exata (maiúscula); extensions que leem estado de config usam `StateEnum.valueOf(state.toUpperCase())` (security `CompanyService#parseState`, `FirstAdminBootstrapService#parseState`). Nome por extenso **não** funciona nesses pontos.
+
+**Onde é usado:** `Address.state` (embeddable do commons); `InstitutionalSignupRequest.state` (login-tenancy); `TenantSignupRequest` (subdomain-tenancy); security (`CompanyService`, `FirstAdminBootstrapService`).
+
+### StateEnum.Regiao
+
+| Valor | Significado | Efeito / onde é tratado | Observações |
+|---|---|---|---|
+| `NORTE` | Região Norte | atributo informativo (`getRegiao()`) | nenhum código da lib decide por região |
+| `NORDESTE` | Região Nordeste | idem | — |
+| `CENTRO_OESTE` | Região Centro-Oeste | idem | — |
+| `SUDESTE` | Região Sudeste | idem | — |
+| `SUL` | Região Sul | idem | — |
+
+Não é serializado isoladamente (o JSON de `StateEnum` é só a sigla).
+
+## ProblemType
+
+Arquivo: `java/seedgrid-quarkus-lib-commons/src/main/java/br/com/seedgrid/commons/web/exceptions/ProblemType.java`.
+
+**Atributos (Lombok `@Getter`):** `uri` = `https://seedgrid.com.br` + caminho e `title`. Só `getUri()` é usado nas respostas (campo `type` do Problem Details); `getTitle()` não é lido por nenhum código do monorepo. O enum em si **não** é serializado.
+
+| Valor | URI (`type`) | Significado | Efeito / onde é tratado | Observações |
+|---|---|---|---|---|
+| `DADOS_INVALIDOS` | `/dados-invalidos` | Dados de entrada inválidos | `ApiExceptionHandler`: `ConstraintViolationException` (400) e fallback de `WebApplicationException` sem outro mapeamento; usado também por billing e security | — |
+| `ERRO_DE_SISTEMA` | `/erro-de-sistema` | Erro interno | `ApiExceptionHandler`: status ≥ 500 (inclui o 500 de exceção não tratada) | — |
+| `PARAMETRO_INVALIDO` | `/parametro-invalido` | Parâmetro inválido | Nenhum código do monorepo usa este valor | Existe no enum; pode ser usado por hosts |
+| `MENSAGEM_INCOMPREENSIVEL` | `/mensagem-incompreensivel` | Corpo ilegível/não processável | `ApiExceptionHandler`: `WebApplicationException` com 415 ou 422 | — |
+| `RECURSO_NAO_ENCONTRADO` | `/recurso-nao-encontrado` | Recurso inexistente | `ApiExceptionHandler`: `NotFoundException` e status 404; usado por billing, security e login-tenancy | — |
+| `ENTIDADE_EM_USO` | `/entidade-em-uso` | Conflito: entidade em uso | `ApiExceptionHandler`: status 409 de `WebApplicationException`; usado por billing (`PlanInUseException`) e security | `EntityInUseException` **não** usa este tipo (é `BusinessException` → `ERRO_NEGOCIO`, 400) |
+| `ERRO_NEGOCIO` | `/erro-negocio` | Violação de regra de negócio | `ApiExceptionHandler`: `BusinessException` e subclasses (400) | — |
+| `OBRIGATORIO_TROCA_DE_SENHA` | `/obrigatorio-troca-de-senha` | Troca de senha obrigatória | Nenhum código do monorepo usa este valor | Existe no enum; pode ser usado por hosts |
+| `ACESSO_NEGADO` | `/acesso-negado` | Sem permissão (403) | `ApiExceptionHandler`: status 403; usado por security | — |
+| `ERRO_AO_ENVIAR_O_EMAIL` | `/erro-ao-enviar-o-email` | Falha ao enviar e-mail | Nenhum código do monorepo usa este valor | Existe no enum; pode ser usado por hosts |
+| `OPERACAO_NAO_PERMITIDA` | `/operacao-nao-permitida` | Operação bloqueada por regra | Usado por billing (exceções de plano/assinatura/quota) e security; não pelo handler do commons | — |
+| `AUTENTICACAO_NEGADA` | `/autenticacao-negada` | Não autenticado (401) | `ApiExceptionHandler`: status 401; usado por security e billing | — |
+| `SISTEMA_INDISPONIVEL` | `/sistema-indisponivel` | Serviço/provedor indisponível | Usado por billing (`ProviderOperationException`) e security | — |
+| `RECURSO_NAO_SUPORTADO` | `/recurso-nao-suportado` | Recurso não suportado | Usado por billing (`CatalogNotSupportedException`, `UsageNotSupportedException`) | — |
+
+Mapeamento por status no handler (`resolveProblemType`): 404→`RECURSO_NAO_ENCONTRADO`, 401→`AUTENTICACAO_NEGADA`, 403→`ACESSO_NEGADO`, 409→`ENTIDADE_EM_USO`, 415/422→`MENSAGEM_INCOMPREENSIVEL`, ≥500→`ERRO_DE_SISTEMA`, demais→`DADOS_INVALIDOS`. **Confirmado.**
+
+**Onde é usado:** campo `type` das respostas `application/problem+json` — ver [[SeedGrid/Extensions/commons/Visao-geral|Visão geral do commons]] e as `ApiExceptionExtension` das demais extensions.
+
+## Internos
+
+Nenhum.