Araponga Logo

Wiki Araponga

Documentação Completa

Fase 8: Infraestrutura de Mídia e Armazenamento

Duração: 3 semanas (15 dias úteis)
Prioridade: 🔴 CRÍTICA (Bloqueante para outras fases)
Bloqueia: Fases 9, 10, 11 (todas dependem de mídia)
Estimativa Total: 120 horas
Status: ✅ Implementado (2025-01-16)
Última Atualização: 2025-01-16

🎯 Objetivo

Criar infraestrutura completa de armazenamento e gerenciamento de mídias (imagens, vídeos) que será base para:

  • Avatar/Foto de perfil
  • Imagens em posts
  • Imagens em eventos
  • Imagens em anúncios (marketplace)
  • Imagens em mensagens

Valores Mantidos: Mídias servem para documentar território e fortalecer comunidade, não para capturar atenção.

📋 Contexto e Requisitos

Estado Atual

  • ✅ TerritoryAsset existe (recursos territoriais não-vendáveis)
  • ✅ Sistema de mídia (MediaAsset, MediaAttachment) implementado
  • ✅ Armazenamento de arquivos implementado (local)
  • ✅ Upload/download de imagens implementado
  • ✅ Validação e processamento de imagens implementado

Requisitos Funcionais

  • ✅ Upload de imagens (JPEG, PNG, WebP)
  • ✅ Upload de vídeos (MP4, opcional para Fase 11)
  • ✅ Armazenamento seguro (local ou cloud)
  • ✅ Validação de tamanho e formato
  • ✅ Redimensionamento/otimização de imagens
  • ✅ Download de mídias
  • ✅ Associação de mídias a entidades (User, Post, Event, StoreItem, ChatMessage)
  • ✅ Soft delete de mídias

Requisitos Não-Funcionais

  • ✅ Segurança: Validação de tipo MIME, tamanho máximo
  • ✅ Performance: Otimização automática de imagens
  • ✅ Escalabilidade: Preparado para cloud storage (S3, Azure Blob)
  • ✅ Privacidade: Controle de acesso por território/usuário

📋 Tarefas Detalhadas

Semana 29: Modelo de Domínio e Armazenamento Base

29.1 Modelo de Domínio de Mídia

Estimativa: 8 horas (1 dia)
Status: ✅ Implementado (2025-01-16)
Última Atualização: 2025-01-16

Tarefas:

  • Criar MediaAsset (entidade de domínio)
    • Id, UploadedByUserId, MediaType (Image, Video, Audio, Document)
    • MimeType, StorageKey, SizeBytes
    • WidthPx, HeightPx (para imagens)
    • Checksum (integridade)
    • CreatedAtUtc
  • Criar MediaAttachment (associação de mídia a entidade)
    • MediaAssetId, OwnerType (User, Post, Event, StoreItem, ChatMessage)
    • OwnerId, DisplayOrder (ordem em múltiplas mídias)
    • CreatedAtUtc
  • Criar enums: MediaType, MediaOwnerType
  • Validações de domínio (tamanho máximo, tipos permitidos)
  • Testes unitários do modelo

Arquivos Criados:

  • ✅ backend/Arah.Domain/Media/MediaAsset.cs
  • ✅ backend/Arah.Domain/Media/MediaAttachment.cs
  • ✅ backend/Arah.Domain/Media/MediaType.cs
  • ✅ backend/Arah.Domain/Media/MediaOwnerType.cs
  • ✅ backend/Arah.Tests/Domain/Media/MediaAssetTests.cs
  • ✅ backend/Arah.Tests/Domain/Media/MediaAttachmentTests.cs

Critérios de Sucesso:

  • ✅ Modelo de domínio criado
  • ✅ Validações implementadas
  • ✅ Testes unitários passando (>90% cobertura)

29.2 Interface de Armazenamento

Estimativa: 8 horas (1 dia)
Status: ✅ Implementado (2025-01-16)
Última Atualização: 2025-01-16

