Pular para o conteúdo principal

Feature: Gestão de Arquivos Modelo

Introdução ao documento​

Documenta o fluxo de CRUD de arquivos modelo (templates) de atividades.

Versionamento​

  • Versão do documento: 1.0.0
  • Última atualização: 2026-03-04
  • Responsável: Time Dhedalos

Referencial teórico​

Visão geral​

Arquivos modelo (templates) são associados a combinações de curso/atividade/ciclo/turma. São gerenciados via API (sistema externo) e via painel admin (Backpack). Servem como referência para os participantes na elaboração de suas submissões.

Atores​

  • Sistema externo — cria/atualiza templates via API
  • Administrador — gerencia templates via painel Backpack
  • Participante — consome templates (leitura)

Pré-condições​

  1. API Key válida para operações via API — Evidência: app/Http/Middleware/ApiKeyMiddleware.php:15
  2. Autenticação admin para operações via Backpack — Evidência: app/Http/Middleware/CheckIfAdmin.php

Fluxo principal (via API)​

  1. Sistema envia POST /api/activity-template-files com API Key + dados + arquivo
    • Evidência: routes/api.php:27, app/Http/Controllers/Api/ActivityTemplateFileController.php:50
  2. Controller valida dados via ActivityTemplateFileRequest
    • Evidência: app/Http/Requests/ActivityTemplateFileRequest.php
  3. TemplateFileService::replaceFile() faz upload do arquivo para S3/local na pasta activity-templates/
    • Evidência: app/Services/TemplateFileService.php:23
  4. Registro criado em activity_template_files
    • Evidência: app/Models/ActivityTemplateFile.php:18
  5. Retorna JSON do template criado (HTTP 201)

Fluxos alternativos​

  • Filtro por curso/atividade: GET /api/activity-template-files/filter filtra templates por parâmetros.
    • Evidência: routes/api.php:25, app/Http/Controllers/Api/ActivityTemplateFileController.php:27
  • Visualização individual: GET /api/activity-template-files/{id} retorna template específico.
    • Evidência: routes/api.php:26, app/Http/Controllers/Api/ActivityTemplateFileController.php:21
  • Atualização: PUT /api/activity-template-files/{id} atualiza dados e/ou arquivo.
    • Evidência: routes/api.php:28, app/Http/Controllers/Api/ActivityTemplateFileController.php:89
  • Exclusão: DELETE /api/activity-template-files/{id} soft-deleta o template.
    • Evidência: routes/api.php:29, app/Http/Controllers/Api/ActivityTemplateFileController.php:118
  • CRUD Admin: Via Backpack em /admin/activity-template-file.
    • Evidência: routes/backpack/custom.php:32, app/Http/Controllers/Admin/ActivityTemplateFileCrudController.php

Regras de negócio​

  1. Unique constraint: Combinação (course_id, activity_id, cycle_id, class_id, original_name) é única.
    • Evidência: database/migrations/2025_12_15_201931_create_activity_template_files.php:30
  2. Soft delete: Templates são soft-deletados, preservando histórico.
    • Evidência: app/Models/ActivityTemplateFile.php:14 (trait SoftDeletes)
  3. Cleanup automático: Ao deletar model, arquivo físico é removido automaticamente via booted().
    • Evidência: app/Models/ActivityTemplateFile.php:54

Estados possíveis​

  • Ativo (sem deleted_at)
  • Soft-deletado (deleted_at preenchido)

Endpoints envolvidos​

  • GET /api/activity-template-files/filter — filtrar templates (openapi.yaml)
  • GET /api/activity-template-files/{id} — visualizar template
  • POST /api/activity-template-files — criar template
  • PUT /api/activity-template-files/{id} — atualizar template
  • DELETE /api/activity-template-files/{id} — excluir template
  • Evidência: routes/api.php:25-29

Dados impactados​

  • activity_template_files — registros de templates (model.md)
  • Storage S3/local — arquivos na pasta activity-templates/

Pendências​

  • ⚠️ PENDÊNCIA: Documentar MIME types permitidos para templates (se diferem dos de submissão).
  • ⚠️ PENDÊNCIA: Verificar se download de template é público ou requer autenticação.