@seedgrid/ai-toolkit 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,141 @@
+---
+tags: [seedgrid, library, commons, exemplos]
+fonte: java/seedgrid-quarkus-lib-commons
+branch: main
+commit: fa49c344db
+analisado-em: 2026-10-14
+---
+
+# SeedGrid Commons — Exemplos
+
+Voltar: [[SeedGrid/Extensions/commons/Visao-geral|Visão geral do commons]] · [[SeedGrid/Extensions/commons/Configuracao|Configuração do commons]]
+
+Não há projeto em `java/examples` para o commons; os exemplos abaixo seguem o `README.md` e as assinaturas reais do código.
+
+## Dependência
+
+```xml
+<dependency>
+    <groupId>br.com.seedgrid</groupId>
+    <artifactId>seedgrid-commons</artifactId>
+    <version>2026.10.08</version>
+</dependency>
+```
+
+## Entidade base com auditoria de usuário
+
+```java
+@Entity
+public class Product extends BaseEntity {
+    private String name;
+}
+// @PrePersist gera publicId (UUIDv7) e garante active=true;
+// createdAt/updatedAt (Instant) via @CreationTimestamp/@UpdateTimestamp;
+// createUserPublicId/updateUserPublicId preenchidos pelo BaseEntityAuditListener.
+```
+
+Fornecendo o usuário corrente (substitui o `DefaultCurrentUserProvider`, que é `@DefaultBean`):
+
+```java
+@ApplicationScoped
+public class MyCurrentUserProvider implements CurrentUserProvider {
+    @Override public String getCurrentUserPublicId() { return /* publicId do usuário autenticado */ null; }
+    @Override public String getCurrentUserEmail()    { return null; }
+    @Override public String getCurrentUserName()     { return null; }
+    @Override public String getCurrentUserWhatsapp() { return null; }
+}
+```
+
+## Validadores
+
+```java
+public class SignupRequest {
+    @ValidName(quantidadePalavras = 2)   // atributo obrigatório (sem default)
+    String fullName;
+
+    @ValidEmail                          // bloqueia domínios descartáveis só em prod
+    String email;
+
+    @ValidPhone
+    String phone;
+
+    @ValidBirthDate(minAge = 18)
+    LocalDate birthDate;
+
+    // Defaults reais: minSize=8 e TODAS as regras true
+    @ValidPassword(prohibitsRepeatedCharactersInSequence = false)
+    String password;
+}
+```
+
+## Exceções de negócio → Problem Details
+
+```java
+throw new BusinessException("Nao foi possivel concluir", "detalhe tecnico para devMessage");
+// -> 400, type https://seedgrid.com.br/erro-negocio, application/problem+json
+```
+
+`EntityNotFoundException`/`EntityInUseException` também resultam em **400** (estendem `BusinessException`). Para outro status, use `ApiExceptionExtension`:
+
+```java
+@ApplicationScoped
+public class MyCustomExceptionExtension implements ApiExceptionExtension {
+    @Override
+    public Response tryHandle(Throwable ex) {
+        // atenção: BusinessException e subclasses são tratadas ANTES das extensions,
+        // então este ponto só recebe exceções que o handler não reconhece.
+        if (ex instanceof MyCustomException) {
+            return Response.status(422)
+                .entity(ProblemDetails.builder()
+                    .type(ProblemType.MENSAGEM_INCOMPREENSIVEL.getUri())
+                    .title("Unprocessable Entity")
+                    .status(422)
+                    .detail("Revise os dados enviados e tente novamente.")
+                    .devMessage(ex.getMessage())
+                    .instance("")
+                    .build())
+                .type("application/problem+json")
+                .build();
+        }
+        return null;
+    }
+}
+```
+
+Fonte: `README.md` (exemplo de extensão) + ordem de tratamento em `ApiExceptionHandler#toResponse`.
+
+## Fuso de negócio
+
+```java
+@Inject BusinessTimeZone businessTimeZone;
+
+LocalDate dataDeNegocio = instante.atZone(businessTimeZone.zoneId()).toLocalDate();
+```
+
+## Evento para o usuário (`SgUserEvent`)
+
+```java
+@Inject Event<SgUserEvent> userEvents;
+
+@Transactional
+public void finish(Export export) {
+    // ... grava o resultado
+    userEvents.fire(new SgUserEvent(userPublicId, "backup", "backup.finished.success",
+            Map.of("exportPublicId", export.getPublicId())));
+}
+
+// Quem escuta (ex.: realtime) usa:
+void on(@Observes(during = TransactionPhase.AFTER_SUCCESS) SgUserEvent e) { /* ... */ }
+```
+
+Fonte: Javadoc de `SgUserEvent` (dispare dentro da transação; `data` só com identificadores).
+
+## Configuração típica
+
+```properties
+seedgrid.web.cors.allow-origins=https://<app.seudominio>
+seedgrid.show-dev-message=false
+app.build.version=${APP_VERSION:dev}
+```
+
+Ver [[SeedGrid/Extensions/commons/Configuracao|Configuração do commons]].

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

