Object Storage — metadados e arquivos¶

Owner: Object Storage. object_storage reside no banco do tenant; global_file_registry usa object-storage.global-database, default gateway-globals. Binários ficam no provider MINIO ou GCS, e não no documento Mongo. Bucket default gateway-assets, sobrescrito por configuração.

Modelos visuais¶

Registro global e metadados¶

Registro global seleciona o banco do owner. O binário fica no provedor, fora do Mongo.

Registro global e metadados; visão simplificada em tema escuro.

Explorar diagramas detalhados com zoom

Legenda e convenções dos modelos. Os dicionários e evidências desta página permanecem a referência dos campos.

%%{init: {"theme":"base","themeVariables":{"fontFamily":"Arial, sans-serif","fontSize":"16px","lineColor":"#64748b","primaryTextColor":"#172b4d"},"flowchart":{"htmlLabels":true,"useMaxWidth":true,"nodeSpacing":28,"rankSpacing":38,"padding":14,"curve":"linear","subGraphTitleMargin":{"top":12,"bottom":16}},"sequence":{"useMaxWidth":true,"actorMargin":28,"width":145,"height":45,"diagramMarginX":32,"diagramMarginY":12,"messageMargin":24,"wrap":true,"mirrorActors":false},"themeCSS":".edgeLabel, .edgeLabel p {background-color:var(--diagram-surface)!important;color:var(--diagram-text)!important}\n.cluster rect {fill:var(--diagram-group)!important;stroke:var(--diagram-line)!important}\n.cluster-label span, .cluster-label text {color:var(--diagram-text)!important;fill:var(--diagram-text)!important}\n.flowchart-link, .actor-line {stroke:var(--diagram-line)!important}\nmarker path {fill:var(--diagram-line)!important;stroke:var(--diagram-line)!important}\n.actor {fill:var(--diagram-domain)!important;stroke:var(--diagram-domain-border)!important}\ntext.actor, .messageText, .loopText, .labelText {fill:var(--diagram-text)!important}\n.messageLine0, .messageLine1, .loopLine {stroke:var(--diagram-line)!important}\n.labelBox {fill:var(--diagram-surface)!important;stroke:var(--diagram-line)!important}\n.note {fill:var(--diagram-async)!important;stroke:var(--diagram-async-border)!important}\n.noteText {fill:var(--diagram-text)!important}\n.nodeLabel, .nodeLabel p, .nodeLabel span {color:var(--diagram-text)!important}\n.node .nodeLabel, .node .nodeLabel p {font-size:17px;font-weight:600;line-height:1.4;text-align:center}\n.nodeLabel small {display:inline-block;margin-top:4px;font-size:15px;font-weight:400;line-height:1.4;color:var(--diagram-description)!important}\ntext.actor, text.actor tspan {font-size:17px;font-weight:600}\n.node.entry rect, .node.entry polygon, .node.entry path, .node.entry circle {fill:var(--diagram-entry)!important;stroke:var(--diagram-entry-border)!important}\n.node.domain rect, .node.domain polygon, .node.domain path, .node.domain circle {fill:var(--diagram-domain)!important;stroke:var(--diagram-domain-border)!important}\n.node.security rect, .node.security polygon, .node.security path, .node.security circle {fill:var(--diagram-security)!important;stroke:var(--diagram-security-border)!important}\n.node.store rect, .node.store polygon, .node.store path, .node.store circle {fill:var(--diagram-store)!important;stroke:var(--diagram-store-border)!important}\n.node.async rect, .node.async polygon, .node.async path, .node.async circle {fill:var(--diagram-async)!important;stroke:var(--diagram-async-border)!important}\n.node.external rect, .node.external polygon, .node.external path, .node.external circle {fill:var(--diagram-external)!important;stroke:var(--diagram-external-border)!important}\n text.actor tspan, .loopText tspan, .labelText tspan, .messageText tspan, .noteText tspan {fill:var(--diagram-text)!important}\n\n"}}%%
flowchart TB
    registry["global_file_registry<br/><small>Registro global de publicação</small>"]:::store
    metadata["object_storage<br/><small>Metadados no banco do owner</small>"]:::store
    blob(["MinIO / GCS<br/><small>Objeto binário</small>"]):::external
    registry -->|fileId / ownerTenantId| metadata
    metadata -->|provider / bucket / objectKey| blob
    classDef store stroke-width:1.5px;
    classDef external stroke-width:1.5px;

Collection	Identidade e ciclo de vida
`object_storage`	`_id` string gerada para o arquivo; tenant, propósito, provider/localização, tamanho, MIME, extensão, checksum e dimensões. Upload inicia `TEMPORARY`; vinculação usa `LINKED` e `entityType/entityId`. Enum também declara `DELETED`. Remoção/limpeza coordenam provider e metadados
`global_file_registry`	`fileId`, `ownerTenantId`, `publishedAt`; upsert condicionado por arquivo e owner; unpublish remove por ambos. Não declara campo `_id` no modelo, embora Mongo tenha identidade própria

Propósitos: GATEWAY_TEMPLATE_ICON, API_DEFINITION_DOCUMENT. Políticas validam tamanho/tipo/dimensões e determinam expiração do temporário. Campos de imagem não se tornam obrigatórios para todo arquivo. Publicar um ícone não copia seu blob; a leitura pública resolve o owner no registro global e consulta os metadados desse tenant.