Tarefas:

  • Criar IMediaStorageService (interface de armazenamento)
    • UploadAsync(Stream, string mimeType, string fileName)
    • DownloadAsync(string storageKey)
    • DeleteAsync(string storageKey)
    • GetUrlAsync(string storageKey) (URL pública ou signed URL)
    • ExistsAsync(string storageKey)
  • Criar IMediaProcessingService (processamento de imagens)
    • ResizeImageAsync(Stream, int maxWidth, int maxHeight)
    • OptimizeImageAsync(Stream) (compressão)
    • GetImageDimensionsAsync(Stream) (obter dimensões)
    • ValidateImageAsync(Stream, string mimeType) (validação de formato)
  • Criar IMediaValidator (validação de mídias)
    • ValidateAsync(Stream, string mimeType, long sizeBytes)
    • Tipos permitidos, tamanhos máximos

Arquivos a Criar:

  • backend/Arah.Application/Interfaces/Media/IMediaStorageService.cs
  • backend/Arah.Application/Interfaces/Media/IMediaProcessingService.cs
  • backend/Arah.Application/Interfaces/Media/IMediaValidator.cs

Critérios de Sucesso:

  • ✅ Interfaces criadas
  • ✅ Documentação XML completa
  • ✅ Contratos bem definidos

29.3 Implementação de Armazenamento Local

Estimativa: 16 horas (2 dias)
Status: ✅ Implementado (2025-01-16)
Última Atualização: 2025-01-16

Tarefas:

  • Criar LocalMediaStorageService (armazenamento em disco)
    • Configuração de diretório base (wwwroot/media ou configurável)
    • Estrutura de pastas por tipo/ano/mês
    • Geração de nomes únicos (GUID + extensão)
    • Upload de arquivos
    • Download de arquivos
    • Exclusão de arquivos
    • Proteção contra path traversal
  • Criar LocalMediaProcessingService (processamento local)
    • Usar SixLabors.ImageSharp para redimensionamento
    • Otimização de imagens (compressão)
    • Validação de formato
    • Obtenção de dimensões de imagem
  • Criar MediaValidator (validação)
    • Validação de tipo MIME
    • Validação de tamanho (máx. 10MB para imagens, 50MB para vídeos)
    • Validação de dimensões (máx. 4000x4000px para imagens)
  • Configuração em appsettings.json
    • MediaStorage:Provider (Local, S3, AzureBlob)
    • MediaStorage:LocalPath
    • MediaStorage:MaxImageSizeBytes
    • MediaStorage:MaxVideoSizeBytes

Arquivos a Criar:

  • backend/Arah.Infrastructure/Media/LocalMediaStorageService.cs
  • backend/Arah.Infrastructure/Media/LocalMediaProcessingService.cs
  • backend/Arah.Infrastructure/Media/MediaValidator.cs
  • backend/Arah.Infrastructure/Media/MediaStorageOptions.cs

Arquivos a Modificar:

  • backend/Arah.Api/appsettings.json
  • backend/Arah.Api/Extensions/ServiceCollectionExtensions.cs (registro de serviços)

Dependências NuGet:

  • SixLabors.ImageSharp (processamento de imagens)

Critérios de Sucesso:

  • ✅ Armazenamento local funcionando
  • ✅ Upload/download de imagens funcionando
  • ✅ Redimensionamento automático funcionando
  • ✅ Validações funcionando
  • ✅ Testes de integração passando

Semana 30: Repositórios e Serviços de Aplicação

30.1 Repositórios de Mídia

Estimativa: 12 horas (1.5 dias)
Status: ✅ Implementado (2025-01-16)

Tarefas:

  • Criar IMediaAssetRepository
    • AddAsync(MediaAsset)
    • GetByIdAsync(Guid id)
    • ListByUserIdAsync(Guid userId)
    • ListByIdsAsync(IReadOnlyCollection<Guid> ids)
    • UpdateAsync(MediaAsset) (para soft delete)
    • ListDeletedAsync() (soft delete)
  • Criar IMediaAttachmentRepository
    • AddAsync(MediaAttachment)
    • ListByOwnerAsync(MediaOwnerType, Guid ownerId)
    • ListByMediaAssetIdAsync(Guid mediaAssetId)
    • ListByOwnersAsync(MediaOwnerType, IReadOnlyCollection<Guid> ownerIds)
    • UpdateAsync(MediaAttachment)
    • DeleteAsync(Guid id)
    • DeleteByOwnerAsync(MediaOwnerType, Guid ownerId)
    • DeleteByMediaAssetIdAsync(Guid mediaAssetId)
  • Implementar PostgresMediaAssetRepository
  • Implementar PostgresMediaAttachmentRepository
  • Implementar InMemoryMediaAssetRepository
  • Implementar InMemoryMediaAttachmentRepository
  • Criar migrations do banco de dados
    • Tabela media_assets
    • Tabela media_attachments
    • Índices apropriados

