@seedgrid/ai-toolkit 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,110 @@
+---
+tags: [seedgrid, extension, filemanagement, rust, configuracao]
+fonte: rust/seedgrid-rust-crate-filemanagent
+branch: main
+commit: be738a2d1e
+analisado-em: 2026-10-14
+---
+
+# filemanagement — Configuração Rust
+
+Visão do crate: [[SeedGrid/Extensions/filemanagement/Rust|Porte Rust do filemanagement]] · Java: [[SeedGrid/Extensions/filemanagement/Configuracao|Configuração do filemanagement (Java)]].
+
+## Cabeçalho
+| Item | Valor |
+|---|---|
+| Mecanismo | **não lê variáveis de ambiente** nem tem struct de config: cada backend recebe um `HashMap<String, String>` em `FileStorageRegistry::get(tipo, &config)` → `FileStorageFactory::create(&config)` |
+| Equivalente Java | idem: `Map<String,String>` passado ao registry; sem `@ConfigMapping` |
+| Seleção de backend | pelo `tipo` passado ao registry (`type_identifier`); disponibilidade depende das features Cargo |
+| Leitura | na criação do storage (`create`), uma vez por `(tipo, config)` (cache do registry) |
+| Verificação | `grep` por `env::var` em `src/` não encontra nada (**Confirmado**); só `tests/minio_smoke.rs` lê env |
+
+Quem fornece o mapa no workspace: `seedgrid-rust-crate-backup` (`BackupConfig::build_storage_config`, ver [[SeedGrid/Extensions/backup/Configuracao-Rust|Configuração Rust do backup]]) e o exemplo `seedgrid-filemanagement-example` (env `MINIO_*`).
+
+## Chaves por backend
+A coluna "Leitura" é sempre `create(&config)`. Valores são `trim`ados e vazios contam como ausentes, salvo indicação.
+
+### filesystem (sempre disponível)
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `base-path` | String | caminho de diretório | — | Sim | cria o diretório se faltar; valida que é diretório e gravável (arquivo de teste `.seedgrid-write-test-*`) | `FilesystemStorage` | — | `create` | `src/factories.rs` → `FilesystemStorageFactory::create` |
+
+### s3 (feature `s3`)
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `bucket` | String | nome | — | Sim | bucket alvo | `S3CompatStorage` | — | `create` | `src/providers/s3.rs` → `S3StorageFactory` |
+| `region` | String | região AWS | `us-east-1` | Não | sem `endpoint`, precisa ser região válida (`Invalid S3 region`) | idem | `endpoint` | `create` | idem |
+| `endpoint` | String | URL | — | Não | se presente: região custom + **path-style** (MinIO/LocalStack) | idem | — | `create` | idem |
+| 🔒 `access-key` / 🔒 `secret-key` | String | texto | — | Não | só usadas se **ambas** presentes; senão cadeia default de credenciais do `rust-s3` | idem | — | `create` | `credentials_from` |
+
+Cadeia default: o comentário do código diz "env/perfil/instância, igual ao Java"; os nomes exatos das variáveis vêm da biblioteca `rust-s3` (**Inferência**: variáveis AWS padrão como `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY`; não verificado na dependência).
+
+### minio (feature `s3` ou `minio`)
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `endpoint` | String | URL | — | Sim | sempre path-style | `S3CompatStorage` | — | `create` | `src/providers/s3.rs` → `MinioStorageFactory` |
+| 🔒 `access-key` | String | texto | — | Sim | | idem | — | `create` | idem |
+| 🔒 `secret-key` | String | texto | — | Sim | | idem | — | `create` | idem |
+| `bucket` | String | nome | — | Sim | | idem | — | `create` | idem |
+| `region` | String | texto | `us-east-1` | Não | | idem | — | `create` | idem |
+
+### azure-blob (feature `azure`)
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `container` | String | nome | — | Sim | criado se não existir (`ensure_container`) | `AzureBlobStorage` | — | `create` | `src/providers/azure.rs` → `AzureBlobStorageFactory` |
+| 🔒 `connection-string` | String | `AccountName=...;AccountKey=...;[EndpointSuffix=...;DefaultEndpointsProtocol=...]` | — | Condicional: ela **ou** `account-name`+`account-key` | tem precedência; `EndpointSuffix` padrão `core.windows.net`, protocolo padrão `https` | idem | — | `create` | `parse_connection_string` |
+| `account-name` | String | texto | — | Condicional | host `https://<conta>.blob.core.windows.net` | idem | `account-key` | `create` | idem |
+| 🔒 `account-key` | String | base64 | — | Condicional | assinatura SharedKey | idem | `account-name` | `create` | idem |
+
+### gcs (feature `gcs`)
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `bucket` | String | nome | — | Sim | | `GcsStorage` | — | `create` | `src/providers/gcs.rs` |
+| `project-id` | String | texto | — | Sim | só validado (paridade com o Java) | — | — | `create` | idem |
+| `credentials-file` | String | caminho de JSON de service account | — | Condicional: um dos dois | lido do disco; tem precedência | `GoogleTokenProvider` | `credentials-json` | `create` | `src/providers/google_auth.rs` → `from_config` |
+| 🔒 `credentials-json` | String | JSON de service account | — | Condicional | usado se não houver `credentials-file` | idem | — | `create` | idem |
+
+### google-drive (feature `google-drive`)
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `root-folder-id` | String | id da pasta | — | Sim | pasta raiz | `GoogleDriveStorage` | — | `create` | `src/providers/drive.rs` |
+| `credentials-file` / 🔒 `credentials-json` | String | idem GCS | — | Condicional (um dos dois) | idem GCS | `GoogleTokenProvider` | — | `create` | `google_auth.rs` |
+
+### onedrive (feature `onedrive`)
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `client-id` | String | texto | — | Sim | OAuth client-credentials | `OneDriveStorage` | os três juntos | `create` | `src/providers/onedrive.rs` |
+| 🔒 `client-secret` | String | texto | — | Sim | | idem | | `create` | idem |
+| `tenant-id` | String | texto | — | Sim | | idem | | `create` | idem |
+| `root-folder-path` | String | caminho | `/seedgrid/files` | Não | pasta raiz | idem | — | `create` | idem |
+
+## Features Cargo
+| Feature | Padrão | Efeito |
+|---|---|---|
+| (nenhuma) | sim | só `filesystem` |
+| `s3` | não | registra `s3` **e** `minio` em `BuiltInStorageFactories::all()` |
+| `minio` | não | alias de `s3` |
+| `azure` | não | `azure-blob` |
+| `gcs` | não | `gcs` (+ `_google-auth`) |
+| `google-drive` | não | `google-drive` (+ `_google-auth`) |
+| `onedrive` | não | `onedrive` |
+| `full` | não | todos |
+| `_google-auth` | não | interna (JWT RS256 de service account) |
+
+## Somente testes / exemplos
+| Variável | Onde |
+|---|---|
+| `MINIO_ENDPOINT`, `MINIO_ACCESS_KEY` 🔒, `MINIO_SECRET_KEY` 🔒, `MINIO_BUCKET` | `examples/seedgrid-filemanagement-example/src/main.rs` (`env_or`) e `tests/minio_smoke.rs` |
+
+## Configuração mínima
+```rust
+let mut cfg = HashMap::new();
+cfg.insert("base-path".into(), "/var/seedgrid/files".into());
+let storage = FileStorageRegistry::new(BuiltInStorageFactories::all())?.get("filesystem", &cfg)?;
+```
+
+## Receitas
+- **MinIO**: compile com `features = ["s3"]`; mapa `endpoint`, `access-key`, `secret-key`, `bucket` (+ `region`).
+- **AWS S3 com credenciais da instância**: `features = ["s3"]`; mapa só com `bucket` (+ `region`).
+- **Azure**: `features = ["azure"]`; `container` + `connection-string` (`<SEGREDO:azure-connection-string>`).
+- **GCS / Drive**: `credentials-file` apontando para o JSON da service account.

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