Collection	Índices declarados
`object_storage`	`{status:1,expiresAt:1}`; `{entityType:1,entityId:1}`; `{purpose:1,createdAt:-1}`
`global_file_registry`	`{fileId:1}`, unique

expiresAt não possui índice TTL. TemporaryFileCleanupJob percorre tenants, seleciona temporários vencidos em lotes e remove o objeto e seus metadados. A expiração depende desse processamento; não é apagamento automático Mongo.

Fontes: metadados, registro global, leitura cross-tenant, limpeza, políticas, aplicação, configuração.

O teste GlobalFileRegistryMongoTest cobre publicação concorrente com unicidade por fileId, preservação do primeiro publishedAt e resolução do metadado original pelo owner sem copiá-lo. Essas invariantes complementam os modelos abaixo.

Dicionário de documentos¶

Os nomes BSON abaixo respeitam @BsonId/@BsonProperty. A nulabilidade descreve o tipo Java, não uma validação de schema Mongo. Valores iniciais Java precedem os construtores e serviços; os defaults de criação e invariantes estão descritos acima. Referências anuláveis não significam que a API aceite omiti-las em todas as operações. Campos de mapas/documentos livres não possuem schema fechado no modelo.

Propriedades calculadas expostas por getters públicos são identificadas separadamente: fazem parte da superfície do codec POJO, não do estado independente da entidade. @BsonIgnore é respeitado. A representação UUID depende da configuração do codec; os tipos de transporte JSON não substituem os tipos BSON.

Collection / documento raiz	Modelo
`object_storage`	FileMetadata
`global_file_registry`	GlobalFileRegistration

object_storage — FileMetadata¶

FileMetadata.

Campo BSON	Tipo Java / estrutura	Representação	Nulabilidade / valor inicial
`_id`	String	string	Identificador BSON; tipo e geração conforme o ciclo de criação
`tenantId`	String	string	Referência anulável; inicial Java: `null`
`purpose`	FilePurpose	enum string	Referência anulável; inicial Java: `null`
`status`	FileStatus	enum string	Referência anulável; inicial Java: `null`
`provider`	StorageProviderType	enum string	Referência anulável; inicial Java: `null`
`bucket`	String	string	Referência anulável; inicial Java: `null`
`objectKey`	String	string	Referência anulável; inicial Java: `null`
`originalFileName`	String	string	Referência anulável; inicial Java: `null`
`contentType`	String	string	Referência anulável; inicial Java: `null`
`extension`	String	string	Referência anulável; inicial Java: `null`
`size`	long	int64	Primitivo não nulo; inicial Java: `0`
`width`	Integer	int32	Referência anulável; inicial Java: `null`
`height`	Integer	int32	Referência anulável; inicial Java: `null`
`checksum`	String	string	Referência anulável; inicial Java: `null`
`createdBy`	String	string	Referência anulável; inicial Java: `null`
`createdAt`	Instant	data/hora	Referência anulável; inicial Java: `null`
`expiresAt`	Instant	data/hora	Referência anulável; inicial Java: `null`
`entityType`	String	string	Referência anulável; inicial Java: `null`
`entityId`	String	string	Referência anulável; inicial Java: `null`

Exemplo de estrutura¶

Fragmento derivado dos campos do modelo vinculado acima, com valores substituídos por identificadores/textos sintéticos e data fixa. Não é um payload de criação nem um documento completo. ObjectId/data usam notação Extended JSON; nenhum dado de ambiente foi copiado.

{
  "_id": "00000000-0000-4000-8000-000000000001",
  "tenantId": "00000000-0000-4000-8000-000000000001",
  "purpose": "GATEWAY_TEMPLATE_ICON",
  "status": "TEMPORARY"
}

global_file_registry — GlobalFileRegistration¶

GlobalFileRegistration.

Campo BSON	Tipo Java / estrutura	Representação	Nulabilidade / valor inicial
`fileId`	String	string	Referência anulável; inicial Java: `null`
`ownerTenantId`	String	string	Referência anulável; inicial Java: `null`
`publishedAt`	Instant	data/hora	Referência anulável; inicial Java: `null`

Exemplo de estrutura¶

Fragmento derivado dos campos do modelo vinculado acima, com valores substituídos por identificadores/textos sintéticos e data fixa. Não é um payload de criação nem um documento completo. ObjectId/data usam notação Extended JSON; nenhum dado de ambiente foi copiado.

{
  "fileId": "00000000-0000-4000-8000-000000000001",
  "ownerTenantId": "00000000-0000-4000-8000-000000000001",
  "publishedAt": {
    "$date": "2026-10-13T00:00:00Z"
  }
}

Estruturas embutidas, herança e enums¶

Estes tipos não criam collections próprias. Quando uma entidade raiz aparece dentro de um snapshot, a mesma estrutura é embutida naquele caminho. Tipos de elementos de arrays e valores de mapas estão vinculados nas tabelas.

FilePurpose¶

model/FilePurpose.java.

Valores: GATEWAY_TEMPLATE_ICON, API_DEFINITION_DOCUMENT.

FileStatus¶

model/FileStatus.java.

Valores: TEMPORARY, LINKED, DELETED.

StorageProviderType¶

model/StorageProviderType.java.

Valores: GCS, MINIO.