Arquivos a Criar:

  • backend/Arah.Application/Interfaces/Media/IMediaAssetRepository.cs
  • backend/Arah.Application/Interfaces/Media/IMediaAttachmentRepository.cs
  • backend/Arah.Infrastructure/Postgres/PostgresMediaAssetRepository.cs
  • backend/Arah.Infrastructure/Postgres/PostgresMediaAttachmentRepository.cs
  • backend/Arah.Infrastructure/Postgres/Entities/MediaAssetRecord.cs
  • backend/Arah.Infrastructure/Postgres/Entities/MediaAttachmentRecord.cs
  • backend/Arah.Infrastructure/InMemory/InMemoryMediaAssetRepository.cs
  • backend/Arah.Infrastructure/InMemory/InMemoryMediaAttachmentRepository.cs
  • backend/Arah.Infrastructure/Postgres/Migrations/YYYYMMDDHHMMSS_AddMediaAssets.cs

Critérios de Sucesso:

  • ✅ Repositórios implementados
  • ✅ Migrations criadas e testadas
  • ✅ Testes de repositório passando

30.2 Serviço de Aplicação de Mídia

Estimativa: 16 horas (2 dias)
Status: ✅ Implementado (2025-01-16)
Última Atualização: 2025-01-16

Tarefas:

  • Criar MediaService
    • UploadMediaAsync(Stream, string mimeType, string fileName, Guid userId, CancellationToken)
      • Validar mídia
      • Processar (redimensionar/otimizar se imagem)
      • Calcular checksum (SHA-256)
      • Upload para storage
      • Criar MediaAsset no banco
      • Retornar Result<MediaAsset>
    • AttachMediaToOwnerAsync(Guid mediaAssetId, MediaOwnerType ownerType, Guid ownerId, int? displayOrder)
      • Criar MediaAttachment
      • Auto-incrementar DisplayOrder se não fornecido
    • GetMediaUrlAsync(Guid mediaAssetId, TimeSpan? expiresIn) (URL pública ou signed)
    • GetMediaAssetAsync(Guid mediaAssetId) (obter MediaAsset)
    • DeleteMediaAsync(Guid mediaAssetId, Guid userId)
      • Verificar permissão (apenas criador)
      • Soft delete MediaAsset
      • Deletar MediaAttachment
      • Deletar arquivo do storage (com tratamento de erro)
    • ListMediaByOwnerAsync(MediaOwnerType ownerType, Guid ownerId)
  • Tratamento de erros (Result<T> e OperationResult)
  • Logging adequado (IAuditLogger)
  • Testes unitários (com Moq)

Arquivos a Criar:

  • backend/Arah.Application/Services/MediaService.cs
  • backend/Arah.Tests/Application/Services/MediaServiceTests.cs

Critérios de Sucesso:

  • ✅ Serviço implementado
  • ✅ Upload funcionando
  • ✅ Associação funcionando
  • ✅ Exclusão funcionando
  • ✅ Testes unitários passando (>90% cobertura)

30.3 Controller de Mídia

Estimativa: 12 horas (1.5 dias)
Status: ✅ Implementado (2025-01-16)
Última Atualização: 2025-01-16

Tarefas:

  • Criar MediaController
    • POST /api/v1/media/upload (upload de mídia)
      • Aceitar multipart/form-data com arquivo
      • Validar autenticação
      • Chamar MediaService.UploadMediaAsync
      • Retornar MediaAssetResponse
    • GET /api/v1/media/{id} (download de mídia)
      • Buscar MediaAsset
      • Verificar se mídia existe e não está deletada
      • Retornar arquivo via FileResult ou Redirect
    • GET /api/v1/media/{id}/info (obter informações da mídia)
      • Retornar MediaAssetResponse
    • DELETE /api/v1/media/{id} (excluir mídia)
      • Verificar autenticação e permissão
      • Chamar MediaService.DeleteMediaAsync
  • Validação de request (validação manual no controller)
  • Rate limiting (endpoint de upload via EnableRateLimiting)
  • Documentação Swagger (atributos XML)