@@ -0,0 +1,157 @@
+---
+tags: [seedgrid, library, filemanagement, configuracao]
+fonte: java/seedgrid-quarkus-lib-filemanagement
+branch: main
+commit: 35c89c7cf7
+analisado-em: 2026-10-14
+---
+
+# SeedGrid File Management — Configuração
+
+Voltar: [[SeedGrid/Extensions/filemanagement/Visao-geral|Visão geral do filemanagement]] · [[SeedGrid/Extensions/filemanagement/Exemplos|Exemplos do filemanagement]] · [[SeedGrid/Extensions/filemanagement/Rust|Porte Rust]]
+
+## 1. Cabeçalho
+
+| Item | Valor |
+|---|---|
+| Prefixos MicroProfile Config | **Nenhum.** A lib não lê `application.properties`/env |
+| Mecanismo | **Mapa de configuração por chamada**: `FileStorageRegistry#get(String type, Map<String,String> config)` → `FileStorageFactory#create(config)`. Cada factory lê chaves fixas do mapa com `config.get(...)`/`getOrDefault(...)` |
+| Quem preenche o mapa | O host/extension consumidora, a partir de onde quiser (MP Config, env, banco, Vault). Ex.: backup mapeia `seedgrid.backup.<tipo>.*`; o exemplo usa `app.storage.*` |
+| Fase | Runtime, **lazy**: validado no primeiro `get(type, config)` com aquele conteúdo de mapa; instâncias cacheadas por (tipo + conteúdo do mapa) |
+| Arquivos de config da lib | `src/main/resources/application.properties` existe e está **vazio** |
+
+Investigação (**Confirmado**): nenhum `@ConfigMapping`, `@ConfigRoot`, `@ConfigProperty`, `ConfigProvider`, `System.getenv`/`getProperty` em `src/main`. As únicas leituras de config são `config.get/getOrDefault` nos factories em `java/seedgrid-quarkus-lib-filemanagement/src/main/java/br/com/seedgrid/filemanagement/factories/`.
+
+Como os nomes abaixo são **chaves do mapa**, não propriedades MP, não existem variáveis de ambiente associadas pela lib. A coluna "Propriedade" usa a notação `<type>` → `<chave>`.
+
+## 2. Chaves do mapa por backend
+
+### 2.1 `filesystem`
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `filesystem` → `base-path` | `String` (caminho) | diretório gravável | — | Sim | Cria o diretório se não existir; falha se não for diretório ou não for gravável (`StorageConfigurationException`) | Raiz de todos os arquivos; `prefix` vira subpasta | — | Runtime (lazy) | `FilesystemStorageFactory#create` → `FilesystemStorage(basePath)` |
+
+### 2.2 `s3`
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `s3` → `bucket` | `String` | nome de bucket | — | Sim | Ausente/vazio → `StorageConfigurationException` | Todas as operações | — | Runtime (lazy) | `S3StorageFactory#create` |
+| `s3` → `region` | `String` | região AWS (`Region.of`) | `us-east-1` | Não | Região do `S3Client` e do `S3Presigner` | Cliente/presigner | — | Runtime (lazy) | `S3StorageFactory#create` (`getOrDefault`) |
+| `s3` → `access-key` 🔒 | `String` | — | — | Condicional: só é usada se `secret-key` também vier | Com ambas, usa `StaticCredentialsProvider`; sem, usa a cadeia padrão do AWS SDK | Credenciais | par com `secret-key` | Runtime (lazy) | `S3StorageFactory.S3StorageImpl` (construtor) |
+| `s3` → `secret-key` 🔒 | `String` | — | — | Condicional (par com `access-key`) | idem | Credenciais | par com `access-key` | Runtime (lazy) | idem |
+| `s3` → `endpoint` | `String` (URI) | URL de serviço S3-compatível (MinIO, LocalStack) | — | Não | `endpointOverride` no cliente e no presigner | Cliente/presigner | — | Runtime (lazy) | idem |
+
+### 2.3 `minio`
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `minio` → `endpoint` | `String` (URL) | ex.: `http://<host>:9000` | — | Sim | Ausente → `StorageConfigurationException` | `MinioClient` | — | Runtime (lazy) | `MinIOStorageFactory#create` |
+| `minio` → `access-key` 🔒 | `String` | — | — | Sim | idem | Credenciais | — | Runtime (lazy) | idem |
+| `minio` → `secret-key` 🔒 | `String` | — | — | Sim | idem | Credenciais | — | Runtime (lazy) | idem |
+| `minio` → `bucket` | `String` | — | — | Sim | idem | Bucket alvo | — | Runtime (lazy) | idem |
+| `minio` → `region` | `String` | — | `us-east-1` | Não | Repassado ao `MinIOStorage` | Cliente | — | Runtime (lazy) | idem (`getOrDefault`) |
+
+### 2.4 `azure-blob`
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `azure-blob` → `container` | `String` | nome de container | — | Sim | Ausente → `StorageConfigurationException`; criado no init se não existir | Container alvo | — | Runtime (lazy) | `AzureBlobStorageFactory#create`; `AzureBlobStorage#initialize` |
+| `azure-blob` → `connection-string` 🔒 | `String` | connection string Azure | — | Condicional: ela **ou** `account-name`+`account-key` | Tem prioridade sobre nome+chave | Autenticação | alternativa a `account-name`/`account-key` | Runtime (lazy) | idem |
+| `azure-blob` → `account-name` | `String` | — | — | Condicional (sem `connection-string`) | Endpoint `https://<account-name>.blob.core.windows.net` + `StorageSharedKeyCredential` | Autenticação | par com `account-key` | Runtime (lazy) | idem |
+| `azure-blob` → `account-key` 🔒 | `String` | — | — | Condicional (sem `connection-string`) | idem | Autenticação | par com `account-name` | Runtime (lazy) | idem |
+
+### 2.5 `gcs` (Google Cloud Storage)
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `gcs` → `bucket` | `String` | — | — | Sim | Ausente → `StorageConfigurationException`; bucket inexistente → `StorageInitializationException` no init | Bucket alvo | — | Runtime (lazy) | `GoogleCloudStorageFactory#create`; `GoogleCloudStorage#initialize` |
+| `gcs` → `project-id` | `String` | — | — | Sim | Ausente → `StorageConfigurationException` | `StorageOptions.setProjectId` | — | Runtime (lazy) | idem |
+| `gcs` → `credentials-file` 🔒 | `String` (caminho de JSON de service account) | — | — | Condicional: ela **ou** `credentials-json` (o factory não valida, mas o init lança `StorageInitializationException` sem nenhuma) | Tem prioridade sobre `credentials-json` | `ServiceAccountCredentials.fromStream` | alternativa a `credentials-json` | Runtime (lazy) | `GoogleCloudStorage#initialize` |
+| `gcs` → `credentials-json` 🔒 | `String` (conteúdo JSON) | — | — | Condicional (ver acima) | Usada se não houver `credentials-file` | idem | alternativa | Runtime (lazy) | idem |
+
+### 2.6 `google-drive`
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `google-drive` → `root-folder-id` | `String` | ID de pasta do Drive | — | Sim | Ausente → `StorageConfigurationException`; vira o `bucket` da `StorageKey` | Pasta raiz dos uploads | — | Runtime (lazy) | `GoogleDriveStorageFactory#create` |
+| `google-drive` → `credentials-file` 🔒 | `String` (caminho) | JSON de service account | — | Condicional: ela **ou** `credentials-json` (validado no factory) | Prioridade sobre `credentials-json`; escopo `drive.file` | Autenticação | alternativa | Runtime (lazy) | `GoogleDriveStorageFactory#create`; `GoogleDriveStorage` (construtor) |
+| `google-drive` → `credentials-json` 🔒 | `String` (conteúdo JSON) | — | — | Condicional | idem | Autenticação | alternativa | Runtime (lazy) | idem |
+
+### 2.7 `onedrive`
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `onedrive` → `client-id` | `String` | App registration Azure AD | — | Sim | Qualquer das três ausente → `StorageConfigurationException` | `ClientSecretCredential` | com `client-secret`, `tenant-id` | Runtime (lazy) | `OneDriveStorageFactory#create`; `OneDriveStorage` (construtor) |
+| `onedrive` → `client-secret` 🔒 | `String` | — | — | Sim | idem | idem | idem | Runtime (lazy) | idem |
+| `onedrive` → `tenant-id` | `String` | tenant Azure AD (não é tenant da aplicação) | — | Sim | idem | idem | idem | Runtime (lazy) | idem |
+| `onedrive` → `root-folder-path` | `String` | caminho no drive | `/seedgrid/files` | Não | Pasta raiz; vira o `bucket` da `StorageKey` | Uploads | — | Runtime (lazy) | `OneDriveStorageFactory#create` (`getOrDefault`) |
+
+## 3. Propriedades de frameworks
+
+Nenhuma exigida. Não é necessário `quarkus.index-dependency.*`: o jar empacota `META-INF/jandex.idx` (`jandex-maven-plugin` no pom; confirmado também em comentário de `java/examples/seedgrid-filemanagement-example/src/main/resources/application.properties`).
+
+## 4. Propriedades só de testes/exemplos
+
+| Propriedade | Onde | Observação |
+|---|---|---|
+| `quarkus.log.level`, `quarkus.log.category."br.com.seedgrid".level` | idem | logging de teste |
+| `app.storage.type` (default `filesystem` no `@ConfigProperty`), `app.storage.filesystem.base-path` | `java/examples/seedgrid-filemanagement-example` → `DocumentStorageService` | propriedades **do exemplo**, que montam o mapa `Map.of("base-path", basePath)` |
+
+## 5. Aliases, obsoletas, renomeações
+
+Nenhuma propriedade da lib (ela não lê MicroProfile Config).
+
+- Mapeamentos feitos por consumidores (não pertencem a esta lib): backup `seedgrid.backup.<tipo>.*` → chaves acima (`ExportService#buildStorageConfig`); security (avatar) em `UserAvatarService#buildStorageConfig`. Detalhes nas notas de cada extension: [[SeedGrid/Extensions/backup/Configuracao|Configuração do backup]], [[SeedGrid/Extensions/security/Configuracao|Configuração do security]].
+
+## 6. Configuração mínima
+
+Não há `application.properties` da lib. Mínimo no código do host:
+
+```java
+FileStorage storage = registry.get("filesystem", Map.of("base-path", "/var/data/files"));
+```
+
+## 7. Configuração completa comentada (mapas por backend)
+
+```java
+// filesystem
+Map.of("base-path", "/var/data/files");
+
+// s3 (credenciais opcionais: sem elas usa a cadeia padrão do AWS SDK)
+Map<String, String> s3 = new HashMap<>();
+s3.put("bucket", "<bucket>");
+s3.put("region", "us-east-1");                     // padrão us-east-1
+s3.put("access-key", "<SEGREDO:aws-access-key>");
+s3.put("secret-key", "<SEGREDO:aws-secret-key>");
+s3.put("endpoint", "http://<host>:9000");          // opcional (S3-compatível)
+
+// minio (todas obrigatórias, exceto region)
+Map.of("endpoint", "http://<host>:9000", "access-key", "<SEGREDO:minio-access-key>",
+       "secret-key", "<SEGREDO:minio-secret-key>", "bucket", "<bucket>");
+
+// azure-blob: container + (connection-string OU account-name + account-key)
+Map.of("container", "<container>", "connection-string", "<SEGREDO:azure-connection-string>");
+
+// gcs: bucket + project-id + (credentials-file OU credentials-json)
+Map.of("bucket", "<bucket>", "project-id", "<project>", "credentials-file", "/etc/<sa>.json");
+
+// google-drive: root-folder-id + (credentials-file OU credentials-json)
+Map.of("root-folder-id", "<folder-id>", "credentials-json", "<SEGREDO:google-sa-json>");
+
+// onedrive
+Map.of("client-id", "<client-id>", "client-secret", "<SEGREDO:onedrive-client-secret>",
+       "tenant-id", "<azure-tenant-id>", "root-folder-path", "/seedgrid/files");
+```
+
+## 8. Receitas
+
+- **Guardar a config em `application.properties` do host**: declare propriedades próprias (ex.: `app.storage.*`) com `@ConfigProperty` e monte o mapa — padrão do exemplo `DocumentStorageService`.
+- **Vários buckets do mesmo tipo**: chame `registry.get("s3", configA)` e `registry.get("s3", configB)`; o cache separa por conteúdo do mapa.
+- **Trocar de backend sem mudar código de negócio**: parametrize o `type` (ex.: `app.storage.type`) e monte o mapa por tipo, como faz `ExportService#buildStorageConfig` no backup.
+- **Backend novo**: implemente `FileStorageFactory` (`@ApplicationScoped`) com `typeIdentifier` único e valide as chaves em `create`.
+
+## 9. Dúvidas e lacunas
+
+- Para usar um backend de nuvem o host precisa declarar o SDK (dependências `optional` no pom) — **Inferência**; sem ele, `create` deve falhar com `NoClassDefFoundError` (não testado).
+- Equivalência com a config do crate Rust: [[SeedGrid/Extensions/filemanagement/Configuracao-Rust|Configuração Rust do filemanagement]].

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

