Pular para o conteúdo principal

Dhedalos - Dashboard

Introdução ao documento​

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

Versionamento​

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

Referencial teórico​

Introdução​

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.

Mapa rápido do repositório​

Stack​

  • Linguagem/Framework: PHP 8.2+, Laravel 11.9+ - evidência: composer.json:8-19
  • Frontend: React 18.3+, TypeScript 5.5+, Vite 5.3+ - evidência: package.json:32-56
  • Admin Panel: Backpack for Laravel 6.7+ - evidência: composer.json:9-13
  • Banco de dados: MySQL 8.0, Redshift (read-only) - evidência: config/database.php:47-90
  • Cache: Laravel Cache (Redis/Memcached) - evidência: config/cache.php
  • Autenticação: Laravel Sanctum 4.0+ - evidência: composer.json:21, routes/api.php:68
  • API Docs: L5-Swagger 8.6+ - evidência: composer.json:14
  • Testes: Pest PHP 3.8+ - evidência: composer.json:33-34
  • Infra/Deploy: Docker Compose (dev), Kubernetes/Helm (prod) - evidência: docker-compose.yml, helm/
  • Integrações: Google Gemini API (sentiment analysis), AoVivo API - evidência: config/gemini.php:17, routes/api.php:44

Como rodar local​

Pré-requisitos:

  • Docker e Docker Compose
  • PHP >= 8.2 (se rodar sem Docker)
  • Composer >= 2.7.2
  • Node >= 18
  • MySQL >= 8.0.32

Comandos:

# start
docker compose up

# testes
docker compose exec laravel php artisan test
docker compose exec laravel ./vendor/bin/pest

# build (frontend)
npm run build
# ou via docker
docker compose exec vite npm run build

Variáveis de ambiente​

VariávelObrigatóriaExemploOrigem/Evidência
APP_KEYsimbase64:...helm/templates/secret.yaml:12
APP_NAMEsimDhedalos Dashboardconfig/app.php:16
APP_ENVsimlocal/productionconfig/app.php:29
APP_DEBUGsimtrue/falseconfig/app.php:42
APP_URLsimhttp://localhost:8000config/app.php:55
DB_CONNECTIONsimmysqlconfig/database.php:19
DB_HOSTsim127.0.0.1config/database.php:48
DB_PORTsim3306config/database.php:49
DB_DATABASEsimlaravelconfig/database.php:50
DB_USERNAMEsimrootconfig/database.php:51
DB_PASSWORDsimpasswordconfig/database.php:52
REDSHIFT_DB_HOSTnãoredshift-cluster.amazonaws.comconfig/database.php:86
REDSHIFT_DB_DATABASEnãowarehouseconfig/database.php:88
REDSHIFT_DB_USERNAMEnãouserconfig/database.php:89
REDSHIFT_DB_PASSWORDnãopasswordconfig/database.php:90
GEMINI_API_KEYsimAIza...config/gemini.php:17
GEMINI_BASE_URLnãohttps://generativelanguage.googleapis.comconfig/gemini.php:27
AO_VIVO_TOKENsimBearer tokenapp/Http/Controllers/Api/v1/AoVivoIntegracaoController.php:44
AO_VIVO_APIsimhttps://api.aovivo.comapp/Http/Controllers/Api/v1/AoVivoIntegracaoController.php:46
REDIS_HOSTnão127.0.0.1helm/templates/secret.yaml:25
CACHE_DRIVERnãoredis/filehelm/templates/secret.yaml:67
QUEUE_CONNECTIONnãoredis/synchelm/templates/secret.yaml:75

Contexto C4 L1​