@@ -0,0 +1,99 @@
+---
+tags: [seedgrid, library, commons]
+fonte: java/seedgrid-quarkus-lib-commons
+branch: main
+commit: fa49c344db
+analisado-em: 2026-10-14
+---
+
+# SeedGrid Commons — Visão geral
+
+> [!info] Library, não extension Quarkus
+> `seedgrid-quarkus-lib-commons` é uma **library Java** (um único jar com índice Jandex), **não** uma extension Quarkus com `runtime`/`deployment`. Não há `@ConfigRoot`, build steps nem processors. Documentada nesta estrutura por uniformidade. Não existe porte Rust desta lib.
+
+Configuração: [[SeedGrid/Extensions/commons/Configuracao|Configuração do commons]] · Enums: [[SeedGrid/Extensions/commons/Enums|Enums do commons]] · Exemplos: [[SeedGrid/Extensions/commons/Exemplos|Exemplos do commons]]
+
+## Objetivo
+
+Biblioteca compartilhada pelo ecossistema SeedGrid com utilitários, validadores Bean Validation, entidades JPA base com auditoria de usuário, SPIs de tenant/usuário/contato, evento CDI de aviso ao usuário, filtro CORS e mapeamento global de exceções em Problem Details (`application/problem+json`). **Confirmado** (`README.md`, código).
+
+## Coordenadas e dependências
+
+| Item | Valor |
+|---|---|
+| groupId:artifactId | `br.com.seedgrid:seedgrid-commons` |
+| Versão (pom) | `2026.10.08` |
+| Parent | `br.com.seedgrid:seedgrid-parent:2026.07.02`; importa `quarkus-bom` 3.30.8 |
+| Packaging | `jar` (com `jandex-maven-plugin`) |
+| Dependências Quarkus | `quarkus-arc`, `quarkus-hibernate-orm`, `quarkus-hibernate-orm-panache`, `quarkus-hibernate-validator`, `quarkus-rest-jackson` (**optional**) |
+| Dependência SeedGrid | `br.com.seedgrid:seedgrid-privacy:2026.07.27` — ver [[SeedGrid/Extensions/privacy/Visao-geral|Visão geral do privacy]] |
+| Outras | Lombok (provided) |
+
+Fonte: `java/seedgrid-quarkus-lib-commons/pom.xml`. **Confirmado.**
+
+## Componentes e APIs públicas
+
+### Core (`br.com.seedgrid.commons.core`)
+
+| Símbolo | Tipo | Resumo |
+|---|---|---|
+| `time.BusinessTimeZone` | bean `@ApplicationScoped` | `zoneId()`; lê `seedgrid.app.business-timezone` (padrão `America/Sao_Paulo`) |
+| `startup.StartupBannerLogger` | bean `@ApplicationScoped`, observa `StartupEvent` | imprime `banner.txt` (do classpath do host) e `app.build.version` em `System.out` |
+| `utils.UUIDv7` | utilitário | `UUID generate()` (time-ordered) |
+| `utils.HashUtils` | utilitário | `sha256Hex(String)` |
+| `utils.JsonAttributeLimits` / `JsonAttributeLimitsSpec` | utilitário + record | `findViolation(Map<String, JsonNode>, spec)` — limites de tamanho (bytes), profundidade e nº de chaves |
+| `utils.JsonAttributeMerger` | utilitário | `merge(target, patch)`, `copyWithoutNulls(source)` |
+| `enums.StateEnum` | enum | UFs com `sigla`, `nome`, `regiao`, `ibge`; `fromSigla`, `fromNome`, `fromJson` |
+| `exceptions.BusinessException` | `RuntimeException` | `userMessage` + `devMessage` |
+| `exceptions.EntityNotFoundException`, `EntityInUseException` | estendem `BusinessException` | — |
+| `exceptions.ThrowableUtils` | utilitário | `hasException(Throwable, Class)` |
+| `pagination.PageReq` (record), `PageResult<T>` | DTOs | paginação simples |
+| `validators.@ValidBirthDate(minAge, maxAge)` | Bean Validation | `-1` desabilita cada limite |
+| `validators.@ValidName(quantidadePalavras)` | Bean Validation | `quantidadePalavras` **sem default** (obrigatório na anotação) |
+| `validators.@ValidPassword(...)` | Bean Validation | defaults no código: `minSize=8` e **todas** as regras `true` (`upper/lower/number/specialCharacterRequired`, `prohibitsRepeatedCharactersInSequence`) |
+| `validators.@ValidEmail` | Bean Validation | regex + bloqueio de domínios descartáveis em produção (ver config) |
+| `validators.@ValidPhone` | Bean Validation | aceita só dígitos ou formato mascarado |
+
+### Persistência (`br.com.seedgrid.commons.persistence`)
+
+| Símbolo | Resumo |
+|---|---|
+| `BaseEntity` (`@MappedSuperclass`) | `id` (IDENTITY), `publicId` (UUIDv7 no `@PrePersist`), `active`, `createdAt`/`updatedAt` (`Instant` → `timestamptz`), `createUserPublicId`, `updateUserPublicId`; `@EntityListeners(BaseEntityAuditListener)` |
+| `BaseEntityPanache` | idem estendendo `PanacheEntityBase` (sem `active`) |
+| `BaseEntityAuditListener` / `BaseEntityPanacheAuditListener` | preenchem `create/updateUserPublicId` via `CurrentUserProvider`; em erro (sem contexto) gravam `null` |
+| `spi.CurrentUserProvider` + `spi.impl.DefaultCurrentUserProvider` (`@DefaultBean`) | default devolve publicId zero (`00000000-...`), e-mail/nome placeholders |
+| `embeddables.Address`, `embeddables.Contact` (`@Embeddable`) | campos com `@PersonalData` e, em `phone`/`cpf`/`whatsapp`/`email`, `@EncryptedField` + `@Convert(EncryptedFieldAttributeConverter)` com campo `*Hash` irmão (lib privacy) |
+| `SchemaUtils.schemaReady(EntityManager, historyTable)` | verifica se a última migração Flyway registrada teve sucesso (`to_regclass('public.<tabela>')`) |
+
+Colunas usadas por `BaseEntity`: `public_id`, `active`, `created_at`, `updated_at`, `create_user_public_id`, `update_user_public_id`. A lib **não** traz migrations; cada host/extension cria as colunas. **Confirmado.**
+
+### SPIs gerais (`br.com.seedgrid.commons.spi`) e eventos
+
+| Símbolo | Resumo |
+|---|---|
+| `TenantProvider` + `SingleTenantProvider` (`@DefaultBean`) | default single-tenant: tenant `"default"`, set/clear no-op |
+| `UserContactProvider` (+ record `UserContact`) + `DefaultUserContactProvider` (`@DefaultBean`) | default devolve `UserContact.empty()` |
+| `events.SgUserEvent(userPublicId, channel, event, data)` | evento CDI neutro "algo aconteceu para um usuário" (consumido p.ex. pela extension realtime — ver [[SeedGrid/Extensions/realtime/Visao-geral|Visão geral do realtime]]) |
+
+### Web (`br.com.seedgrid.commons.web`)
+
+| Símbolo | Resumo |
+|---|---|
+| `cors.CorsFilter` (`@Provider @PreMatching`, prioridade `AUTHENTICATION - 100`) + `cors.CorsConfig` | responde preflight `OPTIONS` (200 com headers, ou 403 para origem não permitida); origem `"null"` → 403; adiciona `Access-Control-*` nas respostas para origens permitidas; `Allow-Credentials: true`, `Allow-Headers: Accept,Authorization,Content-Type,X-Requested-With`, `Expose-Headers: Location,Link`, `Max-Age: 0` |
+| `exceptions.ApiExceptionHandler` (`ExceptionMapper<Throwable>`) | Problem Details: `NotFoundException`→404; `WebApplicationException`→status da exceção; `ConstraintViolationException`→400 com `violations[]`; `BusinessException` (inclui `EntityNotFoundException`/`EntityInUseException`)→**400** `ERRO_NEGOCIO`; senão tenta `ApiExceptionExtension`s; fallback 500 |
+| `exceptions.ConstraintViolationExceptionMapper` (`@Priority(1)`) | sobrepõe o mapper built-in do Quarkus e delega ao handler |
+| `exceptions.spi.ApiExceptionExtension` + `DefaultApiExceptionExtension` | ponto de extensão (`tryHandle` devolve `Response` ou `null`) |
+| `exceptions.ProblemType` | URIs `https://seedgrid.com.br/<path>` |
+
+Não há endpoints REST próprios.
+
+## Testes existentes (não executados)
+
+`src/test/java/...`: `StateEnumTest`, `BusinessTimeZoneTest`, `HashUtilsTest`, `JsonAttributeLimitsTest`, `JsonAttributeMergerTest`, `UUIDv7Test`, `Valid{BirthDate,Email,Name,Password,Phone}ValidatorTest`, `CorsConfigTest`, `CorsFilterTest`, `ApiExceptionHandlerTest` — todos unitários (nenhum `@QuarkusTest`; ~115 anotações `@Test` por grep). **Não executados.**
+
+## Limitações
+
+- `EntityNotFoundException` e `EntityInUseException` resultam em **400** (caem no ramo `BusinessException`); para 404/409 é preciso lançar `WebApplicationException`/`NotFoundException`. **Confirmado** (`ApiExceptionHandler#toResponse`).
+- `@ValidBirthDate` tem mensagem default `{br.com.seedgrid.subdomaintenancy.validation.BirthDateIsValid.message}` — chave de bundle de outra extension; não há `ValidationMessages.properties` nesta lib. **Confirmado** (busca de resources vazia).
+- `Address`/`Contact` dependem do modo de criptografia da lib privacy (`seedgrid.privacy.*`) — ver [[SeedGrid/Extensions/privacy/Configuracao|Configuração do privacy]].
+- `CorsFilter` é próprio e convive com o CORS nativo do Quarkus (`quarkus.http.cors.*`); interação não documentada — **Não confirmado**.

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