@@ -0,0 +1,157 @@
+---
+tags: [seedgrid, library, filemanagement, exemplos]
+fonte: java/seedgrid-quarkus-lib-filemanagement, java/examples/seedgrid-filemanagement-example
+branch: main
+commit: 35c89c7cf7
+analisado-em: 2026-10-14
+---
+
+# SeedGrid File Management — Exemplos
+
+Voltar: [[SeedGrid/Extensions/filemanagement/Visao-geral|Visão geral do filemanagement]] · [[SeedGrid/Extensions/filemanagement/Configuracao|Configuração do filemanagement]]
+
+## Dependência
+
+```xml
+<dependency>
+    <groupId>br.com.seedgrid</groupId>
+    <artifactId>seedgrid-filemanagement</artifactId>
+    <version>2026.07.08</version>
+</dependency>
+<!-- Para backends de nuvem, declare também o SDK (optional na lib), ex.: software.amazon.awssdk:s3 -->
+```
+
+## Fachada com backend configurável (exemplo real)
+
+Fonte: `java/examples/seedgrid-filemanagement-example/src/main/java/br/com/seedgrid/filemanagementexample/service/DocumentStorageService.java`.
+
+```java
+@ApplicationScoped
+public class DocumentStorageService {
+
+    @Inject
+    FileStorageRegistry registry;
+
+    @ConfigProperty(name = "app.storage.type", defaultValue = "filesystem")
+    String storageType;
+
+    @ConfigProperty(name = "app.storage.filesystem.base-path")
+    String basePath;
+
+    public FileStorage storage() {
+        Map<String, String> config = Map.of("base-path", basePath);
+        return registry.get(storageType, config);
+    }
+
+    public StorageKey store(String filename, byte[] content, String prefix, String contentType)
+            throws StorageException {
+        StorageOptions options = StorageOptions.builder()
+                .prefix(prefix)
+                .contentType(contentType)
+                .build();
+        return storage().store(filename, content, options);
+    }
+
+    public StorageKey keyOf(String relativePath) {
+        return StorageKey.of(storageType, relativePath);
+    }
+
+    public byte[] retrieve(StorageKey key) throws StorageException { return storage().retrieve(key); }
+    public FileMetadata metadata(StorageKey key) throws StorageException { return storage().getMetadata(key); }
+    public void delete(StorageKey key) throws StorageException { storage().delete(key); }
+}
+```
+
+```properties
+# application.properties do exemplo (propriedades DO EXEMPLO, não da lib)
+app.storage.type=filesystem
+app.storage.filesystem.base-path=${STORAGE_BASE_PATH:${java.io.tmpdir}/seedgrid-filemanagement-example}
+```
+
+## S3 com credenciais opcionais
+
+Fonte: `README.md` (chaves conferidas em `S3StorageFactory`).
+
+```java
+Map<String, String> s3Config = new HashMap<>();
+s3Config.put("bucket", "<bucket>");
+s3Config.put("region", "us-east-1");
+s3Config.put("access-key", System.getenv("AWS_ACCESS_KEY_ID"));     // opcional
+s3Config.put("secret-key", System.getenv("AWS_SECRET_ACCESS_KEY")); // opcional
+
+FileStorage storage = registry.get("s3", s3Config);
+StorageKey key = storage.store("avatar.png", content, StorageOptions.builder()
+        .prefix("users/123/avatars")
+        .contentType("image/png")
+        .publicRead(true)          // aplica ACL public-read no S3
+        .build());
+String url = storage.generateSignedUrl(key, Duration.ofMinutes(15));
+```
+
+> `HashMap.put` com valor `null` (env ausente) é aceito; o factory ignora credenciais vazias/nulas e usa a cadeia padrão do AWS SDK.
+
+## Mapeando config própria da extension para o mapa (padrão do backup)
+
+Fonte: `java/seedgrid-quarkus-ext-backup/runtime/src/main/java/br/com/seedgrid/backup/services/ExportService.java` → `buildStorageConfig` (trecho).
+
+```java
+private Map<String, String> buildStorageConfig(String storageType) {
+    Map<String, String> config = new HashMap<>();
+
+    switch (storageType.toLowerCase()) {
+        case "filesystem":
+            config.put("base-path", backupConfig.filesystem().basePath());
+            break;
+
+        case "s3":
+            backupConfig.s3().bucket().ifPresent(v -> config.put("bucket", v));
+            backupConfig.s3().region().ifPresent(v -> config.put("region", v));
+            backupConfig.s3().accessKey().ifPresent(v -> config.put("access-key", v));
+            backupConfig.s3().secretKey().ifPresent(v -> config.put("secret-key", v));
+            backupConfig.s3().endpoint().ifPresent(v -> config.put("endpoint", v));
+            break;
+
+        // ... minio, azure-blob, google-drive, onedrive, gcs (mesmo padrão)
+
+        default:
+            throw new IllegalArgumentException("Unknown storage type: " + storageType);
+    }
+
+    return config;
+}
+
+// uso:
+FileStorage storage = fileStorageRegistry.get(storageType, buildStorageConfig(storageType));
+```
+
+## Backend customizado
+
+Fonte: `README.md` (contrato conferido em `FileStorageFactory`).
+
+```java
+@ApplicationScoped
+public class DropboxStorageFactory implements FileStorageFactory {
+    @Override public String typeIdentifier() { return "dropbox"; }
+
+    @Override
+    public FileStorage create(Map<String, String> config) {
+        String token = config.get("token");
+        if (token == null || token.isBlank()) {
+            throw new StorageConfigurationException("Dropbox token missing");
+        }
+        return new DropboxStorage(token); // sua implementação de FileStorage
+    }
+}
+```
+
+`DropboxStorage` é hipotética (do README); um segundo factory com o mesmo `typeIdentifier` derruba o boot com `DuplicateStorageException`.
+
+## StorageKey e URIs
+
+```java
+StorageKey k1 = StorageKey.filesystem("exports/2024/report.pdf");
+String uri = k1.toUri();                     // "filesystem://exports/2024/report.pdf"
+StorageKey k2 = StorageKey.fromUri(uri);     // bucket="exports", path="2024/report.pdf"
+```
+
+O `FilesystemStorage` resolve `basePath/bucket/path`, então o round-trip acima funciona no filesystem; no S3 a chave volta sem bucket — ver limitações em [[SeedGrid/Extensions/filemanagement/Visao-geral|Visão geral do filemanagement]].

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

