file

O submódulo File cuida de todo o ciclo de vida de ativos binários: upload, persistência de metadados, geração de URLs seguras e entrega com acesso controlado. Os arquivos são recebidos via multipart/form-data, armazenados no backend de armazenamento configurado (disco local ou um provedor de object storage em nuvem), e um registro de metadados é gravado contendo o nome de arquivo original, o MIME type, o tamanho do arquivo, o caminho de armazenamento e um identificador único. O parâmetro opcional destination permite que os chamadores especifiquem um subcaminho para fins de organização.

Os arquivos nunca são servidos por caminhos de armazenamento brutos. Em vez disso, um administrador gera um token assinado com prazo limitado via PUT /file/open/:id para visualização inline ou PUT /file/download/:id para download como anexo. O token codifica o ID do arquivo, um timestamp de expiração e um segredo do lado do servidor. Os endpoints públicos decodificam e validam o token antes de transmitir o arquivo, evitando a enumeração de caminhos de armazenamento e aplicando a expiração por requisição sem manter uma sessão.

O submódulo File é usado como uma camada de infraestrutura compartilhada por vários outros submódulos do Core. O submódulo User armazena avatares como registros de File. O submódulo Dashboard armazena as capturas de tela de pré-visualização dos widget components pelo mesmo pipeline. O fluxo de importação do submódulo Setting aceita arquivos JSON via upload multipart. O submódulo AI aceita um file_id para incluir o conteúdo de documentos como contexto do LLM. Essa centralização significa que todos os ativos binários passam por um único pipeline de armazenamento e controle de acesso consistente, independentemente de qual funcionalidade faz o upload.

A exclusão via DELETE /file remove os registros de arquivo e os arquivos armazenados subjacentes. Os chamadores são responsáveis por garantir que nenhum outro registro mantenha referências aos IDs de arquivo excluídos antes de chamar esse endpoint, pois o HedHog não faz cascade de exclusões automaticamente entre referências de chave estrangeira.