@@ -0,0 +1,122 @@
+---
+tags: [seedgrid, extension, exchange, quarkus, configuracao]
+fonte: java/seedgrid-quarkus-ext-exchange
+branch: main
+commit: 30f1fd6005
+analisado-em: 2026-10-14
+---
+
+# Exchange (Quarkus): configuração
+
+Voltar para [[SeedGrid/Extensions/exchange/Visao-geral|Visão geral do exchange]] · [[SeedGrid/Extensions/exchange/Exemplos|Exemplos]]
+
+## 1. Cabeçalho
+
+| Item | Valor |
+|---|---|
+| Prefixos | `seedgrid.exchange.*` e `seedgrid.app.business-timezone` (chave compartilhada) |
+| Mecanismo | só `@ConfigProperty`. Não há `@ConfigMapping`, `@ConfigRoot` nem `microprofile-config.properties` no runtime. |
+| Classes | `ExchangeEntityManager`, `ExchangeTimeZone` |
+| Fase | runtime |
+| Configuração em banco | tabela `currencies`, uma linha por moeda. Fonte, cron, fuso, retry e caminhos JSON são **cadastro**, não propriedades (seção 2.2). |
+
+Abreviação usada na coluna Origem: `rt/` = `java/seedgrid-quarkus-ext-exchange/runtime/src/main/java/br/com/seedgrid/exchange/`.
+
+Variáveis de ambiente pela regra MP, sem ambiguidade:
+- `seedgrid.exchange.persistence-unit` → `SEEDGRID_EXCHANGE_PERSISTENCE_UNIT`
+- `seedgrid.app.business-timezone` → `SEEDGRID_APP_BUSINESS_TIMEZONE`
+
+## 2. Propriedades
+
+### 2.1 Propriedades lidas pela extension
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `seedgrid.exchange.persistence-unit` | Optional\<String\> | nome de PU; vazio ou `<default>` = PU default | — (PU default) | Não | Escolhe o `EntityManager` das tabelas `currencies` e `currency_exchange_rates`. | `ExchangeEntityManager` → `CurrencyEntityRepository`, `CurrencyExchangeRateEntityRepository` | O subdomain-tenancy define `master` (**Confirmado** no microprofile-config dele). As entidades `br.com.seedgrid.exchange.entities` devem estar mapeadas nessa PU. | runtime | `rt/repositories/ExchangeEntityManager.java` (construtor) |
+| `seedgrid.app.business-timezone` | String (ZoneId) | `ZoneId` válido | `America/Sao_Paulo` | Não | Fuso usado para **apresentar** o horário do próximo retry nos avisos (`exchange.rate-fetch-failed`). Valor vazio ou inválido cai silenciosamente em `America/Sao_Paulo`, sem log. **Não** afeta o cron das moedas, que usa `currencies.time_zone`. | `ExchangeTimeZone#zoneId` → `CurrencyRateFetchService` | **Chave compartilhada**: declarada também em `seedgrid-quarkus-lib-commons` (`commons/core/time/BusinessTimeZone`). Ver [[SeedGrid/Extensions/commons/Configuracao|Configuração do commons]]. | runtime | `rt/config/ExchangeTimeZone.java` (construtor) |
+
+### 2.2 Configuração em banco (`currencies`, por moeda)
+
+| Coluna | Default (entidade/DDL) | Efeito |
+|---|---|---|
+| `code` | — (único, ex.: `USD-BRL`) | Identifica a moeda. O job se chama `currency-rate-<code>`. |
+| `source_url` | — (obrigatória) | URL da cotação do dia. Aceita `{date:FMT}` e `{date-Nd:FMT}`. |
+| `fetch_cron` | — (obrigatória) | Cron Quartz do job da moeda. Se for inválido, o admin recebe erro ao salvar. |
+| `time_zone` | `America/Sao_Paulo` | Fuso do cron e dos marcadores de data. |
+| `retry_offsets_hours` | `4,5,3` | Horas entre tentativas após falha. Vazio desliga o retry. Entradas inválidas são ignoradas. |
+| `rate_json_path` | — | Caminho do valor (ex.: `value[0].cotacaoVenda`). Vazio usa a convenção AwesomeAPI (`bid`). |
+| `quoted_at_json_path` | — | Caminho da data/hora da cotação. |
+| `history_url` | — | URL da série histórica (`{rangeStart:FMT}`, `{date:FMT}`). Vazio faz o gráfico usar só as coletas diárias. |
+| `active` | `true` | Moeda inativa não é agendada nem buscada. |
+
+Origem: `rt/entities/CurrencyEntity.java`, `rt/dtos/CurrencyUpsertRequest.java`, `runtime/src/main/resources/db/migration/exchange/V802__seed_currencies.sql`. A seed V802 cria `USD-BRL` com a fonte PTAX/BCB, `cotacaoVenda`, cron às 7h e fuso `America/Sao_Paulo`.
+
+### 2.3 Propriedades de outras extensions que governam o exchange
+
+| Propriedade | Dona | Padrão | Efeito |
+|---|---|---|---|
+| `seedgrid.exchange.migration.enabled` | login-tenancy (`LoginTenancyMigrationService`) e subdomain-tenancy (`flyway/MigrationService`) | `false` | Aplica `classpath:db/migration/exchange` com a tabela `flyway_schema_history_exchange`. Não é lida pela extension. |
+
+## 3. Propriedades de frameworks
+
+A extension não define nenhuma. Recomendações extraídas do `integration-tests` e do README:
+
+| Propriedade | Recomendação |
+|---|---|
+| `quarkus.flyway.locations` / `quarkus.flyway.table` | `db/migration/exchange` / `flyway_schema_history_exchange` (Flyway nativo). Nos tenancies, use `seedgrid.exchange.migration.enabled`. |
+| `quarkus.hibernate-orm.physical-naming-strategy` | `org.hibernate.boot.model.naming.CamelCaseToUnderscoresNamingStrategy` |
+| `quarkus.hibernate-orm.<pu>.packages` | Incluir `br.com.seedgrid.exchange.entities` na PU configurada (no subdomain-tenancy, só master). |
+| `quarkus.scheduler.enabled` | Os testes usam `false` para controlar os disparos. Em produção, deixe ligado. |
+
+## 4. Propriedades usadas só em testes
+
+Arquivo `integration-tests/src/test/resources/application.properties`:
+- `quarkus.devservices.enabled=false`
+- `quarkus.flyway.migrate-at-start=true`
+- `quarkus.flyway.locations=db/migration/exchange,db/migration/exchange-test`
+- `quarkus.flyway.table=flyway_schema_history_exchange`
+- `quarkus.flyway.baseline-on-migrate=true`
+- naming strategy
+- `quarkus.hibernate-orm.schema-management.strategy=none`
+- `quarkus.scheduler.enabled=false`
+- `quarkus.http.test-port=0`
+- `app.build.version=test`: exigido pelo `StartupBannerLogger` do commons. No host, o valor vem do build.
+
+## 5. Aliases, obsoletas e renomeações
+Não encontradas. Atenção: `seedgrid.app.business-timezone` é diferente de `seedgrid.billing.business-timezone` (ver [[SeedGrid/Extensions/billing/Configuracao|Configuração do billing]]).
+
+## 6. Configuração mínima
+Nenhuma propriedade é obrigatória. Nos tenancies:
+
+```properties
+seedgrid.exchange.migration.enabled=true
+```
+
+## 7. Configuração completa comentada
+
+```properties
+# PU das tabelas de câmbio. Sem valor ou <default> = PU default. subdomain-tenancy: master.
+#seedgrid.exchange.persistence-unit=master
+
+# Fuso de exibição do horário do próximo retry nos avisos (compartilhado com o commons).
+# Default America/Sao_Paulo.
+seedgrid.app.business-timezone=America/Sao_Paulo
+
+# (tenancies) aplicar V800-V804. Default false.
+seedgrid.exchange.migration.enabled=true
+```
+
+## 8. Receitas
+
+| Caso | Como |
+|---|---|
+| Produto sem câmbio | Não aplicar a faixa 8xx. A app sobe com WARN "Módulo de câmbio inativo". |
+| Trocar a fonte de cotação | `PUT /admin/currencies/{id}` com novos `sourceUrl` e `rateJsonPath`. Reagenda sem deploy. |
+| Mudar a grade de retry | `retryOffsetsHours: "2,2,4"`. Com `""`, o retry automático fica desligado. |
+| Corrigir a cotação de um dia | `PUT /admin/currency-exchange-rates/{id}` com `{ "rate": 5.4321 }`, ou `POST .../{id}/retry`. |
+| subdomain-tenancy | `seedgrid.exchange.persistence-unit=master` (já definido pela extension de tenancy). |
+
+## 9. Dúvidas e lacunas
+- O intervalo do drain (`every = "10m"`) e os timeouts HTTP (10s/15s) estão fixos em código.
+- `history_url` não faz parte de `CurrencyUpsertRequest`: só a seed ou SQL direto definem esse valor.
+- `ExchangeTimeZone` engole o fuso inválido sem log, ao contrário do `BusinessTimeZone` do billing, que registra WARN.

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

