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 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-09
  • Responsável: Marivaldo Vinicius

Referencial teórico​

Mapa de descoberta técnica​

Propósito do repo​

Dashboard administrativo da Dhedalos (agência de cursos) para gestão de inscrições, agendamentos, NPS, análise de sentimento e integração com sistema AoVivo. O sistema fornece interface administrativa via Backpack for Laravel e API REST para consumo de dados pelo frontend React.

Entrypoints​

  1. API REST (/api/v1/*): Endpoints para consumo de dados por frontend React e integrações externas

    • Health check disponível em /api/v1/health-check
    • Middleware: ForceJsonResponse, GzipMiddleware, auth:sanctum (quando aplicável)
    • Documentação completa: docs/api/openapi.yaml

  2. Admin Panel (/admin/*): Interface administrativa Backpack

    • Rotas customizadas para funcionalidades administrativas
    • Middleware: HydrateCacheView, RedirectIfMaintenanceModeActive

  3. Web Routes (/): Redirecionamentos para admin panel

    • Rota raiz redireciona para /admin
    • Rota /login também redireciona para /admin

  4. Health Check (/up): Endpoint nativo do Laravel para verificação de saúde

    • Configurado no bootstrap da aplicação

Principais módulos​

Backend​

  • Controllers: 12 controllers API v1 e 24 controllers Admin organizados por funcionalidade
  • Services: Lógica de negócio e integrações externas (EnrollmentStatsService, AdminLogsService)
  • Jobs: Processamento assíncrono de cache e dados (8 jobs)
  • Models: Entidades principais (User, MaintenanceMode, PlainTextToken, VisibleColumnsConfig)
  • Middlewares: Autenticação, compressão, manutenção e controle de acesso

Frontend​

  • React/TypeScript: Interface administrativa com 22 páginas principais
  • Componentes: Reutilizáveis (charts, tables, forms)
  • Contexts: Gerenciamento de estado global (11 contexts)
  • Hooks: Customizados para lógica reutilizável (25 hooks)

Detalhes arquiteturais: docs/architecture/c4-component.md

Integrações externas identificadas​

Google Gemini API​

Análise de sentimento de textos via modelo generativo gemini-2.5-pro. Autenticação via GEMINI_API_KEY. Processa textos e retorna resumos com pontos positivos e negativos. Feature documentada: docs/features/analise-sentimento.md

AoVivo API​

Integração para dados de cursos ao vivo. Endpoints consumidos:

  • /api/dhedalos/v1/live/cycles
  • /api/dhedalos/v1/live/enrolls_by_cycle
  • /api/dhedalos/v1/live/enrollments

Autenticação via Bearer token (AO_VIVO_TOKEN). Cache com TTL de 30 segundos. Feature documentada: docs/features/aovivo.md

WordPress API​

Backend WordPress para enrollment stats e dados de cursos. Autenticação via Svc token (WORDPRESS_API_TOKEN). Base URL configurável via WORDPRESS_API_URL. Busca estatísticas de inscrições, ciclos e cursos disponíveis. Cache com TTL variável (1 minuto a 4 horas dependendo do endpoint).

Redshift (PostgreSQL)​

Data warehouse para consultas analíticas. Utilizado pelos jobs para buscar dados de inscricoes e appointments. Dados são comprimidos com gzip antes de serem armazenados em cache.

MySQL​

Banco de dados principal da aplicação. Utilizado pelos models Eloquent para persistência de dados da aplicação. Modelo de dados: docs/data/model.md

Jobs / cron / queues / workers​

RefreshData​

Job principal para atualização de cache de inscrições, cursos e agendamentos. Conecta ao Redshift para buscar dados, processa e comprime com gzip antes de armazenar no cache Laravel. Métodos: refreshInscricoes(), refreshCursos(), refreshAgendamento().

Cache Jobs específicos​

Jobs dedicados para atualização de cache por domínio:

  • InscricoesCacheJob
  • AgendamentoCacheJob
  • CursosCacheJob
  • NPSUpMarketingCacheJob
  • NPSUpFinancasCacheJob
  • NPSDecolaMeiCacheJob
  • NPSMulheresEmFocoCacheJob

Jobs são processados via Laravel Queue (configurável via QUEUE_CONNECTION).

Storage / caches​

Laravel Cache​

Sistema de cache principal usando Redis/Memcached/File (configurável via CACHE_DRIVER). Chaves definidas no enum CacheKeys:

  • inscricoes55, cursos55, agendamento
  • nps-up-marketing, nps-up-financas, nps-decola-mei, nps-mulheres-em-foco
  • cycles, enrolls-by-cycle, enrollments

TTL padrão: 30 segundos para AoVivo, 1 minuto a 4 horas para WordPress (dependendo do endpoint).

Compressão​

Dados de inscrições e agendamentos são comprimidos com gzip antes de serem armazenados no cache para otimizar uso de memória.

Lista de variáveis de ambiente​

Principais variáveis necessárias:

Aplicação:

  • APP_KEY, APP_NAME, APP_ENV, APP_DEBUG, APP_URL

Banco de dados:

  • DB_CONNECTION, DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD
  • REDSHIFT_DB_HOST, REDSHIFT_DB_PORT, REDSHIFT_DB_DATABASE, REDSHIFT_DB_USERNAME, REDSHIFT_DB_PASSWORD

Integrações:

  • GEMINI_API_KEY, GEMINI_BASE_URL, GEMINI_REQUEST_TIMEOUT
  • AO_VIVO_TOKEN, AO_VIVO_API
  • WORDPRESS_API_TOKEN, WORDPRESS_API_URL

Infraestrutura:

  • CACHE_DRIVER, QUEUE_CONNECTION, REDIS_HOST

Lista completa disponível na configuração de produção.

Testes​

Testes Backend (Pest PHP)​

Testes unitários e de feature utilizando Pest PHP. Localizados em tests/Unit/ e tests/Feature/. Execução via docker compose exec laravel php artisan test ou docker compose exec laravel ./vendor/bin/pest.

Testes E2E (Cypress)​

Testes end-to-end utilizando Cypress para validar fluxos completos da interface administrativa. Localizados em cypress/e2e/. Execução via npm run cypress:open (interface gráfica) ou npm run cypress:run (headless). Documentação completa: docs/tests/cypress.md

Estrutura:

  • 12 arquivos de teste E2E em cypress/e2e/
  • Page Objects em cypress/e2e/forms/
  • Custom commands e helpers em cypress/support/
  • Configuração em cypress.config.js
  • Workflow CI/CD em .github/workflows/cypress.yml

Comandos para rodar, testar e buildar​

  • Run: docker compose up
  • Test (Backend): docker compose exec laravel php artisan test ou docker compose exec laravel ./vendor/bin/pest
  • Test (E2E): npm run cypress:open (interface gráfica) ou npm run cypress:run (headless)
  • Build (frontend): npm run build ou via docker docker compose exec vite npm run build
  • Swagger: docker compose exec laravel php artisan l5-swagger:generate