Criar modelo polimórfico de arquivos

[Junior-Shyko]

📎 Implementar sistema de upload de arquivos polimórfico

Descrição

Implementar a estrutura completa de upload e gerenciamento de arquivos do e-Fomento.
O sistema utilizará uma tabela centralizada files com relacionamento polimórfico,
servindo múltiplas entidades através do padrão object_type + object_id com morph map do Eloquent.

---

Contexto técnico

A tabela files funcionará como repositório único de arquivos para todas as entidades
do sistema. Cada arquivo pertence a uma entidade específica, é armazenado em uma estrutura
de pastas organizada por tipo e ID (project/998877/contrato.pdf) e possui controle de
visibilidade pública/privada.

---

Entidades contempladas

• Notice
• Project
• Opening
• Formalization
• Budget
• Payment
• Monitoring
• LegalAnalysis

---

Critérios de aceite

• Migration da tabela files criada com todos os campos, índices e soft delete
• Model File com soft delete, acessor de URL, scopes e relacionamento polimórfico
• Trait HasFiles criada e aplicada em todas as entidades listadas
• FileService implementado com métodos upload, delete e buildPath
• FileRequest com validação dos campos de upload
• FileController com actions store e destroy
• FileResource expondo os campos públicos do arquivo
• Morph map registrado no AppServiceProvider
• Rotas registradas no api.php
• Disco de storage configurável via .env com variável FILE_DISK

---

Regras de negócio

• Arquivos private = true não expõem URL pública
• Path gerado automaticamente no padrão {object_type}/{object_id}/{slug}.{ext}
• MD5 calculado automaticamente no upload para controle de integridade
• Tamanho máximo por arquivo: 20MB
• Sem suporte a variantes de tamanho ou arquivos derivados (sem parent_id)

---

Rotas

Método	Endpoint	Ação
POST	/files/{objectType}/{objectId}	Upload de arquivo
DELETE	/files/{fileId}	Remoção de arquivo

---

Artefatos a serem criados

Arquivo	Tipo
database/migrations/xxxx_create_files_table.php	Migration
app/Models/File.php	Model
app/Traits/HasFiles.php	Trait
app/Services/FileService.php	Service
app/Http/Requests/FileRequest.php	Request
app/Http/Controllers/FileController.php	Controller
app/Http/Resources/FileResource.php	Resource

---

Stack

• Laravel 12 / PHP 8.3
• Eloquent ORM — Polymorphic Relationships
• Storage nativo do Laravel (sem pacotes externos)

---

Referências

• Discussão de arquitetura da tabela files: (link da conversa ou PR de decisão)
• Laravel Docs — Polymorphic Relationships
• Laravel Docs — File Storage