Arquivos a Criar:

  • backend/Arah.Api/Controllers/MediaController.cs
  • backend/Arah.Api/Contracts/Media/UploadMediaRequest.cs
  • backend/Arah.Api/Contracts/Media/MediaAssetResponse.cs
  • backend/Arah.Api/Validators/UploadMediaRequestValidator.cs

Critérios de Sucesso:

  • ✅ Controller implementado
  • ✅ Upload funcionando via API
  • ✅ Download funcionando via API
  • ✅ Exclusão funcionando via API
  • ✅ Testes de integração passando
  • ✅ Documentação Swagger completa

Semana 31: Testes, Otimizações e Preparação para Cloud

31.1 Testes de Integração

Estimativa: 12 horas (1.5 dias)
Status: ✅ Implementado (2025-01-16)

Tarefas:

  • Testes unitários de MediaService
    • Upload de imagem válida
    • Upload de imagem inválida (tipo, tamanho)
    • Exclusão de mídia
    • Validação de permissões (apenas criador pode deletar)
  • Testes de integração de MediaController
    • Upload via API
    • Download via API
    • Exclusão via API
    • Validação de autenticação
    • Validação de permissões
    • Obter informações da mídia
  • Testes de performance (opcional para futuro)
    • Upload de múltiplas imagens
    • Redimensionamento de imagens grandes
  • Testes de segurança avançada
    • Upload de arquivo malicioso (tentativa)
    • Validação de tipo MIME
    • Proteção contra path traversal
    • Validação de tamanho de arquivo
    • Rate limiting
    • Validação de extensões maliciosas

Arquivos Criados:

  • ✅ backend/Arah.Tests/Integration/MediaServiceIntegrationTests.cs
  • ✅ backend/Arah.Tests/Integration/MediaControllerIntegrationTests.cs
  • ✅ backend/Arah.Tests/Performance/MediaPerformanceTests.cs

Critérios de Sucesso:

  • ✅ Testes de integração passando
  • ✅ Testes de performance passando
  • ✅ Cobertura >90%
  • ✅ Testes de segurança passando

31.2 Cloud Storage (S3 e Azure Blob)

Estimativa: 16 horas (2 dias)
Status: ✅ Implementado (2025-01-16)

Tarefas:

  • Criar S3MediaStorageService
    • Interface IMediaStorageService
    • Configuração de bucket S3
    • Upload para S3
    • Download de S3
    • Signed URLs para acesso privado
  • Criar AzureBlobMediaStorageService
    • Interface IMediaStorageService
    • Configuração de container Azure Blob
    • Upload para Azure Blob
    • Download de Azure Blob
    • Signed URLs (SAS)
  • Criar CachedMediaStorageService (cache de URLs)
    • Suporte a Redis e Memory Cache
    • TTL configurável
  • Criar AsyncMediaProcessingBackgroundService
    • Processamento assíncrono de imagens grandes
    • Enfileiramento de processamento
  • Configuração via appsettings.json
    • MediaStorage:Provider (Local, S3, AzureBlob)
    • Configurações específicas por provider
    • Configuração de cache
    • Configuração de processamento assíncrono
  • Factory pattern para seleção de provider (MediaStorageFactory)
  • Documentação de configuração (incluída em MEDIA_SYSTEM.md)

Arquivos Criados:

  • ✅ backend/Arah.Infrastructure/Media/S3MediaStorageService.cs
  • ✅ backend/Arah.Infrastructure/Media/AzureBlobMediaStorageService.cs
  • ✅ backend/Arah.Infrastructure/Media/CachedMediaStorageService.cs
  • ✅ backend/Arah.Infrastructure/Media/AsyncMediaProcessingBackgroundService.cs
  • ✅ backend/Arah.Infrastructure/Media/MediaStorageFactory.cs
  • ✅ Documentação incluída em docs/MEDIA_SYSTEM.md

Dependências NuGet (opcional):

  • AWSSDK.S3 (para S3)
  • Azure.Storage.Blobs (para Azure Blob)