@@ -0,0 +1,29 @@
+---
+tags: [seedgrid, extension, exchange, quarkus, enum]
+fonte: java/seedgrid-quarkus-ext-exchange
+branch: main
+commit: 30f1fd6005
+analisado-em: 2026-10-14
+---
+
+# Exchange (Quarkus): enums
+
+Voltar para [[SeedGrid/Extensions/exchange/Visao-geral|Visão geral]] · [[SeedGrid/Extensions/exchange/Configuracao|Configuração]].
+
+| Enum | Arquivo | Usado em | Público? |
+|---|---|---|---|
+| `CurrencyExchangeRateStatus` | `runtime/src/main/java/br/com/seedgrid/exchange/entities/CurrencyExchangeRateStatus.java` | coluna `currency_exchange_rates.status`; respostas de `/admin/currency-exchange-rates` | sim |
+
+## CurrencyExchangeRateStatus
+FQN `br.com.seedgrid.exchange.entities.CurrencyExchangeRateStatus`. Sem campos nem métodos. Persistido com `@Enumerated(EnumType.STRING)` em `status varchar(16) not null` (V800), **sem CHECK constraint**. Não é tipo de propriedade de configuração. No JSON aparece pelo nome da constante (sem `@JsonValue`).
+
+| Valor | Significado | Efeito / onde é tratado | Observações |
+|---|---|---|---|
+| `SUCCESS` | Cotação obtida da fonte. | `CurrencyRateFetchService` grava ao aplicar uma busca bem-sucedida. A importação de histórico (`insertImportedIfMissing`) também insere com `SUCCESS`. | Confirmado. |
+| `FAILED` | Busca falhou. | Gravado em falha, com `errorMessage`, `attemptCount` incrementado e `next_retry_at` pela grade `retryOffsetsHours` da moeda. Elegível ao retry automático e manual. | Confirmado. |
+| `MANUAL` | Valor digitado pelo admin. | `PUT /admin/currency-exchange-rates/{id}`. | Confirmado. |
+
+A cotação "mais recente válida" (`latestGoodFor`, usada por `/admin/exchange-rate`) **não filtra por status**: seleciona a linha de maior `reference_date` com `rate` não nulo. Como `FAILED` não tem `rate`, fica de fora, e `MANUAL` conta. **Confirmado** em `CurrencyExchangeRateEntityRepository#latestGoodFor`.
+
+## Internos
+Nenhum.

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