@@ -0,0 +1,70 @@
+---
+tags: [seedgrid, extension, filemanagement, rust]
+fonte: rust/seedgrid-rust-crate-filemanagent
+branch: main
+commit: be738a2d1e
+analisado-em: 2026-10-14
+---
+
+# filemanagement — porte Rust (`seedgrid-rust-crate-filemanagent`)
+
+Porte da lib Java `seedgrid-quarkus-lib-filemanagement`. O nome do pacote Rust tem a grafia `filemanagent` (sem "m"); os crates consumidores o renomeiam para `seedgrid_filemanagement` via `package = ...` (ex.: `rust/seedgrid-rust-crate-backup/Cargo.toml`). Lado Java: [[SeedGrid/Extensions/filemanagement/Visao-geral|Visão geral do filemanagement (Java)]] · [[SeedGrid/Extensions/filemanagement/Configuracao|Configuração do filemanagement (Java)]]. Configuração Rust: [[SeedGrid/Extensions/filemanagement/Configuracao-Rust|Configuração Rust do filemanagement]].
+
+Abstração de armazenamento de arquivos com registro extensível de backends: `filesystem` (sempre presente) e, por feature Cargo, `s3`, `minio`, `azure-blob`, `gcs`, `google-drive`, `onedrive`. **Confirmado** (`src/lib.rs`, `src/factories.rs`).
+
+## Identificação
+| Item | Valor |
+|---|---|
+| Pacote Cargo | `seedgrid-rust-crate-filemanagent` (lib `seedgrid_rust_crate_filemanagent`, nome padrão; usado assim em `tests/minio_smoke.rs`) |
+| Versão | workspace `2026.10.14` |
+| Features | `s3`, `minio` (= `s3`), `azure`, `gcs`, `google-drive`, `onedrive`, `full`; padrão: nenhuma (só filesystem) |
+| Dependências SeedGrid | nenhuma |
+| Consumidores | backup (e o exemplo `seedgrid-filemanagement-example`) |
+| I/O | síncrono (S3/MinIO via `rust-s3` blocking; REST via `reqwest::blocking`) |
+
+## API pública
+| Símbolo | Papel | Fonte |
+|---|---|---|
+| trait `FileStorage` | `store`, `store_stream`, `store_reader` (extra do Rust), `retrieve`, `stream`, `delete`, `exists`, `get_metadata`, `generate_signed_url`, `can_handle`; aliases camelCase (`getMetadata`, `generateSignedUrl`, `canHandle`) | `src/storage.rs` |
+| trait `FileStorageFactory` | `type_identifier`, `create(&HashMap<String,String>)`, `is_available` | `src/storage.rs` |
+| `FileStorageRegistry::new(Vec<Box<dyn FileStorageFactory>>)` | `get(tipo, &config)` com cache por `(tipo, config)`, `get_for_key`, `has`, `get_available_types` | `src/registry.rs` |
+| `BuiltInStorageFactories::all()` | factories disponíveis conforme features | `src/factories.rs` |
+| `FilesystemStorageFactory`, `FilesystemStorage` | backend local | `src/factories.rs`, `src/storages.rs` |
+| `S3StorageFactory`, `MinioStorageFactory`, `S3CompatStorage` | feature `s3` | `src/providers/s3.rs` |
+| `AzureBlobStorageFactory`/`AzureBlobStorage`, `GoogleCloudStorageFactory`/`GcsStorage`, `GoogleDriveStorageFactory`/`GoogleDriveStorage`, `OneDriveStorageFactory`/`OneDriveStorage` | features respectivas | `src/providers/*.rs` |
+| `StorageKey` (`to_uri`, `from_uri`, construtores `filesystem`, `s3`…), `StorageOptions` (+ builder: `prefix`, `content_type`, `ttl`, `encrypt`, `public_read`, `metadata`), `FileMetadata` | domínio | `src/domains.rs` |
+| `StorageError` (`not_found`, `is_not_found`), `StorageConfigurationError`, `StorageNotFoundError`, `DuplicateStorageError`, `StorageInitializationError`, `RegistryError` | erros | `src/error.rs`, `src/registry.rs` |
+
+## Exemplo (de `rust/examples/seedgrid-filemanagement-example/src/main.rs`)
+```rust
+let mut config = HashMap::new();
+config.insert("endpoint".into(), env_or("MINIO_ENDPOINT", "http://localhost:9000"));
+config.insert("access-key".into(), env_or("MINIO_ACCESS_KEY", "<valor-dev>"));
+config.insert("secret-key".into(), env_or("MINIO_SECRET_KEY", "<valor-dev>"));
+config.insert("bucket".into(), env_or("MINIO_BUCKET", "sg-example"));
+
+let registry = FileStorageRegistry::new(vec![
+    Box::new(MinioStorageFactory) as Box<dyn FileStorageFactory>,
+])?;
+let storage = registry.get("minio", &config)?;
+let options = StorageOptions::builder().prefix("example").content_type("text/plain").build();
+let key = storage.store("hello.txt", &payload, &options)?;
+let fetched = storage.retrieve(&key)?;
+let meta = storage.get_metadata(&key)?;
+storage.delete(&key)?;
+```
+(Os valores default de credencial do exemplo foram substituídos por `<valor-dev>`.)
+
+## Testes
+- `tests/filesystem_storage_test.rs`, `registry_test.rs`, `storage_key_test.rs`, `storage_options_test.rs`.
+- `tests/minio_smoke.rs` (feature `s3`, `#[ignore]`, MinIO real).
+- E2E no exemplo: `rust/examples/seedgrid-filemanagement-example/tests/minio_e2e.rs`.
+- **Não executados.** Só S3/MinIO foram validados E2E; Azure/GCS/Drive/OneDrive compilam mas não foram testados contra a nuvem.
+
+## Limitações
+
+- `generate_signed_url` só funciona em S3/MinIO; nos backends REST devolve "not supported".
+- Não há parser manual de `from_uri`, aliases camelCase nem `store_reader`.
+
+## Enums
+Sem enums de domínio (o backend é escolhido pelo texto `type_identifier`: `filesystem`, `s3`, `minio`, `azure-blob`, `gcs`, `google-drive`, `onedrive`). Enum público de erro: `RegistryError` (`src/registry.rs`) com `NotFound(StorageNotFoundError)` (tipo não registrado; a mensagem lista os tipos disponíveis) e `Configuration(StorageConfigurationError)` (falha em `factory.create`). Ver [[SeedGrid/Extensions/filemanagement/Configuracao-Rust|Configuração Rust]] para os tipos e chaves.

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