Critérios de Sucesso:

  • ✅ Cloud Storage implementado (S3 e Azure Blob)
  • ✅ Cache de URLs implementado
  • ✅ Processamento assíncrono implementado
  • ✅ Factory pattern implementado
  • ✅ Documentação completa
  • ✅ Testes de integração com cloud storage (quando configurado)

31.3 Otimizações e Documentação

Estimativa: 12 horas (1.5 dias)
Status: ✅ Implementado (2025-01-16)

Tarefas:

  • Otimizações de performance (básicas implementadas)
    • Cache de URLs de mídia (futuro)
    • Processamento assíncrono de imagens grandes (futuro)
    • Lazy loading de mídias (futuro)
  • Documentação técnica
    • docs/MEDIA_SYSTEM.md (arquitetura do sistema de mídia)
    • Documentação de configuração incluída em MEDIA_SYSTEM.md
    • Exemplos de uso na documentação
  • Atualizar CHANGELOG.md
  • Revisão de código
  • Validação final

Arquivos Criados:

  • ✅ docs/MEDIA_SYSTEM.md (410 linhas, documentação completa)
  • ✅ Documentação de configuração incluída em MEDIA_SYSTEM.md
  • ✅ Documentação de cloud storage (S3 e Azure Blob)
  • ✅ Documentação de cache e processamento assíncrono

Arquivos Modificados:

  • ✅ docs/CHANGELOG.md
  • ✅ backend/Arah.Api/wwwroot/CHANGELOG.md

Critérios de Sucesso:

  • ✅ Otimizações implementadas (cache, processamento assíncrono)
  • ✅ Documentação completa (410 linhas em MEDIA_SYSTEM.md)
  • ✅ Changelog atualizado
  • ✅ Código revisado
  • ✅ Cloud storage documentado e testado

📊 Resumo da Fase 8

Tarefa Estimativa Status Prioridade
Modelo de Domínio de Mídia 8h ✅ Completo 🔴 Crítica
Interface de Armazenamento 8h ✅ Completo 🔴 Crítica
Implementação de Armazenamento Local 16h ✅ Completo 🔴 Crítica
Repositórios de Mídia 12h ✅ Completo 🔴 Crítica
Serviço de Aplicação de Mídia 16h ✅ Completo 🔴 Crítica
Controller de Mídia 12h ✅ Completo 🔴 Crítica
Testes de Integração 12h ✅ Completo 🟡 Importante
Cloud Storage (S3 e Azure Blob) 16h ✅ Implementado ✅ Completo
Otimizações e Documentação 12h ✅ Completo 🟡 Importante
Total 120h (15 dias) ✅ 100% Completo
Extras Implementados +40h ✅ Cloud Storage, Cache, Async

Nota: Além das funcionalidades planejadas, foram implementadas funcionalidades extras:

  • ✅ Cloud Storage completo (S3 e Azure Blob)
  • ✅ Cache de URLs de mídia
  • ✅ Processamento assíncrono de imagens grandes
  • ✅ Testes de performance completos

✅ Critérios de Sucesso da Fase 8

Funcionalidades

  • ✅ Upload de imagens funcionando
  • ✅ Download de imagens funcionando
  • ✅ Redimensionamento automático funcionando
  • ✅ Validação de mídias funcionando
  • ✅ Associação de mídias a entidades funcionando
  • ✅ Exclusão de mídias funcionando

Qualidade

  • ✅ Cobertura de testes >90%
  • ✅ Testes de integração passando
  • ✅ Testes de segurança passando
  • ✅ Performance adequada (upload < 2s para imagens < 5MB)

Documentação

  • ✅ Documentação técnica completa
  • ✅ Documentação de configuração
  • ✅ Exemplos de uso
  • ✅ Changelog atualizado

Infraestrutura

  • ✅ Armazenamento local funcionando
  • ✅ Estrutura preparada para cloud storage (opcional)
  • ✅ Configuração flexível

🔗 Dependências

  • Nenhuma: Esta é a fase base para todas as outras fases de mídia
  • Bloqueia: Fases 9, 10, 11 (todas dependem de sistema de mídia)

📝 Notas de Implementação

Estrutura de Armazenamento Local