@@ -0,0 +1,82 @@
+---
+tags: [seedgrid, extension, exchange, quarkus, exemplos]
+fonte: java/seedgrid-quarkus-ext-exchange
+branch: main
+commit: 30f1fd6005
+analisado-em: 2026-10-14
+---
+
+# Exchange (Quarkus): exemplos
+
+Ver [[SeedGrid/Extensions/exchange/Visao-geral|Visão geral]] e [[SeedGrid/Extensions/exchange/Configuracao|Configuração]].
+
+## 1. Dependência
+
+Fonte: README.
+
+```xml
+<dependency>
+    <groupId>br.com.seedgrid</groupId>
+    <artifactId>seedgrid-exchange</artifactId>
+    <version>2026.10.14</version>
+</dependency>
+```
+
+Security e audit-core vêm do host. Nos tenancies, ligue também `seedgrid.exchange.migration.enabled=true`.
+
+## 2. Cadastrar uma moeda com fonte PTAX
+
+Fontes: `CurrencyUpsertRequest` e seed `V802__seed_currencies.sql`. Requer `CURRENCY_CREATE`.
+
+```http
+POST /admin/currencies
+Content-Type: application/json
+
+{
+  "code": "USD-BRL",
+  "name": "Dolar americano / Real",
+  "sourceUrl": "https://olinda.bcb.gov.br/olinda/servico/PTAX/versao/v1/odata/CotacaoDolarPeriodo(dataInicial=@dataInicial,dataFinalCotacao=@dataFinalCotacao)?@dataInicial='{date-10d:MM-dd-yyyy}'&@dataFinalCotacao='{date:MM-dd-yyyy}'&$format=json&$orderby=dataHoraCotacao%20desc&$top=1",
+  "fetchCron": "0 0 7 * * ?",
+  "timeZone": "America/Sao_Paulo",
+  "retryOffsetsHours": "4,5,3",
+  "rateJsonPath": "value[0].cotacaoVenda",
+  "quotedAtJsonPath": "value[0].dataHoraCotacao",
+  "active": true
+}
+```
+
+Os valores acima são os mesmos da seed V802. A seed também grava `history_url`, mas `CurrencyUpsertRequest` **não tem** esse campo: pela API REST não dá para definir `historyUrl`. **Confirmado** pela leitura do record.
+
+- `code`, `name`, `sourceUrl` e `fetchCron` são obrigatórios (`@NotBlank`).
+- No `PUT`, `retryOffsetsHours`, `rateJsonPath` e `quotedAtJsonPath` com `null` mantêm o valor gravado.
+
+## 3. Consultar cotações
+
+Fonte: `AdminCurrencyExchangeRateResource`, `AdminExchangeRateResource`.
+
+```http
+GET /admin/currency-exchange-rates?currencyCode=USD-BRL&from=2026-10-01&to=2026-10-14&page=0&size=30
+GET /admin/currency-exchange-rates/series?currencyCode=USD-BRL&days=30
+GET /admin/exchange-rate        # { "rate": ..., "updatedAt": ..., "source": ... } (última USD-BRL válida)
+```
+
+## 4. Corrigir manualmente ou reprocessar
+
+Fonte: `ManualRateRequest(@NotNull @Positive BigDecimal rate)`. Requer `CURRENCY_RATE_UPDATE`.
+
+```http
+PUT  /admin/currency-exchange-rates/{publicId}
+Content-Type: application/json
+
+{ "rate": 5.4321 }
+
+POST /admin/currency-exchange-rates/{publicId}/retry
+```
+
+## 5. Configuração (properties)
+
+```properties
+seedgrid.exchange.migration.enabled=true          # tenancies
+#seedgrid.exchange.persistence-unit=master        # subdomain-tenancy já define
+seedgrid.app.business-timezone=America/Sao_Paulo  # fuso dos avisos
+```

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