@@ -0,0 +1,88 @@
+---
+tags: [seedgrid, library, filemanagement]
+fonte: java/seedgrid-quarkus-lib-filemanagement
+branch: main
+commit: 35c89c7cf7
+analisado-em: 2026-10-14
+---
+
+# SeedGrid File Management — Visão geral
+
+> [!info] Library, não extension Quarkus
+> `seedgrid-quarkus-lib-filemanagement` é uma **library Java** (jar único com índice Jandex), **não** uma extension Quarkus com `runtime`/`deployment`. Não há `@ConfigRoot`/`@ConfigMapping`: a lib **não lê MicroProfile Config** — recebe a configuração de cada storage num `Map<String, String>` passado pelo chamador. Documentada nesta estrutura por uniformidade.
+
+Configuração: [[SeedGrid/Extensions/filemanagement/Configuracao|Configuração do filemanagement]] · Exemplos: [[SeedGrid/Extensions/filemanagement/Exemplos|Exemplos do filemanagement]] · [[SeedGrid/Extensions/filemanagement/Rust|Porte Rust]] (crate `seedgrid-rust-crate-filemanagent`)
+
+## Objetivo
+
+Uma API única de armazenamento de arquivos (`FileStorage`) com backends plugáveis — filesystem, AWS S3, MinIO, Azure Blob, Google Cloud Storage, Google Drive e OneDrive — criados **sob demanda** por factories e cacheados pelo `FileStorageRegistry`. A aplicação decide a organização de paths (via `prefix`). **Confirmado** (`pom.xml` description, `README.md`, código).
+
+## Coordenadas e dependências
+
+| Item | Valor |
+|---|---|
+| groupId:artifactId | `br.com.seedgrid:seedgrid-filemanagement` |
+| Versão (pom) | `2026.07.08` |
+| Parent | `br.com.seedgrid:seedgrid-parent:2026.07.02` |
+| Obrigatórias | `quarkus-arc`, `quarkus-hibernate-validator` |
+| **Optional** (o host precisa declarar para usar o backend) | AWS `s3` 2.21.42; `azure-storage-blob` 12.25.1; `google-api-client` 2.2.0, `google-api-services-drive` v3-rev197-1.25.0, `google-auth-library-oauth2-http` 1.20.0; `google-cloud-storage` 2.29.1; `minio` 8.5.9; `microsoft-graph` 5.80.0 + `azure-identity` 1.11.1; também `quarkus-hibernate-orm`, `quarkus-jdbc-postgresql`, `quarkus-flyway` |
+| Dependências SeedGrid | nenhuma (desde 2026.07.08 não depende mais de `seedgrid-commons`, segundo comentário do exemplo) |
+
+Fonte: `java/seedgrid-quarkus-lib-filemanagement/pom.xml`. **Confirmado.** Que o host precise declarar o SDK do backend escolhido é **Inferência** (escopo `optional` não é transitivo).
+
+## Arquitetura
+
+```mermaid
+flowchart LR
+    APP["Host / extension<br/>(monta Map de config)"] -->|"registry.get(type, config)"| REG["FileStorageRegistry<br/>@ApplicationScoped"]
+    REG -->|"descobre no construtor<br/>Instance&lt;FileStorageFactory&gt;"| F["FileStorageFactory<br/>(1 por typeIdentifier)"]
+    F -->|"create(config) — valida chaves"| S["FileStorage<br/>(@Vetoed, não é bean)"]
+    REG -->|"cache por (type + config)"| S
+    S --> B[("filesystem · s3 · minio · azure-blob · gcs · google-drive · onedrive")]
+```
+
+- **Descoberta** (**Confirmado**, `FileStorageRegistry`): o construtor itera `Instance<FileStorageFactory>`; dois factories com o mesmo `typeIdentifier()` → `DuplicateStorageException` (falha no boot); nenhum factory → apenas WARN.
+- **Lazy + cache** (**Confirmado**): `get(type, config)` cria via `factory.create(config)` na primeira chamada e cacheia por `record CacheKey(type, cópia imutável do config)` — igualdade por conteúdo do mapa; configs diferentes do mesmo tipo geram instâncias distintas. `clearCache()` força recriação. Tipo sem factory → `StorageNotFoundException` (checked, propagada via `@SneakyThrows`).
+- **Validação** só no primeiro uso: factories lançam `StorageConfigurationException` (unchecked); construtores de storage podem lançar `StorageInitializationException` (ex.: GCS sem credenciais ou bucket inexistente).
+- As classes de storage são `@Vetoed` (não são beans CDI); os factories são `@ApplicationScoped`. **Confirmado** (todas as classes em `storages/` têm `@Vetoed`; criação sempre via `new` nos factories).
+
+### Backends embutidos
+
+| `typeIdentifier` | Factory | Implementação | `generateSignedUrl` |
+|---|---|---|---|
+| `filesystem` | `FilesystemStorageFactory` | `FilesystemStorage` | não suportado (default lança `UnsupportedOperationException`) |
+| `s3` | `S3StorageFactory` | classe interna `S3StorageImpl` (a classe pública `storages/S3Storage` é `@Vetoed` e **não é usada** pelo factory) | presigned GET |
+| `minio` | `MinIOStorageFactory` | `MinIOStorage` | presigned (expiry em segundos) |
+| `azure-blob` | `AzureBlobStorageFactory` | `AzureBlobStorage` (cria o container se não existir) | SAS |
+| `gcs` | `GoogleCloudStorageFactory` | `GoogleCloudStorage` (verifica se o bucket existe no init) | signed URL (TTL em minutos) |
+| `google-drive` | `GoogleDriveStorageFactory` | `GoogleDriveStorage` (escopo `drive.file`) | **cria permissão pública `anyone/reader`** e devolve link; o TTL é ignorado (link precisa ser revogado manualmente) |
+| `onedrive` | `OneDriveStorageFactory` | `OneDriveStorage` (Graph `me().drive()`, client credentials) | devolve `webUrl` do item; TTL ignorado; loga WARN |
+
+Fonte: `factories/*.java`, `storages/*.java`. **Confirmado.**
+
+## APIs públicas e pontos de integração
+
+| Tipo | Símbolo | Observação |
+|---|---|---|
+| SPI | `spi.FileStorage` | `typeIdentifier()`, `store(filename, byte[], StorageOptions)`, `store(filename, InputStream, StorageOptions)` (default lê tudo em memória), `retrieve`, `stream`, `delete`, `exists`, `getMetadata`, `generateSignedUrl(key, ttl)` (default unsupported), `canHandle(key)` |
+| SPI | `spi.FileStorageFactory` | `typeIdentifier()`, `create(Map<String,String>)` |
+| Bean | `services.FileStorageRegistry` | `get(type, config)`, `get(StorageKey, config)`, `has(type)`, `getAvailableTypes()`, `getCreatedStorages()`, `clearCache()` |
+| Domínio | `domains.StorageKey` | `type`, `bucket`, `path`; `toUri()`/`fromUri()`, fábricas `filesystem`, `s3`, `azureBlob`, `minio`, `of(...)` |
+| Domínio | `domains.StorageOptions` | `prefix`, `contentType`, `publicRead` (false; só tem efeito no S3), `metadata` (gravado por Azure, GCS, Google Drive e MinIO); `defaults()`, `withPrefix()`, `fullPath()` |
+| Domínio | `domains.FileMetadata` | `storageKey`, `filename`, `sizeBytes`, `contentType`, `createdAt`, `lastModifiedAt`, `metadata` (preenchidos conforme o backend) |
+| Exceções | `StorageException` (checked), `StorageNotFoundException` (checked, estende `StorageException`), `StorageConfigurationException`, `StorageInitializationException`, `DuplicateStorageException` | — |
+
+Extensão: o host cria um `@ApplicationScoped FileStorageFactory` com `typeIdentifier` novo; o registry o descobre. Sem endpoints REST, eventos ou migrations (apesar das deps optional de ORM/Flyway, não há entidades nem SQL no `src/main`).
+
+**Consumidores no monorepo** (**Confirmado** por busca): `seedgrid-quarkus-ext-backup` (`ExportService#buildStorageConfig`, mapeia `seedgrid.backup.*` → chaves do mapa) — ver [[SeedGrid/Extensions/backup/Visao-geral|Visão geral do backup]]; `seedgrid-quarkus-ext-security` (`UserAvatarService#buildStorageConfig`) — ver [[SeedGrid/Extensions/security/Visao-geral|Visão geral do security]]; dependência declarada em `seedgrid-quarkus-ext-login-tenancy`.
+
+## Testes existentes (não executados)
+
+`src/test/java/...`: `StorageKeyTest`, `StorageOptionsTest`, `FileMetadataTest`, `FileStorageRegistryTest` (Mockito), `FileStorageRegistryFilesystemTest` (cache por config), `FilesystemStorageTest`, `StorageExceptionTest`, `FileStorageIntegrationTest` (`@QuarkusTest`, só `filesystem`). ~60 `@Test` por grep. Nenhum teste de backend de nuvem. **Não executados.**
+
+## Limitações
+
+- `publicRead` só tem efeito no S3 (ACL `public-read`). **Confirmado.**
+- S3 (`S3StorageImpl`) devolve `StorageKey.of("s3", key)` **sem bucket**; `toUri()` vira `s3://<prefixo>/<arquivo>` e um `fromUri()` posterior interpretaria o primeiro segmento como bucket, mudando o `path`. Risco de round-trip ao persistir a URI — **Inferência** (não testado).
+- `FilesystemStorage` monta caminhos com `Paths.get(basePath, ...)` sem normalizar nem barrar `..` — risco de path traversal se `filename`/`prefix` vierem do usuário. **Inferência.**
+- `GoogleDriveStorage#generateSignedUrl` torna o arquivo público permanentemente.