Pular para o conteúdo principal

activity-delivery-api

Introdução ao documento​

Este README descreve o contexto do repositório activity-delivery-api, instruções operacionais e referências para evolução técnica.

Versionamento​

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

Referencial teórico​

Introdução​

Back-end do módulo Atividades Entregáveis da plataforma Dhedalos. Gerencia o ciclo de vida de submissões de atividades acadêmicas (entrega, avaliação, reenvio) e notificações associadas, expondo uma API REST consumida pelo aplicativo mobile e pelo painel administrativo (Backpack).

Mapa rápido do repositório​

Stack​

  • Linguagem/framework: PHP 8.2+ / Laravel 12
  • Servidor HTTP: FrankenPHP via Laravel Octane
  • Admin: Laravel Backpack 6.8
  • Banco: MySQL 8.0 (dev) / PostgreSQL (produção)
  • Cache/Session: Redis 7 — fallback: database
  • Fila: Database driver (queue)
  • Storage: AWS S3 / local
  • Auth API: API Key + JWT (firebase/php-jwt)
  • Auth Admin: Session (Fortify)
  • Notificações: Novu (HTTP API)
  • Docs API: L5-Swagger (OpenAPI)
  • Testes: Pest PHP 3.8
  • Monitoramento: Laravel Telescope, Laravel Pulse
  • CI/CD: GitHub Actions
  • Infra: Docker, Helm, Kubernetes (OKE)

Como rodar local​

Pré-requisitos:

  • Docker e Docker Compose
  • Node.js / npm (na máquina host)

Comandos:

# 1. Instalar dependências do host
npm install

# 2. Copiar variáveis de ambiente
cp .env.example .env

# 3. Subir containers
docker-compose up --build

# 4. Executar migrations e seeds
docker-compose exec laravel php artisan migrate --seed

# 5. Gerar chave da aplicação
docker-compose exec laravel php artisan key:generate

# 6. Criar link de storage
docker-compose exec laravel php artisan storage:link

# 7. Gerar documentação Swagger
docker-compose exec laravel php artisan l5-swagger:generate

Usuário default​

  • Email: root@root.com
  • Senha: root
  • Role: admin
  • Criado automaticamente pelo UserSeeder em ambiente local.

Testes​

# Todos os testes
docker-compose exec laravel php artisan test

# Teste específico
docker-compose exec laravel php artisan test --filter="ActivityTemplateFileControllerTest"

# Com cobertura
docker-compose exec laravel php artisan test --coverage

# Apenas unitários
docker-compose exec laravel php artisan test tests/Unit/

# Apenas feature
docker-compose exec laravel php artisan test tests/Feature/
  • 140 testes passando, 375 assertions
  • Cobertura: endpoints de API, autenticação, modelos, controllers, services, middleware, providers
  • Para detalhes completos: TESTING.md

Lint​

docker compose exec laravel vendor/bin/phpinsights -v --config-path='config/insights.php' --fix

Gerar API Key​

docker-compose exec laravel php artisan api:key:generate --description="Descrição da chave"

Variáveis de ambiente​

VariávelObrigatóriaExemploOrigem/Evidência
APP_NAMEsimLaravel.env.example:1
APP_ENVsimlocal.env.example:2
APP_KEYsim(gerada via key:generate).env.example:3
APP_DEBUGsimtrue.env.example:4
APP_URLsimhttp://localhost:8000.env.example:5
DB_CONNECTIONsimmysql.env.example:22
DB_HOSTsimmysql.env.example:23
DB_PORTsim3306.env.example:24
DB_DATABASEsimlaravel.env.example:25
DB_USERNAMEsimlaravel.env.example:26
DB_PASSWORDsim***.env.example:27
FILESYSTEM_DISKsimlocal.env.example:36
QUEUE_CONNECTIONsimdatabase.env.example:37
REDIS_HOSTnãoredis.env.example:44
REDIS_PORTnão6379.env.example:46
AWS_ACCESS_KEY_IDprod(secret).env.example:60
AWS_SECRET_ACCESS_KEYprod(secret).env.example:61
AWS_DEFAULT_REGIONprodus-east-1.env.example:62
AWS_BUCKETprod(bucket name).env.example:63
L5_SWAGGER_GENERATE_ALWAYSnãotrue.env.example:67
JWT_SECRETsim(secret)app/Http/Controllers/Api/SubmissionController.php, app/Http/Middleware/JwtAuthenticate.php
NOVU_URLsimhttps://api.novu.co/v1/events/triggerapp/Services/NotificationService.php
NOVU_SECRET_KEYsim(secret)app/Services/NotificationService.php, bootstrap/providers.php

⚠️ PENDÊNCIA: As variáveis JWT_SECRET, NOVU_URL e NOVU_SECRET_KEY não constam no .env.example. Devem ser adicionadas ao arquivo para garantir rastreabilidade.

Contexto C4 L1​

Atores​

  • Participante (aluno) — submete atividades via app mobile
  • Facilitador (professor) — avalia submissões via app mobile ou painel admin
  • Administrador — gerencia usuários, permissões e configurações via Backpack

Sistema em foco​

  • activity-delivery-api — API REST que gerencia o ciclo de vida de submissões de atividades entregáveis (criação, avaliação, reenvio, notificação)

Integrações externas​

  • Novu — serviço de notificações (e-mail/push) — Evidência: app/Services/NotificationService.php:23
  • AWS S3 — armazenamento de arquivos de submissões e templates — Evidência: config/filesystems.php, .env.example:60-64
  • App Mobile Dhedalos — consome a API via API Key + JWT — Evidência: routes/api.php:14-34

Repos relacionados​

Práticas padronizadas no código e UI​

  • PHPDoc para contratos, tipos e comentários estruturados em PHP — Evidência: app/Http/Controllers/Docs/OpenApi.php.
  • L5-Swagger + anotações OpenAPI para documentação de API.
  • Pest PHP para cobertura de testes automatizados.
  • Laravel Backpack para painéis CRUD administrativos.
  • Spatie Permission para controle de acesso baseado em roles/permissions.

Fluxo de manutenção da documentação​

Documentação detalhada​

Governança automática​

  • GitHub Action obrigatória: .github/workflows/docs-governance.yml.
  • A Action valida presença dos arquivos e seções obrigatórias de documentação.

Visualização da OpenAPI​

  • Abra docs/api/openapi.yaml com extensão OpenAPI/Swagger no VS Code (ex.: 42Crunch OpenAPI Editor).
  • Use o preview da extensão para revisar rotas, schemas e erros antes do PR.
  • Documentação interativa via Swagger UI: http://localhost:8000/api/documentation.

Pendências​

  • ⚠️ PENDÊNCIA: Variáveis JWT_SECRET, NOVU_URL e NOVU_SECRET_KEY ausentes do .env.example.
  • ⚠️ PENDÊNCIA: Documentar URLs dos ambientes de staging/produção quando disponíveis.
  • ⚠️ PENDÊNCIA: Configurar checklist de DoD para PRs com impacto em documentação.