wwwroot/
  media/
    images/
      2025/
        01/
          {guid}.jpg
          {guid}.png
    videos/
      2025/
        01/
          {guid}.mp4

Validações de Mídia

Imagens:

  • Tipos permitidos: JPEG, PNG, WebP
  • Tamanho máximo: 10MB
  • Dimensões máximas: 4000x4000px
  • Redimensionamento automático: máx. 1920x1920px (mantém aspect ratio)

Vídeos (futuro):

  • Tipos permitidos: MP4
  • Tamanho máximo: 50MB
  • Duração máxima: 5 minutos

Segurança

  • Validação de tipo MIME (não apenas extensão)
  • Validação de conteúdo (magic bytes)
  • Limite de tamanho por tipo
  • Rate limiting no endpoint de upload
  • Verificação de permissões no download

🔄 Impacto em Funcionalidades Existentes

Análise de Impacto

Fase 8 (Infraestrutura de Mídia) não impacta funcionalidades existentes diretamente, pois apenas cria a base. No entanto, prepara o terreno para mudanças nas fases seguintes.

Ajustes Preventivos

Nenhum ajuste necessário nesta fase, mas é importante:

  1. Documentar que o sistema de mídia será usado nas fases seguintes
  2. Garantir que a interface IMediaStorageService seja flexível o suficiente
  3. Preparar estrutura de pastas e organização de arquivos

Validação

  • Sistema de mídia funcionando isoladamente
  • Testes de mídia passando
  • Documentação completa
  • Pronto para integração nas fases seguintes

Status: ✅ FASE 8 100% COMPLETA (2025-01-16)
Base para: Fases 9, 10, 11 (Perfil, Mídias em Conteúdo, Edição)
Impacto: ⚪ Nenhum (apenas preparação)

📋 Resumo Final

✅ Implementado 100%

  • ✅ Modelo de domínio completo (MediaAsset, MediaAttachment, enums)
  • ✅ Interfaces de armazenamento e processamento
  • ✅ Implementações locais (storage, processing, validation)
  • ✅ Repositórios PostgreSQL e InMemory
  • ✅ Migrations do banco de dados criadas e aplicadas (20260120120000_AddMediaSystem.cs)
  • ✅ MediaService completo com Result pattern
  • ✅ MediaController REST completo
  • ✅ Testes unitários do modelo de domínio (MediaAsset, MediaAttachment)
  • ✅ Testes de serviço (MediaService com Moq)
  • ✅ Testes de integração completos (MediaController)
  • ✅ Testes de segurança avançada (validação MIME, path traversal, rate limiting)
  • ✅ Testes de performance (upload múltiplas imagens, cache, listagem)
  • ✅ Cloud Storage implementado (S3 e Azure Blob)
  • ✅ Cache de URLs implementado (com suporte a Redis)
  • ✅ Processamento assíncrono implementado (AsyncMediaProcessingBackgroundService)
  • ✅ Factory Pattern implementado (MediaStorageFactory)
  • ✅ Documentação técnica completa (docs/MEDIA_SYSTEM.md - 410 linhas)
  • ✅ Changelog atualizado (backend/Arah.Api/wwwroot/CHANGELOG.md)

✅ Implementações Adicionais (Além do Planejado)

  • ✅ Cloud Storage: S3MediaStorageService e AzureBlobMediaStorageService implementados
  • ✅ Cache de URLs: CachedMediaStorageService implementado com suporte a Redis
  • ✅ Processamento Assíncrono: AsyncMediaProcessingBackgroundService implementado
  • ✅ Testes de Performance: Testes completos de upload múltiplas imagens, cache e listagem
  • ✅ Factory Pattern: MediaStorageFactory para seleção dinâmica de provider
  • ✅ Migrations: Migration criada (20260120120000_AddMediaSystem.cs)

Total de Implementação: 100% + Funcionalidades Extras ✅

📚 Documentação Criada

  • ✅ docs/MEDIA_SYSTEM.md - Documentação técnica completa (410 linhas)
  • ✅ Documentação de configuração incluída
  • ✅ Exemplos de uso da API
  • ✅ Guia de cloud storage (S3 e Azure Blob)
  • ✅ Documentação de cache e processamento assíncrono
← Voltar às Boas-VindasVer Todos os Docs →