Atores​

  • Administradores: Usuários que acessam o painel administrativo Backpack (/admin)
  • Sistemas externos: Integrações via API REST (/api/v1/*)

Sistema em foco​

Dhedalos Dashboard - Sistema de gestão administrativa para agência de cursos que fornece:

  • Dashboard de métricas e KPIs
  • Gestão de inscrições e agendamentos
  • Análise de NPS por produto (UP Marketing, UP Finanças, Decola MEI, Mulheres em Foco)
  • Análise de sentimento via Google Gemini
  • Integração com sistema AoVivo para cursos ao vivo
  • Painel administrativo via Backpack for Laravel

Integrações externas​

  • Google Gemini API: Análise de sentimento de textos - evidência: config/gemini.php:17, app/Http/Controllers/Api/v1/SentimentController.php
  • AoVivo API: Integração para dados de cursos ao vivo - evidência: app/Http/Controllers/Api/v1/AoVivoIntegracaoController.php:44-46
  • Redshift: Data warehouse para consultas analíticas - evidência: config/database.php:86-90
  • AWS S3: Armazenamento de arquivos (quando configurado) - evidência: helm/templates/secret.yaml:35-38

Repos relacionados​

  • Sistema AoVivo (fonte de dados de cursos ao vivo)
  • Backend WordPress (possível integração futura)

Práticas padronizadas no código e UI​

  • Storybook: Documentação e validação visual de componentes React
  • PHPDoc: Contratos, tipos e comentários estruturados em PHP
  • OpenAPI/Swagger: Documentação de API via L5-Swagger - Especificação
  • Mindmap: Visão de componentização/domínio - Documentação

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

Documentação detalhada​

Visão Geral​

API e Dados​

Operação​

Testes​

Decisões e Features​

Pré-Requisitos​

  • PHP >= 8.2
  • Composer - version 2.7.2
  • MySQL - 8.0.32
  • Laravel >= 11.0
  • Node >= 18

Instalação (Desenvolvimento)​

  1. Copie o arquivo .env.example para .env e configure as variáveis de ambiente.

  2. Inicie o docker com o comando: docker compose up

  3. Gere uma nova chave de aplicativo: docker compose exec laravel php artisan key:generate

  4. Limpe o cache de configurações: docker compose exec laravel php artisan config:clear

  5. Execute as migrações: docker compose exec laravel php artisan migrate --seed

  6. Crie um novo usuario via backpack docker compose exec laravel php artisan backpack:user

  7. Acesse a aplicação em: http://localhost:8000.

Swagger​

Para gerar a documentação basta rodar o comando

docker compose exec laravel php artisan l5-swagger:generate

A documentação estará na url http://localhost:8080/api/documentation#/default

Gerar usuário admin​

Para gerar um usuário admin basta executar o comando

php artisan create:admin-user

Testes​

O projeto utiliza duas ferramentas de teste:

  • Pest PHP para testes unitários e funcionais do backend
  • Cypress para testes end-to-end (E2E) da interface administrativa

Testes Backend (Pest PHP)​

# Executar todos os testes com Pest
docker compose exec laravel ./vendor/bin/pest

# Executar via Artisan (compatível com Pest)
docker compose exec laravel php artisan test

# Executar cobertura via Artisan (atualiza pagina HTML em storage/coverage-html)
docker compose exec laravel php artisan test --coverage

# Executar testes específicos
docker compose exec laravel php artisan test --filter="AoVivoControllerTest"

# Executar com cobertura total de app/ (100%)
docker compose exec laravel ./vendor/bin/pest --coverage --min=100 --coverage-filter=app

# Executar apenas testes unitários
docker compose exec laravel ./vendor/bin/pest tests/Unit

# Executar apenas testes de feature
docker compose exec laravel ./vendor/bin/pest tests/Feature

Testes E2E (Cypress)​

Pré-requisitos:

  • Aplicação Laravel rodando em http://localhost:8000
  • Dependências Node instaladas (npm install)
  • Usuário de teste criado no banco de dados
# Abrir Cypress Test Runner (interface gráfica)
npm run cypress:open

# Executar testes em modo headless
npm run cypress:run

Criar usuário de teste:

# Via Tinker
docker compose exec laravel php artisan tinker
# Criar usuário com email e senha conhecidos

Variáveis de ambiente (opcionais):

export CYPRESS_BASE_URL=http://localhost:8000
export CYPRESS_USER_EMAIL=test@example.com
export CYPRESS_USER_PASSWORD=password

Documentação completa dos testes Cypress: docs/tests/cypress.md

Testes Automatizados​

O projeto está configurado para executar testes automaticamente:

CI/CD Pipeline (GitHub Actions):

  • Testes Pest rodam automaticamente em cada push e pull request
  • Jobs de deploy só executam depois dos testes passarem
  • Validação de cobertura mínima com --min=100

Pre-commit Hooks (Opcional):

# Configurar hooks locais para rodar testes antes do commit
./setup-hooks.sh

# Agora os testes rodam automaticamente antes de cada commit
git commit -m "minha alteração"

# Para pular os testes temporariamente (não recomendado)
git commit --no-verify -m "commit sem testes"

Comandos utilitários​

# Menu interativo de testes
./test-runner.sh

# Scripts Composer
composer test
composer test:pest
composer test:coverage

Status dos testes​

  • 143 testes passando
  • 315 assertions validadas
  • 100% de cobertura real em app/ (--coverage-filter=app)

Para detalhes completos, consulte: TESTING.md

Governança automática​

  • GitHub Action obrigatória: .github/workflows/docs-governance.yml (a ser criada).
  • 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 Swagger disponível em: http://localhost:8080/api/documentation#/default (após gerar com php artisan l5-swagger:generate).