Pular para o conteúdo principal

Inventário do Repositório

Introdução ao documento​

Este documento consolida o inventário técnico do repositório activity-delivery-api com base em evidências do código e das configurações.

Versionamento​

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

Referencial teórico​

Mapa de descoberta técnica​

Propósito do repo​

  • API REST para gestão do ciclo de vida de atividades entregáveis: submissão, avaliação, reenvio e notificação de participantes e facilitadores.
  • Evidência: routes/api.php:14-34, app/Http/Controllers/Api/SubmissionController.php:87

Entrypoints​

  1. API REST — routes/api.php:14-34 — endpoints para submissões e arquivos de template, protegidos por api.key e jwt.auth.
  2. Painel Admin (Backpack) — routes/web.php + routes/backpack/custom.php:12-32 — CRUD de usuários, submissões, roles, permissions, chaves Novu e arquivos modelo.
  3. Artisan Commands — app/Console/Commands/GenerateApiKey.php:16 — geração de chaves de API ($signature = 'api:key:generate').
  4. Healthcheck — GET /up — registrado em bootstrap/app.php.

Principais pastas e responsabilidade​

  • app/Http/Controllers/Api/ — Controllers da API REST (SubmissionController, ActivityTemplateFileController)
  • app/Http/Controllers/Admin/ — Controllers CRUD do Backpack (DeliverableSubmissionCrudController, UserCrudController, etc.)
  • app/Http/Controllers/Docs/ — Definições OpenAPI/Swagger (OpenApi.php)
  • app/Http/Middleware/ — Middleware customizado (ApiKeyMiddleware, JwtAuthenticate, CheckIfAdmin, ViewLogs)
  • app/Http/Requests/ — Form Requests de validação (DeliverableSubmissionRequest, ActivityTemplateFileRequest, etc.)
  • app/Models/ — Eloquent Models (User, DeliverableSubmission, SubmissionFile, ApiKey, NovuKey, ActivityTemplateFile, Role, Permission)
  • app/Services/ — Lógica de negócio (NotificationService, SubmissionFileService, TemplateFileService)
  • app/Actions/Fortify/ — Ações de autenticação Fortify (CreateNewUser, ResetUserPassword, etc.)
  • app/Helpers/ — Helpers utilitários (MimeTypes.php)
  • app/Providers/ — Service Providers (AppServiceProvider, FortifyServiceProvider, NovuServiceProvider, TelescopeServiceProvider)
  • database/migrations/ — Migrations do schema do banco de dados
  • database/seeders/ — Seeders (UserSeeder — cria usuário root e roles padrão)
  • database/factories/ — Model Factories para testes
  • config/ — Configurações Laravel e pacotes (backpack, permission, l5-swagger, octane, pulse, telescope)
  • routes/ — Definição de rotas (api, web, backpack, console)
  • tests/ — Testes Pest PHP (Feature e Unit)

Integrações externas identificadas​

  • Novu API — notificações por e-mail/push via HTTP POST — Evidência: app/Services/NotificationService.php:23
  • AWS S3 — armazenamento de arquivos (submissões e templates) — Evidência: config/filesystems.php, .env.example:60-64
  • Redis — cache e sessão — Evidência: .env.example:43-46, config/cache.php

Jobs / cron / queues / workers​

  • Queue driver: database — Evidência: config/queue.php, .env.example:37
  • Supervisor worker: configurado no Dockerfile de produção — Evidência: Dockerfile:30-33
  • Jobs tables: jobs, job_batches, failed_jobs — Evidência: database/migrations/

⚠️ PENDÊNCIA: Nenhum job dispatch explícito identificado no código-fonte atual. Verificar se há jobs enfileirados em funcionalidades futuras.

Storage / caches​

  • File storage: S3 (produção) / local (dev) — Evidência: config/filesystems.php
  • Paths de upload: submissions/ (arquivos de submissão), activity-templates/ (arquivos modelo) — Evidência: app/Services/SubmissionFileService.php:14, app/Services/TemplateFileService.php:23
  • Cache: database (default) / Redis (configurado) — Evidência: config/cache.php
  • Session: database — Evidência: .env.example:29

Lista de variáveis de ambiente​

  • APP_NAME: .env.example:1
  • APP_ENV: .env.example:2
  • APP_KEY: .env.example:3
  • APP_DEBUG: .env.example:4
  • APP_URL: .env.example:5
  • DB_CONNECTION: .env.example:22
  • DB_HOST: .env.example:23
  • DB_PORT: .env.example:24
  • DB_DATABASE: .env.example:25
  • DB_USERNAME: .env.example:26
  • DB_PASSWORD: .env.example:27
  • FILESYSTEM_DISK: .env.example:36
  • QUEUE_CONNECTION: .env.example:37
  • REDIS_HOST: .env.example:44
  • REDIS_PORT: .env.example:46
  • AWS_ACCESS_KEY_ID: .env.example:60
  • AWS_SECRET_ACCESS_KEY: .env.example:61
  • AWS_DEFAULT_REGION: .env.example:62
  • AWS_BUCKET: .env.example:63
  • L5_SWAGGER_GENERATE_ALWAYS: .env.example:67
  • JWT_SECRET: app/Http/Controllers/Api/SubmissionController.php, app/Http/Middleware/JwtAuthenticate.php
  • NOVU_URL: app/Services/NotificationService.php
  • NOVU_SECRET_KEY: app/Services/NotificationService.php

Comandos para rodar, testar e buildar​

  • Run: docker-compose up --build
  • Test: docker-compose exec laravel php artisan test
  • Test coverage: docker-compose exec laravel php artisan test --coverage
  • Lint: docker compose exec laravel vendor/bin/phpinsights -v --config-path='config/insights.php' --fix
  • Swagger: docker-compose exec laravel php artisan l5-swagger:generate
  • Build (prod): docker build -t activity-delivery-api .
  • API Key: docker-compose exec laravel php artisan api:key:generate

Pendências​

  • ⚠️ PENDÊNCIA: Variáveis JWT_SECRET, NOVU_URL e NOVU_SECRET_KEY ausentes do .env.example.
  • ⚠️ PENDÊNCIA: Verificar se existe uso de cron/scheduler além do worker de fila.
  • ⚠️ PENDÊNCIA: Documentar endpoints de healthcheck Kubernetes (liveness/readiness probes) a partir dos Helm charts.