Pular para o conteúdo principal

Feature: Cursos AoVivo

Introdução ao documento​

Este documento descreve a funcionalidade de gestão e visualização de cursos ao vivo, incluindo estatísticas de inscrições e ciclos.

Versionamento​

  • Versão do documento: 1.0.0
  • Última atualização: 2026-03-09
  • Responsável: Marivaldo Vinicius

Referencial teórico​

Visão geral​

A feature de cursos AoVivo permite visualizar e gerenciar dados de cursos ao vivo, incluindo ciclos, inscrições, estatísticas e filtros. Sistema integra com duas fontes: WordPress API (via service) e AoVivo API (direta), com cache estratégico para otimizar performance.

Atores envolvidos​

  • Administrador: Visualiza estatísticas e gerencia cursos ao vivo
  • Sistema: Integra com WordPress API e AoVivo API
  • Frontend React: Consome APIs e exibe dados em dashboards e tabelas

Pré-condições​

  • WordPress API configurada (WORDPRESS_API_URL, WORDPRESS_API_TOKEN)
  • AoVivo API configurada (AO_VIVO_API, AO_VIVO_TOKEN)
  • Cache Laravel configurado e operacional
  • Permissões adequadas para visualização

Fluxo principal​

Visualização de Estatísticas de Inscrições​

  1. Seleção de ciclo

    • Administrador seleciona ciclo no dashboard AoVivo
    • Frontend envia requisição para /api/v1/ao-vivo/stats/{cycle_id}
    • Parâmetros opcionais: page, per_page (default: 1, 10000)

  2. Busca de dados

    • AoVivoController utiliza EnrollmentStatsService
    • Service verifica cache (TTL: 1 minuto)
    • Se cache não existe ou expirou, chama WordPress API
    • Autenticação via Svc token

  3. Processamento e cache

    • Dados são recebidos do WordPress API
    • Armazenados no cache com chave baseada em parâmetros
    • Retornados ao frontend em formato JSON

  4. Visualização

    • Frontend recebe dados paginados
    • Exibe estatísticas em tabelas e gráficos
    • Permite navegação entre páginas

Listagem de Ciclos e Cursos​

  1. Listar ciclos disponíveis

    • Frontend consome /api/v1/ao-vivo/cycles
    • Service busca do WordPress API com cache de 1 minuto
    • Retorna lista de ciclos em captação

  2. Listar cursos disponíveis

    • Frontend consome /api/v1/ao-vivo/courses
    • Service busca do WordPress API com cache de 4 horas
    • Retorna lista de cursos com informações básicas

  3. Listar ciclos por curso

    • Frontend consome /api/v1/ao-vivo/cycles/{course_id}
    • Service busca ciclos específicos do curso
    • Cache de 4 horas (dados menos dinâmicos)

Integração Direta com AoVivo API​

  1. Endpoints de integração

    • Endpoints /api/v1/dhedalos/v1/live/* chamam AoVivo API diretamente
    • Autenticação via Bearer token
    • Cache de 30 segundos (dados muito dinâmicos)

  2. Dados disponíveis

    • Ciclos: /dhedalos/v1/live/cycles
    • Inscrições por ciclo: /dhedalos/v1/live/enrolls-by-cycle
    • Inscrições por produto: /dhedalos/v1/live/enrolls-by-product
    • Inscrições gerais: /dhedalos/v1/live/enrollments

Fluxos alternativos​

Estatísticas com turno​

  • Endpoint /api/v1/ao-vivo/shift-stats/{cycle_id} retorna estatísticas incluindo informação de turno
  • Mesmo fluxo de cache e integração, mas com endpoint diferente no WordPress API

Falha na integração WordPress​

  • Se WordPress API retorna erro, sistema retorna 500 com mensagem de erro
  • Frontend exibe mensagem de erro ao usuário
  • Cache não é atualizado em caso de erro

Falha na integração AoVivo​

  • Se AoVivo API falha, erro é retornado na resposta
  • Cache não é atualizado
  • Frontend trata erro adequadamente

Cache expirado​

  • Se cache expirou, nova requisição é feita automaticamente
  • Transparente para o usuário
  • Latência pode aumentar se API externa estiver lenta

Regras de negócio​

  1. TTL variável por tipo de dado:

    • Estatísticas dinâmicas: 1 minuto
    • Cursos e ciclos: 4 horas (dados menos frequentes)
    • Integração AoVivo direta: 30 segundos

  2. Paginação obrigatória: Estatísticas sempre retornam paginadas (default: 10000 itens por página)

  3. Autenticação diferenciada:

    • WordPress API: Svc token (WORDPRESS_API_TOKEN)
    • AoVivo API: Bearer token (AO_VIVO_TOKEN)

  4. Idempotência: Mesmos parâmetros sempre retornam mesmos dados (dentro do TTL)

  5. Fallback: Não há fallback se APIs externas falharem

Estados possíveis​

  • Disponível: Dados disponíveis no cache ou API
  • Carregando: Requisição à API externa em andamento
  • Erro: Falha na integração com API externa
  • Cache expirado: Cache existe mas expirou, nova requisição necessária

Endpoints envolvidos​

WordPress API (via Service)​

  • GET /api/v1/ao-vivo/cycles - Lista ciclos disponíveis
  • GET /api/v1/ao-vivo/courses - Lista cursos disponíveis
  • GET /api/v1/ao-vivo/cycles/{course_id} - Lista ciclos por curso
  • GET /api/v1/ao-vivo/stats/{cycle_id} - Estatísticas de inscrições por ciclo
  • GET /api/v1/ao-vivo/shift-stats/{cycle_id} - Estatísticas com turno

AoVivo API (direta)​

  • GET /api/v1/dhedalos/v1/live/cycles - Ciclos do AoVivo
  • GET /api/v1/dhedalos/v1/live/enrolls-by-cycle - Inscrições por ciclo
  • GET /api/v1/dhedalos/v1/live/enrolls-by-product - Inscrições por produto
  • GET /api/v1/dhedalos/v1/live/enrollments - Lista de inscrições

Dados afetados​

  • Cache Laravel: Múltiplas chaves para diferentes tipos de dados

    • enrollment-stats:page_{page}:per_page_{perPage}:cycle_id_{cycleId}
    • cycles-shift
    • available-courses
    • available-cycles:course_id_{courseId}
    • Chaves do AoVivo: cycles, enrolls-by-cycle, enrollments

  • Nenhuma tabela local: Dados não são persistidos, apenas cacheados

Integrações externas​

  • WordPress API: Backend WordPress para dados de enrollment

    • Autenticação: Svc token
    • Endpoints: /export/enrollment-stats, /live/enrollments-stats, /live/cycles, /export/courses, /export/cycles-stats

  • AoVivo API: API externa para dados de cursos ao vivo

    • Autenticação: Bearer token
    • Endpoints: /api/dhedalos/v1/live/*

Services relacionados​

  • EnrollmentStatsService: Service principal para integração com WordPress API
    • Métodos: getEnrollmentStats(), getEnrollmentStatsWithShift(), getCycles(), getAvailableCourses(), getAvailableCyclesByCourse()