@@ -0,0 +1,118 @@
+---
+tags: [seedgrid, extension, exchange, quarkus]
+fonte: java/seedgrid-quarkus-ext-exchange
+branch: main
+commit: 30f1fd6005
+analisado-em: 2026-10-14
+---
+
+# Exchange (Quarkus): visão geral
+
+Câmbio para hosts Quarkus. Mantém moedas e cotações diárias, com histórico e série para gráfico. As fontes de cotação são configuráveis por cadastro (URL com marcadores de data e caminho JSON do valor). Há retry automático (grade de horas por moeda) e manual. A seed padrão é USD-BRL via PTAX do Banco Central. Não há crate Rust equivalente.
+
+- Configuração: [[SeedGrid/Extensions/exchange/Configuracao|Configuração do exchange]]
+- Exemplos: [[SeedGrid/Extensions/exchange/Exemplos|Exemplos do exchange]]
+- Enums: [[SeedGrid/Extensions/exchange/Enums|Enums do exchange]]
+
+## Módulos e coordenadas
+
+| Módulo | Artefato |
+|---|---|
+| parent | `br.com.seedgrid:seedgrid-exchange-parent:2026.10.14` (parent `seedgrid-parent:2026.07.02`) |
+| runtime | `br.com.seedgrid:seedgrid-exchange` |
+| deployment | `br.com.seedgrid:seedgrid-exchange-deployment` |
+| integration-tests | não publicado |
+
+A feature Quarkus é `seedgrid-exchange` (`SeedgridExchangeProcessor`). O processor registra services, scheduler, resources e `NoOpExchangeAuditSink` como *unremovable*.
+
+> Usa Java 21 e Quarkus **3.30.6**: o `pom.xml` do módulo sobrescreve `quarkus.platform.version` (o `seedgrid-parent` usa 3.30.8). O `runtime/src/main/resources/META-INF/quarkus-extension.properties` declara `deployment-artifact=...:1.0.0-SNAPSHOT` como valor fixo. **Confirmado** nos arquivos.
+
+### Dependências
+- SeedGrid: `seedgrid-commons` 2026.10.08, `seedgrid-security` 2026.10.09, `seedgrid-audit-core` 2026.09.25 e `seedgrid-notification-api`.
+- Quarkus: `arc`, `rest-jackson`, `hibernate-orm` (JPA puro), `scheduler`, `security` e `hibernate-validator`.
+
+## Arquitetura
+
+```mermaid
+flowchart LR
+    BOOT[StartupEvent] --> SCH[CurrencyRateScheduler]
+    SCH -->|1 job por moeda ativa: cron + fuso da linha| FETCH[CurrencyRateFetchService.fetchToday]
+    SCH -->|every 10m| DRAIN[drainPendingRetries]
+    DRAIN --> FETCH
+    FETCH -->|HttpClient, URL resolvida| SRC((fonte: PTAX/AwesomeAPI...))
+    FETCH --> DB[(currency_exchange_rates)]
+    FETCH -. exchange.rate-fetch-failed .-> NOTIF[notification-api]
+```
+
+### Scheduler
+
+Componente: `CurrencyRateScheduler`.
+
+- Cria **um job por moeda ativa** (`currency-rate-<code>`), com `fetch_cron` e `time_zone` da própria linha em `currencies`.
+- No startup, para cada moeda ativa sem cotação do dia, dispara a busca na hora.
+- Se a tabela não existir, registra WARN e sai sem derrubar o boot (`ModuloDesligadoTest`).
+- `@Scheduled(every = "10m")` drena os retries vencidos. O estado do retry fica no banco (`next_retry_at`).
+- Retry vencido de um dia anterior é descartado, nunca gravado com a cotação de hoje.
+- Ao criar, editar, renomear ou excluir uma moeda, o job é reagendado sem restart.
+
+### Resolução da fonte
+
+Componente: `CurrencySourceResolver`.
+
+- Marcadores aceitos na URL: `{date:FMT}`, `{date-Nd:FMT}` e `{rangeStart:FMT}`.
+- O caminho JSON do valor segue o formato `value[0].cotacaoVenda`.
+- Com o caminho vazio, vale a convenção AwesomeAPI: campo `bid` do único objeto raiz.
+
+### Busca HTTP
+
+Componente: `CurrencyRateFetchService`. Usa connect timeout de 10s e request de 15s.
+
+## APIs públicas
+
+### SPI
+| SPI | Default | Assinatura |
+|---|---|---|
+| `ExchangeAuditSink` | `NoOpExchangeAuditSink` | `record(String actionType, String targetType, String targetId, String summary, Map<String,Object> details)`. O README o chama de legado: a auditoria é feita via `@Audit`. |
+
+### Endpoints REST (`RestControllerPath`)
+Todos os resources são `@MonoCompany @Authenticated`.
+
+| Método | Caminho | Permissão |
+|---|---|---|
+| GET | `/admin/currencies` | `CURRENCY_READ` |
+| GET | `/admin/currencies/{id}` | `CURRENCY_READ` |
+| POST | `/admin/currencies` | `CURRENCY_CREATE` |
+| PUT | `/admin/currencies/{id}` | `CURRENCY_UPDATE` |
+| DELETE | `/admin/currencies/{id}` | `CURRENCY_DELETE` |
+| GET | `/admin/currency-exchange-rates?currencyCode&from&to&page=0&size=30` | `CURRENCY_RATE_READ` |
+| GET | `/admin/currency-exchange-rates/series?currencyCode&days=30` | `CURRENCY_RATE_READ` |
+| POST | `/admin/currency-exchange-rates/{id}/retry` | `CURRENCY_RATE_UPDATE` |
+| PUT | `/admin/currency-exchange-rates/{id}` (`{rate}`, edição manual) | `CURRENCY_RATE_UPDATE` |
+| GET | `/admin/exchange-rate` (última USD-BRL válida: `rate`, `updatedAt`, `source`) | só autenticado |
+
+Os `{id}` são `publicId`. **Confirmado** nos resources.
+
+### Evento de notificação
+`exchange.rate-fetch-failed` (`ExchangeNotificationCatalog`), publicado após o commit da tentativa. O evento inclui a variável `reason`, com o horário do próximo retry no fuso `seedgrid.app.business-timezone`.
+
+## Migrations
+`db/migration/exchange`, de **V800 a V804**. Histórico em `flyway_schema_history_exchange`.
+
+| Versão | Conteúdo |
+|---|---|
+| V800 | tabelas |
+| V801 | permissões `CURRENCY_*`, audience `platform`, vinculadas a `ADMIN` |
+| V802 | seed USD-BRL: PTAX, cron às 7h, São Paulo |
+| V803 | histórico PTAX sem `$select` |
+| V804 | `currency_exchange_rates.active` |
+
+Nos tenancies, o runner só aplica essas migrations com `seedgrid.exchange.migration.enabled=true` (default `false`).
+
+## Testes (não executados)
+- `runtime/src/test`: `CurrencyRateNotificationTest`, `CurrencySourceResolverTest` e `ExchangeNotificationCatalogTest`.
+- `integration-tests`: `ExchangePermissionMigrationTest`, `ExchangeSchemaAndPersistenceTest`, `ModuloDesligadoTest`, `CurrencyRateSchedulerTest`, `CurrencyRateFetchServiceTest` e `CurrencyRateHistoryTest`. Usam a migration de teste `V899__test_remove_moeda_semeada`.
+
+## Limitações
+- `/admin/exchange-rate` é um atalho fixo para `USD-BRL`.
+- O drain de retry é fixo em 10 minutos, sem propriedade para mudar.
+- O fuso padrão `America/Sao_Paulo` está repetido em código: em `ExchangeTimeZone`, como default do `applySchedule` e como default da coluna.