Pular para o conteúdo principal

Features

Introdução ao documento​

Este documento orienta o padrão para descrição funcional de features do serviço activity-delivery-api e serve como índice das features documentadas.

Versionamento​

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

Referencial teórico​

Escopo​

Documentação funcional por feature do repositório activity-delivery-api.

Features identificadas​

1. Submissão de atividades​

  • Atores: Participante (aluno) via app mobile
  • Fluxo: Participante envia atividade com arquivos → sistema persiste submissão e arquivos no S3 → envia notificações ao participante e facilitador
  • Endpoints: POST /api/submissions (JWT), GET /api/submissions/token (API Key)
  • Dados: deliverable_submissions, submission_files
  • Evidência: app/Http/Controllers/Api/SubmissionController.php:755 — método getToken; app/Http/Controllers/Api/SubmissionController.php:187 — método store

2. Avaliação de submissões​

  • Atores: Facilitador (professor) via app mobile ou painel admin
  • Fluxo: Facilitador visualiza submissão → atualiza status/nota/comentário → sistema envia notificação ao participante
  • Endpoints: POST /api/submissions/{id} (API Key), Admin CRUD
  • Dados: deliverable_submissions (campos status, score, facilitator_comment, evaluated_at)
  • Evidência: app/Http/Controllers/Api/SubmissionController.php:340 — método update

3. Solicitação de reenvio​

  • Atores: Facilitador
  • Fluxo: Facilitador deleta submissão com action=resend → sistema soft-deleta, remove arquivos e envia notificação ao participante para reenviar
  • Endpoints: DELETE /api/submissions/{id}?action=resend (API Key)
  • Evidência: app/Http/Controllers/Api/SubmissionController.php:413 — método destroy

4. Consulta de submissões​

  • Atores: App mobile, facilitador
  • Fluxo: Listagem com filtros (course, class, participant, facilitator, status, cycle) e visualização individual
  • Endpoints: GET /api/submissions, GET /api/submissions/{id} (API Key)
  • Evidência: app/Http/Controllers/Api/SubmissionController.php:87 — método index; app/Http/Controllers/Api/SubmissionController.php:137 — método show

5. Status summary (painel do facilitador)​

  • Atores: Facilitador via app mobile
  • Fluxo: Consulta resumo de submissões pendentes agrupadas por ciclo e turma
  • Endpoints: GET /api/submissions/status-sumary (API Key)
  • Evidência: app/Http/Controllers/Api/SubmissionController.php:524 — método checkPendingActivityReviews

6. Download de arquivos (ZIP)​

  • Atores: Facilitador, sistema
  • Fluxo: Gera ZIP com arquivos de submissão filtrados por critérios
  • Endpoints: GET /api/submissions/files (API Key)
  • Evidência: app/Http/Controllers/Api/SubmissionController.php:697 — método getFiles

7. Limpeza de arquivos por ciclo​

  • Atores: Sistema/admin
  • Fluxo: Remove arquivos físicos de um ciclo completo (mantém registros DB)
  • Endpoints: DELETE /api/submissions/files (API Key)
  • Evidência: app/Http/Controllers/Api/SubmissionController.php:602 — método deleteFiles

8. Gestão de arquivos modelo de atividade​

  • Atores: Admin, sistema externo via API
  • Fluxo: CRUD de arquivos modelo (templates) associados a curso/atividade/ciclo/turma
  • Endpoints: GET/POST/PUT/DELETE /api/activity-template-files (API Key), Admin CRUD
  • Dados: activity_template_files
  • Evidência: app/Http/Controllers/Api/ActivityTemplateFileController.php:12

9. Painel administrativo (Backpack)​

  • Atores: Administrador
  • Fluxo: CRUD de submissões, usuários, roles, permissions, chaves Novu, arquivos modelo + visualização de Swagger docs e logs
  • Endpoints: /admin/*
  • Evidência: routes/backpack/custom.php:12-32, controllers em app/Http/Controllers/Admin/

10. Gestão de chaves Novu​

  • Atores: Administrador via painel Backpack
  • Fluxo: CRUD de chaves de workflow Novu (description, novu_key, app_key)
  • Dados: novu_keys
  • Evidência: app/Http/Controllers/Admin/NovuKeyCrudController.php

Como documentar cada feature​

Criar arquivo docs/features/<slug>.md com:

  1. Visão geral
  2. Atores
  3. Pré-condições
  4. Fluxo principal
  5. Fluxos alternativos
  6. Regras de negócio
  7. Estados possíveis
  8. Endpoints envolvidos
  9. Dados afetados
  10. Pendências

Relações cruzadas​

  • API: docs/api/openapi.yaml
  • Dados: docs/data/model.md
  • Arquitetura: docs/architecture/c4-component.md

Pendências​

  • ⚠️ PENDÊNCIA: Criar documentação detalhada individual para features restantes (consulta-submissoes, status-summary, download-zip, limpeza-arquivos, painel-backpack, gestao-chaves-novu).
  • ⚠️ PENDÊNCIA: Mapear regras de negócio detalhadas para transição de status da submissão (pending → submitted → evaluated).
  • ⚠️ PENDÊNCIA: Documentar fluxos alternativos e edge cases por feature.

Features detalhadas (individuais)​