> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devmob.app.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Storage

> Upload de arquivos com contextos por projeto, limites de tamanho e confirmação em duas fases.

O **Storage** gerencia o upload de arquivos, como avatares de usuário e logos de organização. O cliente solicita uma autorização de upload, envia o arquivo e depois salva o recurso que usa esse arquivo.

## Contextos e MIME

| Contexto            | Prefixo lógico      | Tamanho máximo |
| ------------------- | ------------------- | -------------- |
| `USER_AVATAR`       | `user-avatar`       | 5 MB           |
| `ORGANIZATION_LOGO` | `organization-logo` | 2 MB           |

Tipos MIME permitidos: `image/png`, `image/jpeg`, `image/webp`.

### Contextos por projeto

Cada projeto só pode assinar uploads dos contextos permitidos. Um contexto não permitido resulta em `403 Forbidden`.

| Projeto    | Contextos permitidos               |
| ---------- | ---------------------------------- |
| `customer` | `USER_AVATAR`                      |
| `driver`   | `USER_AVATAR`                      |
| `ops`      | `USER_AVATAR`, `ORGANIZATION_LOGO` |
| `bko`      | `USER_AVATAR`, `ORGANIZATION_LOGO` |

## Fluxo em duas fases

```mermaid theme={null}
sequenceDiagram
    participant C as Cliente
    participant O as DEVMOB
    participant ST as Storage

    C->>O: Solicita autorização de upload
    Note over O: Contexto permitido para o projeto
    O-->>C: Retorna dados de upload

    C->>ST: Envia arquivo
    ST-->>C: Upload concluído

    C->>O: Salva perfil/organização com a chave do arquivo
    O->>ST: Confirma arquivo temporário
    O->>ST: Vincula arquivo ao recurso
    O-->>C: Recurso atualizado
```

### Fase 1 — Autorizar upload

O DEVMOB valida o contexto para o projeto, gera uma autorização temporária e retorna os dados necessários para o upload.

* A resposta inclui a chave autorizada, `cdnUrl`, dados de upload e `expiresIn`.
* O limite de tamanho é aplicado conforme o contexto.

### Fase 2 — Confirmar uso

A confirmação ocorre quando o usuário salva o recurso que usa o arquivo, como avatar ou logo.

* Valida que a chave temporária pertence ao usuário.
* Confere a existência do arquivo temporário.
* Vincula o arquivo ao recurso final, como avatar de usuário ou logo de organização.

## Capacidade

Apenas a autorização de upload é exposta como capacidade direta; a confirmação ocorre dentro da atualização de perfil/organização.

| Capacidade       | Auth        | Descrição                                      |
| ---------------- | ----------- | ---------------------------------------------- |
| Autorizar upload | Autenticado | Retorna os dados de upload + URL final no CDN. |

O projeto é `customer`, `ops`, `driver` ou `bko`. O usuário do escopo vem do perfil autenticado.

<Info>
  O arquivo é enviado pelo cliente usando os dados de upload retornados. O DEVMOB controla a autorização, o vínculo com o usuário e a localização final.
</Info>