Inova — Sistema de Governança de Ideias

MÓDULO DE ENGENHARIA DE SOFTWARE - PANTANAL.DEV Comitiva: Amanda Beatriz, Carlos Braga, Elias Silva e João José

---

📚 Índice da Documentação

Seções Principais:

1. Visão Geral - Introdução ao sistema
2. Status Atual - Funcionalidades implementadas
3. Como a Aplicação Funciona - Fluxo de usuário
4. Arquitetura - Estrutura técnica
5. Módulos - Componentes do sistema
6. Tecnologias - Stack tecnológico
7. Como Executar - Instruções de instalação

Documentação dos Dashboards:

8. Métricas e Indicadores - Explicação das métricas
9. Cálculos de ROI - Fórmulas e exemplos
10. Sistema de Gamificação - Pontuação e ranking
11. Sistema de Desafios - Competições e métricas
12. Métricas de Tempo e Custo - Análise financeira
13. Configuração e Personalização - Como adaptar
14. Troubleshooting - Soluções para problemas
15. Roadmap Futuro - Funcionalidades planejadas

Recursos Técnicos:

16. Apêndice - Estrutura de dados e exemplos
17. Conclusão - Resumo e próximos passos

Visão Geral

O Inova é um sistema web para gerenciar o ciclo de vida de ideias e iniciativas de inovação dentro de uma organização. Ele centraliza a submissão, avaliação, votação, comentários (públicos e privados) e a governança dessas ideias, permitindo que gestores acompanhem e priorizem aquilo que mais gera valor.

Objetivos principais:

• Promover cultura de inovação com um funil unificado de ideias.
• Dar visibilidade a colaboradores e gestores sobre status, pilar, prioridade e impacto.
• Prover governança com regras claras e histórico de decisões/pareceres.

Status Atual da Aplicação ✅

• Banco de Dados: MySQL configurado e funcionando
• Autenticação: JWT via cookies HTTPOnly funcionando
• Votação: Sistema de votos funcionando com validação de status
• Comentários: Comentários públicos e pareceres privados funcionando
• Governança: Interface completa com 7 status disponíveis
• Feed: Exibição pública de ideias funcionando
• Minhas Ideias: Gestão pessoal com visualização de pareceres
• Relatórios: especificações mensais de Engajamento e Impacto documentadas em RELATORIOS.md

Principais áreas da aplicação:

• Feed Público de Ideias: descoberta, votos, comentários públicos
• Minhas Ideias: CRUD para o autor, submissão formal e visualização de pareceres
• Governança: gestão de status, prioridade, pilar e pareceres privados
• Dashboard: métricas e indicadores

Status de Ideias Disponíveis

1. Rascunho (DRAFT): Em preenchimento, apenas o autor pode visualizar
2. Submetida (SUBMITTED): Enviado, visível no feed e pela governança
3. Em Análise (UNDER_REVIEW): Começou avaliação de viabilidade
4. Aprovada (APPROVED): Projeto aceito, vira iniciativa automaticamente
5. Rejeitada (REJECTED): Ideia não foi aceita
6. Arquivada (ARCHIVED): Status final

Status de Iniciativas Disponíveis

1. Planejamento (PLANNING): Iniciativa criada, em fase de planejamento
2. Em Progresso (IN_PROGRESS): Execução iniciada
3. Pausada (ON_HOLD): Temporariamente suspensa
4. Concluída (COMPLETED): Projeto finalizado com sucesso
5. Cancelada (CANCELLED): Projeto cancelado

Nota: Ideias aprovadas criam automaticamente iniciativas via eventos de domínio

Funcionalidades Principais ✅

• 🗳️ Votação: Sistema completo com validação de status
• 💬 Comentários: Públicos (feed) e privados (governança)
• 🔄 Gestão de Status: 8 status com regras de transição
• 🔍 Filtros: Por status e pilar na governança
• 🔒 Segurança: JWT via cookies HTTPOnly
• 📊 Dashboard: Métricas e indicadores
• 📱 Responsivo: Interface adaptada para mobile

---

Como a aplicação funciona (User Journey)

1. Usuário acessa a SPA em http://localhost:8080 (arquivos estáticos em src/main/resources/static).
2. Faz login/registro; recebe JWT e navega entre abas Feed, Minhas Ideias, Governança e Dashboard.
3. No Feed, visualiza ideias públicas, votos e feedbacks públicos. Pode votar se autenticado.
4. Em Minhas Ideias, cria/edita suas ideias e pode submetê-las para avaliação.
5. Em Governança (perfil com role GOVERNANCE), os gestores filtram ideias por status/pilar, atualizam status/prioridade/pilar e adicionam pareceres privados.
6. O Dashboard mostra contadores agregados (total, aprovadas, concluídas, taxa de conversão).

---

Arquitetura e Organização (Monólito Modular + DDD + Clean)

• Monólito Modular: um único artefato de deploy (Spring Boot), organizado por domínios em modules/ (p. ex. ideamanagement, authmanagement, initiativemanagement, reporting).
• DDD (Bounded Contexts): cada módulo possui sua linguagem e regras. Evita vazamentos de regras entre domínios.
• Clean Architecture em cada módulo:
  • domain: entidades, regras e políticas puras
  • application: casos de uso, DTOs, orquestração
  • infrastructure: repositórios/JPA, adaptações externas
  • presentation: controladores REST, validações de entrada
• shared: utilitários cross-cutting (respostas padronizadas, segurança, configs)

Árvore de pastas (resumo):

src/main/java/com/innovation/governance/
├─ GovernanceApplication.java
├─ config/
├─ shared/
│  ├─ api/              # ApiResponse, erros comuns, validações
│  ├─ core/             # AggregateRoot, EventBus (eventos de domínio)
│  └─ security/         # JwtTokenProvider, filtros, SecurityConfig
├─ presentation/        # endpoints cross-cutting (se aplicável)
└─ modules/
    ├─ ideamanagement/
    │  ├─ domain/        # entidades, regras e eventos (puras)
    │  ├─ application/   # use cases, DTOs e portas (interfaces)
    │  ├─ infrastructure/# JPA, mappers, repositórios (implementações)
    │  └─ presentation/  # controllers REST
    ├─ authmanagement/
    │  ├─ domain/ | application/ | infrastructure/ | presentation/
    ├─ initiativemanagement/
    │  ├─ domain/ | application/ | infrastructure/ | presentation/
    ├─ reporting/
    │  ├─ domain/ | application/ | infrastructure/ | presentation/
    ├─ companymanagement/
    │  ├─ domain/ | application/ | infrastructure/ | presentation/
    ├─ gamification/
    │  ├─ domain/ | application/ | infrastructure/ | presentation/
    └─ challenges/
        ├─ domain/ | application/ | infrastructure/ | presentation/

src/main/resources/
├─ application.properties
├─ application-dev.properties
├─ application-h2.properties
├─ application-test.properties
├─ db/
│  └─ migration/
│     ├─ V1__create_users_table.sql
│     ├─ V2__create_companies_table.sql
│     ├─ V2_1__create_user_roles_table.sql
│     ├─ V3__add_company_reference_to_users.sql
│     ├─ V4__create_ideas_table.sql
│     ├─ V5__insert_development_data.sql
│     ├─ V6__create_challenges_tables.sql
│     └─ V7__documentation_comments.sql
└─ static/
    ├─ index.html
    ├─ privacy-policy.html
    ├─ css/
    └─ js/
        ├─ app.js
        ├─ auth.js
        ├─ dashboard.js
        ├─ feed.js
        ├─ governance-modern.js
        ├─ my-ideas.js
        ├─ profile.js
        ├─ ranking.js
        └─ token-refresh.js

src/test/
├─ java/com/innovation/governance/
│  ├─ config/ (GovernanceApplicationTests.java)
│  ├─ modules/
│  ├─ PasswordHashTest.java
│  └─ TestDataInitializer.java
└─ resources/
    └─ static/js/idea-form-validation.test.js

Clean Architecture — explicação prática

• Regra de dependência: camadas externas dependem das internas; nunca o contrário.
• Camadas por módulo:
  • domain: regras e modelos do negócio (puros, sem Spring/JPA). Ex.: Idea, IdeaStatus, eventos de domínio.
  • application: casos de uso e portas (interfaces). Orquestra regras, define interfaces de repositório/serviços externos.
  • infrastructure: adaptações para o mundo externo. Ex.: JPA repositories, mapeadores Entity↔Domain, integrações.
  • presentation: entrada/saída. Ex.: REST controllers, validações sintáticas, Serialização de DTOs.
• Fluxo típico: Controller → UseCase (application) → Repository (interface) → Implementação (infrastructure) → Mapper ↔ Domain.
• Onde colocar cada coisa:
  • Regra de negócio e invariantes: domain (e validações de caso de uso em application).
  • Autorização/validações de entrada: presentation (Bean Validation, sanitização).
  • Persistência, SQL/JPA e integrações: infrastructure (sem regras de negócio).
  • Eventos de domínio: publicados pelo domain/application e propagados via shared/core/EventBus.
• Benefícios: testabilidade (mocks em portas), baixo acoplamento, liberdade para trocar tecnologia (ex.: JPA por outro adapter) sem mudar regras.
• Abordagem “lean” aqui:
  • Monólito modular com limites claros por módulo (bounded contexts), evitando microcamadas desnecessárias.
  • Use cases enxutos injetados nos controllers; nada de "services" duplicados sem responsabilidade.
  • Repositórios em memória onde didático (iniciativas) para simplificar, com caminho de migração para JPA.
  • Mappers explícitos evitam vazar entidades JPA para o domínio.

Aplicação principal: GovernanceApplication (Spring Boot), com scan para modules, shared e config.

Módulos (visão rápida)

• authmanagement: autenticação, usuários, JWT e papéis (roles)
• ideamanagement: ciclo de vida de ideias (entidades, votos, comentários, pareceres, governança)
• initiativemanagement: iniciativas oriundas de ideias aprovadas; métricas de impacto (tempo/custo/público)
• reporting: agregações e DTOs para dashboards/relatórios (engajamento, impacto, estatísticas)
• companymanagement: cadastro e consulta de empresas (onboarding)
• gamification: ranking/score de usuários
• challenges (experimental): desafios/temas de inovação (schema e endpoints iniciais)

---

Tecnologias

• Java 21, Spring Boot 3.5.x
• Spring Web, Spring Data JPA (Hibernate), Validation
• Spring Security + JWT (cookies HTTPOnly), OAuth2 Client (extensível)
• MySQL 8.0 (DEV) com DataInitializer customizado
• Maven (build/test/coverage)
• Frontend SPA com React 18 via UMD + Babel Standalone

Perfis e Banco de Dados

• Perfil ativo padrão: dev (MySQL, Flyway) — ver application-dev.properties
• Perfil prod: MySQL para produção — ver application-prod.properties
• Perfil h2: memória (H2, create-drop) para experimentos — ver application-h2.properties
• Perfil test: H2 para testes automatizados — ver application-test.properties
• Flyway: habilitado para migrações MySQL (migrations em src/main/resources/db/migration/)

Variáveis de ambiente (Windows CMD):

set DB_NAME=governance_dev
set DB_USERNAME=root
set DB_PASSWORD=suasenha
set JWT_SECRET=umaChaveSecretaCom32+Caracteres

Opcional: set SERVER_PORT=8080

---

Módulo de Gestão de Ideias (Idea Management) ✅

Principais DTOs: CreateIdeaDto, IdeaResponseDto, UpdateIdeaStatusDto, StatusOptionDto, etc.

Principais casos de uso (application/usecases):

• CreateIdea, UpdateIdeaStatus, ToggleVoteIdea ✅, CheckUserVote ✅
• AddPublicComment ✅, GetPublicCommentsQuery ✅
• GetAllIdeasQuery ✅, GetIdeaByIdQuery ✅
• AddIdeaFeedback (pareceres privados) ✅

Funcionalidades Implementadas:

• Votação: Sistema completo com validação de status
• Comentários Públicos: Visíveis no feed para todos
• Pareceres Privados: Visíveis apenas para autor e governança
• Gestão de Status: 8 status com regras de transição
• Filtros: Por status e pilar na governança

Principais controladores (presentation/controllers):

• IdeaController (rota base /api/ideas)

  • POST /api/ideas — criar ideia
  • GET /api/ideas — feed público (executeForPublicFeed)
  • GET /api/ideas/{id} — obter ideia por id
  • PATCH /api/ideas/{id}/status — atualizar status
  • POST /api/ideas/{id}/upvote — alternar voto
  • GET /api/ideas/{id}/vote-status — verificar voto do usuário
  • GET /api/ideas/{id}/feedbacks — comentários públicos
  • POST /api/ideas/{id}/feedbacks — adicionar comentário público

• MyIdeasController (rota base /api/my-ideas)

  • GET /api/my-ideas — listar ideias do usuário autenticado
  • PUT /api/my-ideas/{id} — atualizar ideia do autor
  • DELETE /api/my-ideas/{id} — excluir ideia do autor
  • POST /api/my-ideas/{id}/submit — submeter ideia para avaliação

• GovernanceController (rota base /api/governance) ✅

  • GET /api/governance/ideas?status=...&pillar=... — filtrar ideias
  • PUT /api/governance/ideas/{ideaId} — atualizar status/prioridade/pilar
  • POST /api/governance/ideas/{ideaId}/feedback — adicionar parecer privado
  • GET /api/governance/ideas/{ideaId}/feedback — listar pareceres privados
  • GET /api/governance/status-options — listar todos os status disponíveis
  • GET /api/governance/status-transitions/{status} — transições válidas

Resposta padrão: ApiResponse<T> com { success, message, data }.

Módulo de Iniciativas (Initiative Management)

• Criação automática a partir de ideias aprovadas (evento de domínio)
• Guarda métricas de impacto (tempo/custo/público) usadas no relatório de impacto
• Implementação atual do repositório é em memória (propósito didático)

Módulo de Desafios (Challenges)

• Suporte inicial a desafios/temas de inovação
• Tabelas criadas via migration V6__create_challenges_tables.sql

---

Segurança e Autenticação ✅

• JWT via cookies HTTPOnly: Tokens seguros enviados via cookies, não acessíveis via JavaScript
• JwtTokenProvider: Geração e validação de tokens com HS256
• SecurityConfig define rotas públicas e protegidas:
  • Públicas: /api/auth/**, /api/ideas/**, /api/dashboard/**, estáticos
  • Restritas à role GOVERNANCE: /api/governance/**
• Filtro JwtAuthenticationFilter: Carrega usuário do token (header ou cookie)
• CORS habilitado para http://localhost:8080
• Validação de entrada: Sanitização contra log injection e XSS

Autenticação (Auth) ✅

Rotas sob /api/auth/** (liberadas para acesso público no SecurityConfig):

• POST /api/auth/register — registra usuário/empresa
• POST /api/auth/login — autentica e retorna dados do usuário + cookie HTTPOnly
• GET /api/auth/me — dados do usuário autenticado
• POST /api/auth/logout — limpa cookie de autenticação

Perfis e banco:

• Profile ativo: DEV (spring.profiles.active=dev)
• MySQL com schema auto (create-drop) e DataInitializer customizado
• Dados de teste: 3 usuários (admin, gestor, normal) + 3 ideias de exemplo

---

Frontend (SPA) ✅

• React 18 via UMD + Babel Standalone
• Scripts: auth.js, dashboard.js, feed.js, my-ideas.js, governance.js, app.js
• Funcionalidades Implementadas:
  • Feed Público: Visualização, votação e comentários ✅
  • Minhas Ideias: CRUD + visualização de pareceres da governança ✅
  • Governança: Filtros, gestão de status e pareceres privados ✅
  • Autenticação: Login/logout com cookies HTTPOnly ✅
• Estilos: static/css/style.css e static/css/auth.css
  • Marcadores “=== MÓDULO ===” ajudam a navegar por seções (Feed, Comentários, Dashboard, Admin, Perfil, Ranking)
  • Notas de truncamento multiline com line-clamp documentadas em static/css/governance-modern.css

Dashboard

• Controller: DashboardController (módulo reporting), rota base /api/dashboard.
• GET /api/dashboard/stats — retorna estatísticas agregadas (exemplo mockado no controller). Público.

Métricas e Indicadores dos Dashboards

O sistema possui três dashboards principais que fornecem visões diferentes sobre o desempenho das ideias e iniciativas:

1. Dashboard de Estatísticas Gerais (/api/dashboard/stats)

Métricas apresentadas:

• Contadores por Status: Total de ideias, submetidas, aprovadas, concluídas, rejeitadas, em progresso, em análise e arquivadas
• Taxas de Sucesso:
  • Taxa de sucesso = (Ideias concluídas / Total de ideias) × 100
  • Taxa de aprovação = (Ideias aprovadas / Ideias submetidas) × 100
• Engajamento: Total de votos, comentários e médias por ideia

2. Dashboard de Engajamento (/api/dashboard/engagement)

Métricas apresentadas:

• Distribuição por Status: Percentual de ideias em cada status do funil
• Distribuição por Pilar: Percentual de ideias por pilar (Cultura, Ecossistema, P&D, Governança)
• Tendências Temporais: Submissões por mês e evolução temporal
• Top Performers:
  • Top 5 ideias mais votadas
  • Top 5 ideias mais comentadas
  • Ranking de usuários por engajamento

3. Dashboard de Impacto (/api/dashboard/impact)

Métricas apresentadas:

• Alcance: Parceiros externos, público externo e interno impactados
• Economia: Economia de custos e tempo, processos melhorados
• Satisfação: Melhorias na satisfação de funcionários e clientes

Cálculos de ROI (Return on Investment):

Fórmulas Principais:

1. ROI Real (Valor Absoluto):

   ROI Real = Ganhos Totais - Custos de Implementação
   

   Onde: Ganhos Totais = Economia de Custos + Valor da Satisfação

2. ROI Percentual:

   ROI % = (ROI Real / Custos de Implementação) × 100
   

3. Período de Retorno (Payback):

   Payback = Custos de Implementação / (Ganhos Mensais × 12)
   

   Resultado em anos

4. Valor Presente Líquido (NPV):

   NPV = Ganhos Futuros / (1 + Taxa de Desconto)^Período - Custos Iniciais
   

   Taxa de desconto padrão: 10% ao ano

Cálculos Específicos:

• Valor da Satisfação: Estimativa de R$ 1.000/ano por funcionário para cada 1% de melhoria
• Ganhos Totais: Soma da economia de custos + valor monetizado da satisfação
• ROI por Pilar: Média dos ROIs das iniciativas agrupadas por pilar de inovação

Filtros Disponíveis:

• Período: Anual, semestral, trimestral, mensal
• Pilar: Cultura, Ecossistema, P&D, Governança
• Status: Em progresso, concluídas, todas as ativas

Observações Importantes:

• Os cálculos de ROI consideram apenas iniciativas com métricas completas (custos antes/depois e custos de implementação)
• As métricas de satisfação são convertidas em valores monetários para inclusão nos cálculos financeiros
• O sistema calcula automaticamente o melhor pilar em performance baseado no ROI médio
• Todas as métricas são calculadas em tempo real a partir dos dados das iniciativas ativas

Interpretação dos Resultados:

ROI Positivo (> 0%): A iniciativa gera mais valor do que custa

• ROI 100%: Para cada R$ 1,00 investido, retorna R$ 2,00 (dobra o investimento)
• ROI 200%: Para cada R$ 1,00 investido, retorna R$ 3,00 (triplica o investimento)

Payback Period: Tempo para recuperar o investimento

• Payback 1.0 ano: Investimento recuperado em 1 ano
• Payback 0.5 anos: Investimento recuperado em 6 meses

NPV Positivo: Projeto vale mais do que custa considerando o valor do dinheiro no tempo

Exemplos Práticos:

Cenário 1 - Iniciativa de Automação:

• Custo antes: R$ 50.000/mês
• Custo depois: R$ 30.000/mês
• Custo implementação: R$ 100.000
• Economia mensal: R$ 20.000
• ROI: ((20.000 × 12) - 100.000) / 100.000 × 100 = 140%
• Payback: 100.000 / (20.000 × 12) = 0,42 anos (5 meses)

Cenário 2 - Melhoria de Processo:

• Custo implementação: R$ 25.000
• Economia anual: R$ 15.000
• Melhoria satisfação: 5% (equivalente a R$ 5.000/ano)
• Ganhos totais: R$ 20.000/ano
• ROI: (20.000 - 25.000) / 25.000 × 100 = -20% (prejuízo no primeiro ano)
• Payback: 25.000 / (20.000 / 12) = 1,5 anos (recuperação no segundo ano)

Uso dos Dashboards para Tomada de Decisão:

1. Priorização de Ideias: Focar em ideias com maior potencial de ROI
2. Alocação de Recursos: Direcionar investimentos para pilares com melhor performance
3. Monitoramento de Performance: Acompanhar evolução das iniciativas ao longo do tempo
4. Identificação de Oportunidades: Detectar padrões de sucesso para replicação
5. Justificativa de Investimentos: Usar métricas para aprovação de novos projetos

Endpoints da API dos Dashboards:

Dashboard de Estatísticas Gerais:

GET /api/dashboard/stats

• Acesso: Público (não requer autenticação)
• Resposta: Contadores, taxas e métricas de engajamento
• Uso: Visão geral rápida do sistema

Dashboard de Engajamento:

GET /api/dashboard/engagement

• Acesso: Público (não requer autenticação)
• Resposta: Distribuições, tendências e top performers
• Uso: Análise de comportamento e participação dos usuários

Dashboard de Impacto:

GET /api/dashboard/impact
GET /api/dashboard/impact?period=annual&pillar=CULTURA

• Acesso: Público (não requer autenticação)
• Parâmetros de Filtro:
  • period: annual, semester, quarter, month, all
  • pillar: CULTURA, ECOSSISTEMA, P&D, GOVERNANÇA, all
• Resposta: Métricas financeiras, ROI, payback e NPV
• Uso: Análise de retorno financeiro e impacto das iniciativas

Estatísticas do Perfil do Usuário:

GET /api/dashboard/user-profile/{userId}

• Acesso: Usuário autenticado (próprio perfil) ou role GOVERNANCE
• Resposta: Métricas pessoais, pontuação e ranking
• Uso: Acompanhamento individual de performance

Configuração e Personalização:

Filtros Disponíveis no Frontend:

• Período: Seleção de janela temporal para análise
• Pilar: Foco em área específica de inovação
• Status: Filtro por estágio das iniciativas
• Atualização em Tempo Real: Dados são recalculados automaticamente

Exportação de Dados:

• Os dashboards podem ser integrados com ferramentas de BI externas
• Dados disponíveis em formato JSON para análise avançada
• Possibilidade de agendamento de relatórios automáticos

Alertas e Notificações:

• Sistema preparado para alertas de performance abaixo do esperado
• Notificações sobre iniciativas com ROI excepcional
• Acompanhamento de tendências e anomalias

Sistema de Gamificação e Ranking

O sistema inclui um módulo completo de gamificação que incentiva a participação e reconhece o desempenho dos usuários:

Sistema de Pontuação:

Pontos por Atividade:

• Ideia Aprovada: +10 pontos
• Ideia em Progresso: +15 pontos
• Ideia Concluída: +20 pontos
• Vitória em Desafio: +25 pontos
• Impacto de Público: +1 ponto por pessoa impactada
• Economia Gerada: +0.1 ponto por R$ 1,00 economizado
• Tempo Economizado: +0.05 pontos por hora economizada

Cálculo da Pontuação Total:

Pontuação Total = Pontos por Ideias + Pontos por Desafios + Pontos por Impacto + Pontos por Economia

Níveis e Tiers:

Classificação por Pontuação:

• Novato: 0-9 pontos
• Iniciante: 10-24 pontos
• Intermediário: 25-49 pontos
• Especialista: 50-99 pontos
• Líder: 100+ pontos

Ranking e Competição:

Endpoint do Ranking:

GET /api/ranking

• Acesso: Público (não requer autenticação)
• Resposta: Top 10 usuários com maior pontuação
• Atualização: Automática a cada 30 segundos
• Ordenação: Por pontuação total decrescente

Métricas do Ranking:

• Posição no ranking geral
• Total de pontos acumulados
• Contagem de ideias por status
• Público impactado (interno e externo)
• Economia gerada (tempo e dinheiro)
• Vitórias em desafios

Integração com Dashboards:

Estatísticas Pessoais:

• Endpoint: GET /api/dashboard/user-profile/{userId}
• Métricas: Performance individual, taxas de aprovação, ranking pessoal
• Uso: Acompanhamento de evolução pessoal e comparação com outros usuários

Impacto no Sistema:

• Usuários com maior pontuação têm maior visibilidade
• Sistema de badges e reconhecimento automático
• Integração com desafios e competições
• Histórico completo de contribuições e conquistas

Benefícios da Gamificação:

1. Engajamento: Sistema de pontos motiva participação contínua
2. Reconhecimento: Ranking público destaca melhores contribuidores
3. Competição Saudável: Comparação de performance entre usuários
4. Desenvolvimento: Níveis mostram progresso e evolução
5. Impacto Mensurável: Pontuação reflete valor real gerado para a organização

Sistema de Desafios e Competições

O sistema inclui um módulo de desafios que promove inovação através de competições temáticas:

Funcionalidades dos Desafios:

Criação de Desafios:

• Acesso: Apenas usuários com role GOVERNANCE
• Endpoint: POST /api/challenges
• Campos: Título, descrição, prazo, recompensa em pontos
• Status: Ativo/Inativo, com controle de período

Submissão de Soluções:

• Acesso: Usuários autenticados
• Endpoint: POST /api/challenges/{id}/submit
• Campos: Título da solução, descrição detalhada, arquivos anexos
• Validação: Verificação de prazo e status do desafio

Seleção de Vencedores:

• Acesso: Apenas usuários com role GOVERNANCE
• Endpoint: POST /api/challenges/submissions/{id}/winner
• Processo: Avaliação das submissões e definição do vencedor
• Recompensa: 25 pontos automaticamente adicionados ao vencedor

Endpoints dos Desafios:

Consulta Pública:

GET /api/challenges/active          # Desafio ativo mais recente
GET /api/challenges                 # Lista de desafios ativos

Gestão (GOVERNANCE):

POST /api/challenges                # Criar novo desafio
GET /api/challenges/{id}/submissions # Ver submissões de um desafio
POST /api/challenges/submissions/{id}/winner # Definir vencedor

Participação (USER):

POST /api/challenges/{id}/submit    # Submeter solução

Integração com Dashboards:

Métricas de Desafios:

• Contagem de desafios ativos e concluídos
• Taxa de participação por desafio
• Performance dos vencedores
• Impacto na pontuação geral dos usuários

Relatórios Específicos:

• Top usuários por vitórias em desafios
• Distribuição de soluções por tipo de desafio
• Evolução da participação ao longo do tempo
• ROI dos desafios em termos de engajamento

Fluxo de Negócio:

1. Criação: Governança define tema, prazo e recompensa
2. Divulgação: Sistema notifica usuários sobre novo desafio
3. Participação: Usuários submetem soluções durante período ativo
4. Avaliação: Governança analisa submissões e define vencedor
5. Recompensa: Sistema atualiza pontuação automaticamente
6. Análise: Métricas são incorporadas aos dashboards de engajamento

Benefícios dos Desafios:

1. Inovação Direcionada: Foco em temas específicos da organização
2. Engajamento Temporário: Competições com prazo definido
3. Reconhecimento Especial: Vitórias geram pontos extras
4. Colaboração: Usuários trabalham em soluções para problemas reais
5. Métricas de Sucesso: Medição do impacto das competições

Métricas de Tempo e Custo

O sistema captura e analisa métricas detalhadas de tempo e custo para fornecer uma visão completa do impacto das iniciativas:

Métricas de Tempo:

Processamento Antes vs. Depois:

• Campo: processTimeBeforeHours e processTimeAfterHours
• Unidade: Horas por processo
• Cálculo: Economia de tempo = Tempo antes - Tempo depois
• Exemplo: Processo que levava 8 horas agora leva 2 horas = Economia de 6 horas

Análise de Produtividade:

• Processos Melhorados: Contagem de iniciativas com redução de tempo
• Média de Economia: Tempo total economizado / Número de iniciativas
• Impacto Mensal: Economia de tempo por período

Métricas de Custo:

Custos Operacionais:

• Campo: costBefore e costAfter
• Unidade: Reais (R$) por período
• Cálculo: Economia de custos = Custo antes - Custo depois
• Exemplo: Processo que custava R$ 5.000/mês agora custa R$ 2.000/mês = Economia de R$ 3.000/mês

Custos de Implementação:

• Campo: implementationCost
• Unidade: Reais (R$) totais
• Uso: Base para cálculos de ROI e payback
• Inclusão: Desenvolvimento, treinamento, infraestrutura

Custos de Manutenção:

• Campo: maintenanceCost
• Unidade: Reais (R$) por ano
• Uso: Cálculo de custo total de propriedade (TCO)
• Consideração: Custos recorrentes após implementação

Cálculos Integrados:

ROI Baseado em Tempo:

Valor do Tempo = Horas Economizadas × Valor Hora Interna
ROI Tempo = (Valor do Tempo - Custos de Implementação) / Custos de Implementação × 100

ROI Baseado em Custo:

ROI Custo = (Economia Anual - Custos de Implementação) / Custos de Implementação × 100

ROI Combinado:

ROI Total = (Economia Total - Custos Totais) / Custos Totais × 100
Onde: Economia Total = Economia de Custos + Valor do Tempo + Valor da Satisfação

Métricas de Satisfação:

Melhorias de Satisfação:

• Funcionários: employeeSatisfactionImprovement (0-100%)
• Clientes: customerSatisfactionImprovement (0-100%)
• Valor Monetário: R$ 1.000/ano por 1% de melhoria
• Inclusão: Incorporado nos cálculos de ROI

Cálculo do Valor da Satisfação:

Valor Satisfação = (Melhoria Funcionários + Melhoria Clientes) × R$ 1.000

Análise por Pilar:

Distribuição de Economias:

• Por Pilar: Agrupamento de iniciativas por área de inovação
• Métricas: Economia total, ROI médio, número de iniciativas
• Identificação: Melhor pilar em performance financeira

Top Iniciativas por Pilar:

• Maior Economia: Iniciativas com maior redução de custos
• Maior Impacto: Iniciativas com maior número de pessoas impactadas
• Melhor ROI: Iniciativas com maior retorno sobre investimento

Relatórios Temporais:

Evolução Mensal:

• Economias: Acumulado de economias por mês
• Impacto: Número de pessoas impactadas por período
• Tendências: Identificação de padrões sazonais

Projeções:

• Payback: Tempo para recuperar investimento
• NPV: Valor presente líquido considerando inflação
• Cenários: Análise de diferentes cenários de implementação

Uso das Métricas:

1. Justificativa de Investimentos: ROI e payback para aprovação de projetos
2. Priorização: Foco em iniciativas com maior impacto financeiro
3. Alocação de Recursos: Direcionamento para pilares mais rentáveis
4. Monitoramento: Acompanhamento de performance ao longo do tempo
5. Comunicação: Relatórios executivos com métricas claras e objetivas

Configuração e Personalização dos Dashboards

Arquivos de Configuração:

Frontend (JavaScript):

• src/main/resources/static/js/dashboard.js - Lógica principal dos dashboards
• src/main/resources/static/css/dashboard.css - Estilos do dashboard principal
• src/main/resources/static/css/impact-dashboard.css - Estilos específicos de impacto
• src/main/resources/static/css/engagement-dashboard.css - Estilos de engajamento

Backend (Java):

• src/main/java/com/innovation/governance/modules/reporting/ - Módulo de relatórios
• DashboardController.java - Endpoints da API
• GetImpactMetrics.java - Cálculos de ROI e métricas financeiras
• GetEngagementMetrics.java - Métricas de engajamento e participação

Personalização de Métricas:

Adicionar Novas Métricas:

1. DTO: Criar novo campo em ImpactMetricsDto ou EngagementMetricsDto
2. Use Case: Implementar cálculo no caso de uso correspondente
3. Controller: Expor novo campo via API
4. Frontend: Adicionar visualização no dashboard

Exemplo de Nova Métrica:

// Em ImpactMetricsDto
public record ImpactMetricsDto(
    // ... campos existentes ...
    Double newMetric, // Nova métrica
    // ... outros campos ...
) {}

// Em GetImpactMetrics.java
Double newMetric = calculateNewMetric(initiatives);
return new ImpactMetricsDto(..., newMetric, ...);

Configuração de Filtros:

Filtros Disponíveis:

• Período: annual, semester, quarter, month, all
• Pilar: CULTURA, ECOSSISTEMA, P&D, GOVERNANÇA, all
• Status: IN_PROGRESS, COMPLETED, all

Adicionar Novo Filtro:

// Em GetImpactMetrics.java
public ImpactMetricsDto execute(String period, String pillar, String newFilter) {
    // Aplicar novo filtro
    List<Initiative> filtered = applyNewFilter(initiatives, newFilter);
    // ... resto da lógica
}

// Em DashboardController.java
@GetMapping("/impact")
public ResponseEntity<ApiResponse<ImpactMetricsDto>> getImpactMetrics(
    @RequestParam(required = false) String period,
    @RequestParam(required = false) String pillar,
    @RequestParam(required = false) String newFilter) {
    // ... implementação
}

Configuração de Gráficos:

Biblioteca de Gráficos:

• Chart.js: Gráficos responsivos e interativos
• Tipos Suportados: Barras, linha, pizza, radar, área
• Personalização: Cores, estilos, animações, tooltips

Adicionar Novo Gráfico:

// Em dashboard.js
const createNewChart = () => {
    const ctx = document.getElementById('newChart');
    if (ctx) {
        const chart = new Chart(ctx, {
            type: 'bar', // ou 'line', 'pie', etc.
            data: {
                labels: ['Label 1', 'Label 2'],
                datasets: [{
                    label: 'Nova Métrica',
                    data: [value1, value2],
                    backgroundColor: 'rgba(59, 130, 246, 0.2)',
                    borderColor: 'rgba(59, 130, 246, 1)'
                }]
            },
            options: {
                responsive: true,
                plugins: {
                    title: { display: true, text: 'Título do Gráfico' }
                }
            }
        });
    }
};

Configuração de Alertas:

Sistema de Notificações:

• Performance: Alertas para métricas abaixo do esperado
• ROI: Notificações para iniciativas com retorno excepcional
• Engajamento: Alertas para queda na participação

Configuração de Thresholds:

// Em GetImpactMetrics.java
private void checkAlertThresholds(ImpactMetricsDto metrics) {
    if (metrics.roiPercentage() < 50.0) {
        // Disparar alerta de ROI baixo
        alertService.sendLowRoiAlert(metrics);
    }
    
    if (metrics.totalCostSavings() < 10000.0) {
        // Disparar alerta de economia baixa
        alertService.sendLowSavingsAlert(metrics);
    }
}

Exportação e Integração:

Formatos de Exportação:

• JSON: Para integração com ferramentas externas
• CSV: Para análise em Excel ou BI
• PDF: Para relatórios executivos

Integração com BI:

• Power BI: Conectores para APIs REST
• Tableau: Extração de dados via endpoints
• Qlik: Integração com base de dados MySQL

Configuração de Agendamento:

// Em DashboardController.java
@Scheduled(cron = "0 0 9 * * MON") // Toda segunda às 9h
@GetMapping("/weekly-report")
public ResponseEntity<ApiResponse<WeeklyReportDto>> getWeeklyReport() {
    // Gerar relatório semanal
    WeeklyReportDto report = generateWeeklyReport();
    return ResponseEntity.ok(ApiResponse.success("Relatório semanal gerado", report));
}

Monitoramento e Performance:

Métricas de Performance:

• Tempo de Resposta: < 2 segundos para dashboards
• Cache: Dados em memória para consultas frequentes
• Índices: Otimização de consultas MySQL

Configuração de Cache:

// Em GetImpactMetrics.java
@Cacheable("impact-metrics")
public ImpactMetricsDto execute(String period, String pillar) {
    // ... implementação com cache automático
}

// Em application.properties
spring.cache.type=caffeine
spring.cache.cache-names=impact-metrics,engagement-metrics
spring.cache.caffeine.spec=maximumSize=100,expireAfterWrite=5m

Segurança e Acesso:

Controle de Acesso:

• Dashboards Públicos: Estatísticas gerais e engajamento
• Dashboards Protegidos: Impacto detalhado e perfil do usuário
• Role-based Access: GOVERNANCE para métricas avançadas

Configuração de Segurança:

// Em SecurityConfig.java
.antMatchers("/api/dashboard/stats", "/api/dashboard/engagement").permitAll()
.antMatchers("/api/dashboard/impact", "/api/dashboard/user/**").authenticated()
.antMatchers("/api/dashboard/admin/**").hasRole("GOVERNANCE")

Troubleshooting e Problemas Comuns

Problemas de Performance:

Dashboard Lento:

• Sintoma: Carregamento demorado (> 5 segundos)
• Causa: Consultas complexas ou falta de índices
• Solução:

  -- Adicionar índices para consultas frequentes
  CREATE INDEX idx_ideas_status ON ideas(status);
  CREATE INDEX idx_ideas_pillar ON ideas(pillar);
  CREATE INDEX idx_initiatives_status ON initiatives(status);
  CREATE INDEX idx_user_scores_points ON user_scores(total_points DESC);

Métricas Não Atualizadas:

• Sintoma: Dados desatualizados ou incorretos
• Causa: Cache expirado ou dados inconsistentes
• Solução:

  // Limpar cache manualmente
  @CacheEvict("impact-metrics")
  public void refreshMetrics() {
      // Forçar recálculo
  }

Problemas de Cálculo:

ROI Incorreto:

• Sintoma: Valores de ROI inconsistentes ou negativos
• Causa: Dados de custo ou economia incorretos
• Solução:

  // Validar dados antes do cálculo
  private void validateMetrics(Initiative initiative) {
      if (initiative.getImplementationCost() <= 0) {
          throw new IllegalArgumentException("Custo de implementação deve ser positivo");
      }
      if (initiative.getCostBefore() <= initiative.getCostAfter()) {
          throw new IllegalArgumentException("Custo antes deve ser maior que custo depois");
      }
  }

Divisão por Zero:

• Sintoma: Erro de cálculo ou valores infinitos
• Causa: Denominador zero em cálculos de taxa
• Solução:

  // Proteção contra divisão por zero
  Double successRate = totalIdeas > 0 ? 
      (completedIdeas.doubleValue() / totalIdeas.doubleValue()) * 100 : 0.0;

Problemas de Interface:

Gráficos Não Carregam:

• Sintoma: Área de gráfico vazia ou erro no console
• Causa: Chart.js não carregado ou dados inválidos
• Solução:

  // Verificar se Chart.js está disponível
  if (typeof Chart === 'undefined') {
      console.error('Chart.js não carregado');
      return;
  }
  
  // Validar dados antes de criar gráfico
  if (!data || data.length === 0) {
      console.warn('Dados vazios para gráfico');
      return;
  }

Filtros Não Funcionam:

• Sintoma: Seleção de filtros não atualiza dados
• Causa: Eventos não disparados ou API não chamada
• Solução:

  // Verificar se filtros estão funcionando
  const handleFilterChange = (filterType, value) => {
      console.log('Filtro alterado:', filterType, value);
      setSelectedFilters(prev => ({ ...prev, [filterType]: value }));
      fetchMetrics(); // Forçar atualização
  };

Problemas de API:

Endpoints Não Respondem:

• Sintoma: Erro 404 ou timeout nas requisições
• Causa: Rotas não mapeadas ou controller não registrado
• Solução:

  // Verificar se controller está sendo escaneado
  @ComponentScan(basePackages = "com.innovation.governance.modules.reporting")
  @SpringBootApplication
  public class GovernanceApplication {
      // ...
  }

Erro de CORS:

• Sintoma: Requisições bloqueadas pelo navegador
• Causa: Configuração de CORS incorreta
• Solução:

  // Em SecurityConfig.java
  @Bean
  public CorsConfigurationSource corsConfigurationSource() {
      CorsConfiguration configuration = new CorsConfiguration();
      configuration.setAllowedOrigins(Arrays.asList("http://localhost:8080"));
      configuration.setAllowedMethods(Arrays.asList("GET", "POST", "PUT", "DELETE"));
      configuration.setAllowedHeaders(Arrays.asList("*"));
      
      UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
      source.registerCorsConfiguration("/**", configuration);
      return source;
  }

Problemas de Banco de Dados:

Dados Inconsistentes:

• Sintoma: Métricas que não fazem sentido
• Causa: Dados corrompidos ou transações incompletas
• Solução:

  -- Verificar integridade dos dados
  SELECT COUNT(*) as total_ideas FROM ideas;
  SELECT COUNT(*) as total_initiatives FROM initiatives;
  SELECT COUNT(*) as total_scores FROM user_scores;
  
  -- Verificar relacionamentos
  SELECT i.id, i.title, i.status 
  FROM ideas i 
  LEFT JOIN initiatives init ON i.id = init.idea_id 
  WHERE init.id IS NULL AND i.status = 'APPROVED';

Problemas de Conectividade:

• Sintoma: Erro de conexão com banco
• Causa: Pool de conexões esgotado ou timeout
• Solução:

  # Em application.properties
  spring.datasource.hikari.maximum-pool-size=20
  spring.datasource.hikari.connection-timeout=30000
  spring.datasource.hikari.idle-timeout=600000
  spring.datasource.hikari.max-lifetime=1800000

Logs e Debugging:

Habilitar Logs Detalhados:

# Em application.properties
logging.level.com.innovation.governance.modules.reporting=DEBUG
logging.level.org.springframework.web=DEBUG
logging.level.org.hibernate.SQL=DEBUG
logging.level.org.hibernate.type.descriptor.sql.BasicBinder=TRACE

Monitoramento de Performance:

// Em GetImpactMetrics.java
@Slf4j
public class GetImpactMetrics {
    
    public ImpactMetricsDto execute(String period, String pillar) {
        long startTime = System.currentTimeMillis();
        
        try {
            // ... implementação ...
            
            long executionTime = System.currentTimeMillis() - startTime;
            log.info("Métricas de impacto calculadas em {}ms", executionTime);
            
            return result;
        } catch (Exception e) {
            log.error("Erro ao calcular métricas de impacto", e);
            throw e;
        }
    }
}

Checklist de Verificação:

Antes de Reportar Problema:

1. ✅ Verificar logs da aplicação
2. ✅ Confirmar dados no banco de dados
3. ✅ Testar endpoint diretamente (Postman/curl)
4. ✅ Verificar console do navegador
5. ✅ Confirmar versão da aplicação
6. ✅ Verificar configurações de ambiente

Informações para Suporte:

• Versão da aplicação
• Logs de erro completos
• Dados de exemplo que causam problema
• Passos para reproduzir
• Configurações de ambiente
• Screenshots da interface (se aplicável)

Roadmap e Melhorias Futuras

Próximas Funcionalidades dos Dashboards:

Dashboard Executivo Avançado:

• KPIs Personalizáveis: Métricas customizáveis por usuário/role
• Alertas Inteligentes: Machine learning para detectar anomalias
• Relatórios Automáticos: Agendamento e distribuição automática
• Exportação Avançada: PDF, Excel, PowerPoint com templates

Análise Preditiva:

• Tendências Futuras: Projeções baseadas em dados históricos
• ROI Forecasting: Estimativas de retorno para novas iniciativas
• Análise de Riscos: Identificação de fatores de risco
• Cenários "What-If": Simulação de diferentes estratégias

Integração Avançada:

• APIs Externas: Conexão com sistemas ERP, CRM, BI
• Webhooks: Notificações em tempo real para sistemas externos
• SSO Corporativo: Integração com Active Directory, LDAP
• Mobile App: Aplicativo nativo para iOS e Android

Melhorias de Performance:

Cache Inteligente:

• Redis: Cache distribuído para alta disponibilidade
• Cache por Usuário: Dados personalizados em cache
• Invalidação Inteligente: Cache atualizado automaticamente
• Compressão: Redução de tamanho de dados transferidos

Otimização de Banco:

• Índices Avançados: Otimização automática de consultas
• Partitioning: Divisão de tabelas grandes por período
• Read Replicas: Separação de leitura e escrita
• Connection Pooling: Gerenciamento avançado de conexões

Monitoramento em Tempo Real:

• Métricas de Sistema: CPU, memória, disco, rede
• APM: Application Performance Monitoring
• Alertas Proativos: Notificações antes de problemas
• Dashboards de Infraestrutura: Saúde do sistema

Funcionalidades de Gamificação Avançada:

Sistema de Conquistas:

• Badges Dinâmicos: Conquistas baseadas em métricas
• Níveis Avançados: Sistema de evolução mais complexo
• Competições em Equipe: Rankings por departamento/equipe
• Recompensas Reais: Integração com sistemas de benefícios

Análise de Comportamento:

• Padrões de Uso: Identificação de usuários ativos
• Segmentação: Agrupamento por comportamento
• Recomendações: Sugestões personalizadas de ações
• Engajamento Predictivo: Identificação de usuários em risco de abandono

Inteligência Artificial e Machine Learning:

Análise de Sentimento:

• Comentários: Análise automática de feedback
• Tendências: Identificação de temas emergentes
• Satisfação: Medição automática de satisfação
• Insights: Descoberta automática de insights

Otimização Automática:

• ROI Prediction: Estimativas automáticas de retorno
• Resource Allocation: Sugestões de alocação de recursos
• Risk Assessment: Avaliação automática de riscos
• Performance Tuning: Otimização automática de parâmetros

Chatbot Inteligente:

• Suporte Automático: Respostas a perguntas frequentes
• Análise de Dados: Consultas em linguagem natural
• Recomendações: Sugestões baseadas em contexto
• Integração: Conexão com sistemas de suporte

Melhorias de UX/UI:

Interface Adaptativa:

• Responsivo Avançado: Adaptação automática a dispositivos
• Temas Personalizáveis: Cores e estilos customizáveis
• Modo Escuro: Interface adaptável à preferência do usuário
• Acessibilidade: Suporte completo a WCAG 2.1

Interatividade Avançada:

• Drag & Drop: Reorganização de dashboards
• Zoom e Pan: Navegação avançada em gráficos
• Filtros Visuais: Seleção visual de parâmetros
• Animações: Transições suaves e feedback visual

Personalização:

• Dashboards Customizáveis: Layout personalizado por usuário
• Widgets: Componentes reutilizáveis e configuráveis
• Templates: Modelos pré-definidos para diferentes perfis
• Favoritos: Métricas e gráficos favoritos do usuário

Integração com Ecossistema:

Ferramentas de BI:

• Power BI: Conectores nativos e templates
• Tableau: Integração via APIs e webhooks
• Qlik: Conexão direta com base de dados
• Looker: Modelos de dados compartilhados

Sistemas Corporativos:

• ERP: Integração com SAP, Oracle, Microsoft Dynamics
• CRM: Conexão com Salesforce, HubSpot, Pipedrive
• HR: Integração com sistemas de recursos humanos
• Financeiro: Conexão com sistemas contábeis

Ferramentas de Produtividade:

• Slack: Notificações e integração com canais
• Microsoft Teams: Tabs e bots integrados
• Email: Relatórios automáticos por email
• Calendário: Agendamento de reuniões de revisão

Segurança e Compliance:

Auditoria Avançada:

• Logs Detalhados: Rastreamento completo de ações
• Compliance: Conformidade com regulamentações
• Backup Automático: Cópia de segurança automática
• Recovery: Recuperação rápida de desastres

Segurança Reforçada:

• 2FA: Autenticação de dois fatores
• SSO: Single Sign-On corporativo
• Encryption: Criptografia em repouso e trânsito
• Vulnerability Scanning: Verificação automática de vulnerabilidades

Timeline de Implementação:

Fase 1 (3 meses):

• Cache Redis e otimizações de performance
• Sistema de alertas inteligentes
• Melhorias de UX/UI básicas

Fase 2 (6 meses):

• Análise preditiva básica
• Sistema de conquistas avançado
• Integração com ferramentas de BI

Fase 3 (12 meses):

• Machine learning para insights
• Chatbot inteligente
• Integração com sistemas corporativos

Fase 4 (18 meses):

• IA avançada para otimização
• Análise de comportamento
• Plataforma de extensibilidade

Contribuição e Feedback:

Como Contribuir:

• Issues: Reportar bugs e sugerir melhorias
• Pull Requests: Contribuir com código
• Documentação: Melhorar esta documentação
• Testes: Reportar problemas encontrados

Canais de Comunicação:

• GitHub Issues: Para bugs e feature requests
• Discord/Slack: Para discussões da comunidade
• Email: Para suporte técnico
• Documentação: Para guias e tutoriais

Padrões de Contribuição:

• Código: Seguir padrões de codificação estabelecidos
• Testes: Incluir testes para novas funcionalidades
• Documentação: Atualizar documentação relacionada
• Review: Passar por code review antes do merge

---

Resumo da Documentação dos Dashboards

O que foi Documentado:

✅ Métricas e Indicadores: Explicação detalhada de todos os KPIs apresentados ✅ Cálculos de ROI: Fórmulas completas com exemplos práticos ✅ Sistema de Gamificação: Pontuação, ranking e níveis dos usuários ✅ Sistema de Desafios: Competições e métricas de participação ✅ Métricas de Tempo e Custo: Análise financeira e de produtividade ✅ Configuração e Personalização: Como adaptar e estender os dashboards ✅ Troubleshooting: Soluções para problemas comuns ✅ Roadmap Futuro: Funcionalidades planejadas e melhorias

Principais Dashboards Disponíveis:

1. 📊 Dashboard de Estatísticas Gerais (/api/dashboard/stats)

   • Contadores por status, taxas de sucesso e engajamento

2. 🎯 Dashboard de Engajamento (/api/dashboard/engagement)

   • Distribuições, tendências e top performers

3. 💰 Dashboard de Impacto (/api/dashboard/impact)

   • ROI, payback, NPV e métricas financeiras

4. 👤 Estatísticas Pessoais (/api/dashboard/user-profile/{userId})

   • Performance individual e ranking pessoal

Métricas de ROI Documentadas:

• ROI Real: (Ganhos - Custos) / Custos × 100
• Payback Period: Tempo para recuperar investimento
• NPV: Valor presente líquido com taxa de desconto
• Valor da Satisfação: Monetização de melhorias de satisfação
• ROI por Pilar: Performance financeira por área de inovação

Sistema de Gamificação:

• Pontuação: 10-20 pontos por ideia (aprovada, em progresso, concluída)
• Níveis: Novato → Iniciante → Intermediário → Especialista → Líder
• Ranking: Top 10 usuários com atualização automática
• Desafios: +25 pontos por vitória em competições

Como Usar Esta Documentação:

1. Para Desenvolvedores: Seções de configuração e troubleshooting
2. Para Usuários Finais: Explicação das métricas e interpretação
3. Para Gestores: Fórmulas de ROI e uso para tomada de decisão
4. Para Administradores: Configuração de segurança e performance

Próximos Passos Recomendados:

1. Implementar Cache: Adicionar Redis para melhor performance
2. Sistema de Alertas: Configurar notificações automáticas
3. Exportação de Dados: Implementar relatórios em PDF/Excel
4. Integração BI: Conectar com ferramentas como Power BI
5. Mobile App: Desenvolver aplicativo para dispositivos móveis

Suporte e Contato:

• Documentação: Este README e arquivos relacionados
• Código: Repositório GitHub com exemplos implementados
• Issues: GitHub Issues para bugs e melhorias
• Comunidade: Discussões e suporte da equipe

---

📚 Esta documentação é um recurso vivo e será atualizada conforme o sistema evolui. Para sugestões de melhoria ou correções, abra uma issue no repositório.

Apêndice: Estrutura de Dados e Exemplos

Estrutura das Tabelas de Métricas:

Tabela initiatives (Métricas de Impacto):

CREATE TABLE initiatives (
    id VARCHAR(36) PRIMARY KEY,
    idea_id VARCHAR(36) NOT NULL,
    status VARCHAR(20) NOT NULL,
    pillar VARCHAR(50),
    
    -- Métricas de Tempo
    process_time_before_hours INTEGER,
    process_time_after_hours INTEGER,
    
    -- Métricas de Custo
    cost_before DECIMAL(15,2),
    cost_after DECIMAL(15,2),
    implementation_cost DECIMAL(15,2),
    maintenance_cost DECIMAL(15,2),
    
    -- Métricas de Público
    external_partners TEXT,
    external_public INTEGER,
    internal_public INTEGER,
    
    -- Métricas de Satisfação
    employee_satisfaction_improvement DECIMAL(5,2),
    customer_satisfaction_improvement DECIMAL(5,2),
    
    -- Metadados
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    
    FOREIGN KEY (idea_id) REFERENCES ideas(id)
);

Tabela user_scores (Gamificação):

CREATE TABLE user_scores (
    user_id VARCHAR(36) PRIMARY KEY,
    total_points INTEGER DEFAULT 0,
    
    -- Contadores de Ideias
    approved_ideas INTEGER DEFAULT 0,
    in_progress_ideas INTEGER DEFAULT 0,
    completed_ideas INTEGER DEFAULT 0,
    
    -- Métricas de Impacto
    external_audience_count INTEGER DEFAULT 0,
    internal_audience_count INTEGER DEFAULT 0,
    hours_improved DECIMAL(10,2) DEFAULT 0.0,
    money_saved DECIMAL(15,2) DEFAULT 0.0,
    
    -- Desafios
    challenge_wins INTEGER DEFAULT 0,
    
    -- Metadados
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    
    FOREIGN KEY (user_id) REFERENCES users(id)
);

Exemplos de Dados de Métricas:

Iniciativa de Automação:

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "idea_id": "550e8400-e29b-41d4-a716-446655440010",
  "status": "COMPLETED",
  "pillar": "P&D",
  
  "process_time_before_hours": 40,
  "process_time_after_hours": 8,
  
  "cost_before": 5000.00,
  "cost_after": 2000.00,
  "implementation_cost": 15000.00,
  "maintenance_cost": 500.00,
  
  "external_partners": "Empresa A, Empresa B",
  "external_public": 100,
  "internal_public": 25,
  
  "employee_satisfaction_improvement": 15.5,
  "customer_satisfaction_improvement": 8.2
}

Cálculo de ROI para esta Iniciativa:

Economia de Tempo: 40 - 8 = 32 horas/mês
Economia de Custo: 5000 - 2000 = R$ 3.000/mês
Economia Anual: R$ 36.000

Valor da Satisfação: (15.5 + 8.2) × R$ 1.000 = R$ 23.700/ano
Ganhos Totais: R$ 36.000 + R$ 23.700 = R$ 59.700/ano

ROI Real: R$ 59.700 - R$ 15.000 = R$ 44.700
ROI %: (R$ 44.700 / R$ 15.000) × 100 = 298%

Payback: R$ 15.000 / (R$ 59.700 / 12) = 3.0 meses

Exemplos de Respostas da API:

Dashboard de Estatísticas (/api/dashboard/stats):

{
  "success": true,
  "message": "Estatísticas carregadas com sucesso",
  "data": {
    "totalIdeas": 150,
    "submittedIdeas": 45,
    "approvedIdeas": 28,
    "completedIdeas": 15,
    "rejectedIdeas": 8,
    "inProgressIdeas": 13,
    "underReviewIdeas": 4,
    "archivedIdeas": 37,
    "successRate": 10.0,
    "approvalRate": 62.2,
    "totalVotes": 342,
    "totalComments": 89,
    "averageVotesPerIdea": 2,
    "averageCommentsPerIdea": 1
  }
}

Dashboard de Impacto (/api/dashboard/impact):

{
  "success": true,
  "message": "Métricas de impacto carregadas com sucesso",
  "data": {
    "externalPartners": 12,
    "externalPublic": 1250,
    "internalPublic": 89,
    "totalCostSavings": 125000.00,
    "totalTimeSavings": 480.5,
    "processesImproved": 8,
    "totalImplementationCost": 45000.00,
    "totalMaintenanceCost": 2500.00,
    "averageEmployeeSatisfactionImprovement": 12.3,
    "averageCustomerSatisfactionImprovement": 7.8,
    "realRoi": 80000.00,
    "roiPercentage": 177.8,
    "paybackPeriod": 0.4,
    "netPresentValue": 75000.00,
    "savingsByMonth": {
      "Jan": 0.0, "Fev": 0.0, "Mar": 15000.0,
      "Abr": 18000.0, "Mai": 22000.0, "Jun": 25000.0,
      "Jul": 28000.0, "Ago": 30000.0
    },
    "savingsByPillar": {
      "CULTURA": 25000.0,
      "ECOSSISTEMA": 35000.0,
      "P&D": 45000.0,
      "GOVERNANÇA": 20000.0
    },
    "roiByPillar": {
      "CULTURA": 125.0,
      "ECOSSISTEMA": 175.0,
      "P&D": 225.0,
      "GOVERNANÇA": 100.0
    },
    "bestPerformingPillar": "P&D",
    "averageSavingsPerInitiative": 15625.00
  }
}

Ranking de Usuários (/api/ranking):

{
  "success": true,
  "message": "Ranking obtido com sucesso",
  "data": [
    {
      "position": 1,
      "userId": "550e8400-e29b-41d4-a716-446655440009",
      "userName": "João Pedro Oliveira",
      "totalPoints": 185,
      "approvedIdeas": 3,
      "inProgressIdeas": 2,
      "completedIdeas": 1,
      "externalAudienceCount": 150,
      "internalAudienceCount": 25,
      "hoursImproved": 120.5,
      "moneySaved": 45000.00,
      "challengeWins": 2
    },
    {
      "position": 2,
      "userId": "550e8400-e29b-41d4-a716-446655440010",
      "userName": "Carlos Lima",
      "totalPoints": 142,
      "approvedIdeas": 2,
      "inProgressIdeas": 1,
      "completedIdeas": 1,
      "externalAudienceCount": 95,
      "internalAudienceCount": 18,
      "hoursImproved": 85.0,
      "moneySaved": 32000.00,
      "challengeWins": 1
    }
  ]
}

Exemplos de Filtros e Parâmetros:

Filtro por Período:

GET /api/dashboard/impact?period=annual
GET /api/dashboard/impact?period=semester
GET /api/dashboard/impact?period=quarter
GET /api/dashboard/impact?period=month

Filtro por Pilar:

GET /api/dashboard/impact?pillar=CULTURA
GET /api/dashboard/impact?pillar=ECOSSISTEMA
GET /api/dashboard/impact?pillar=P&D
GET /api/dashboard/impact?pillar=GOVERNANÇA

Filtros Combinados:

GET /api/dashboard/impact?period=annual&pillar=P&D
GET /api/dashboard/impact?period=semester&pillar=CULTURA

Exemplos de Cálculos de Pontuação:

Usuário com 3 Ideias Aprovadas, 2 em Progresso, 1 Concluída:

Pontos por Ideias Aprovadas: 3 × 10 = 30 pontos
Pontos por Ideias em Progresso: 2 × 15 = 30 pontos
Pontos por Ideias Concluídas: 1 × 20 = 20 pontos
Total de Pontos: 30 + 30 + 20 = 80 pontos

Nível: Especialista (50-99 pontos)

Usuário Vencedor de 2 Desafios:

Pontos por Desafios: 2 × 25 = 50 pontos
Pontos por Ideias: 80 pontos
Total de Pontos: 50 + 80 = 130 pontos

Nível: Líder (100+ pontos)

Exemplos de Configuração de Cache:

Configuração Redis:

# Em application.properties
spring.cache.type=redis
spring.redis.host=localhost
spring.redis.port=6379
spring.redis.timeout=2000ms
spring.cache.redis.time-to-live=300000
spring.cache.redis.cache-null-values=false

Configuração Caffeine (Local):

# Em application.properties
spring.cache.type=caffeine
spring.cache.cache-names=impact-metrics,engagement-metrics,user-stats
spring.cache.caffeine.spec=maximumSize=100,expireAfterWrite=5m,expireAfterAccess=10m

Exemplos de Queries SQL para Análise:

Top 5 Iniciativas por ROI:

SELECT 
    i.id,
    i.pillar,
    ((i.cost_before - i.cost_after) - i.implementation_cost) / i.implementation_cost * 100 as roi_percentage,
    (i.cost_before - i.cost_after) as cost_savings,
    i.implementation_cost
FROM initiatives i
WHERE i.status IN ('IN_PROGRESS', 'COMPLETED')
    AND i.implementation_cost > 0
    AND i.cost_before > i.cost_after
ORDER BY roi_percentage DESC
LIMIT 5;

Métricas por Pilar:

SELECT 
    i.pillar,
    COUNT(*) as total_initiatives,
    AVG((i.cost_before - i.cost_after)) as avg_cost_savings,
    AVG((i.process_time_before_hours - i.process_time_after_hours)) as avg_time_savings,
    SUM(i.implementation_cost) as total_investment
FROM initiatives i
WHERE i.status IN ('IN_PROGRESS', 'COMPLETED')
GROUP BY i.pillar
ORDER BY avg_cost_savings DESC;

Evolução Mensal de Economias:

SELECT 
    DATE_FORMAT(i.created_at, '%Y-%m') as month,
    SUM(i.cost_before - i.cost_after) as monthly_savings,
    COUNT(*) as initiatives_count
FROM initiatives i
WHERE i.status IN ('IN_PROGRESS', 'COMPLETED')
    AND i.cost_before > i.cost_after
GROUP BY DATE_FORMAT(i.created_at, '%Y-%m')
ORDER BY month;

---

Como Executar ✅

Pré-requisitos:

• JDK 21+
• Maven 3.8+
• MySQL 8.0 (local ou Docker)

Passos:

1. Configurar MySQL:

   • Executar script: setup_database.sql (cria database governance_dev)
   • Configurar variáveis (opcional): DB_USERNAME, DB_PASSWORD
   • Padrão: root sem senha

2. Build/Run (DEV):

   mvn clean spring-boot:run

   • App em: http://localhost:8080
   • Migrações Flyway executadas automaticamente
   • Dados de exemplo carregados via migração

   Executar com outro perfil:

   # Produção
   mvn clean spring-boot:run -Dspring-boot.run.profiles=prod
   
   # H2 (memória)
   mvn clean spring-boot:run -Dspring-boot.run.profiles=h2

3. Testes (110 testes passando):

   mvn test

Usuários de teste (carregados por DataInitializer) ✅:

• Admin: admin@inovafeed.com / senha password (roles: ADMIN, GOVERNANCE, USER)
• Gestor: joao.oliveira@inovafeed.com / senha password (roles: GOVERNANCE, USER)
• Usuário: carlos.lima@inovafeed.com / senha password (role: USER)

Ideias de exemplo ✅:

• Automatização do Onboarding (APPROVED)
• Dashboard de Vendas IA (IN_PROGRESS)
• Horário 100% Flexível (SUBMITTED)

---

Padrões de Código e Boas Práticas

• DTOs de entrada validados com jakarta.validation.
• Sanitização de logs e validação de UUIDs em controladores.
• Respostas consistentes via ApiResponse<T>.
• Casos de uso isolam regras da camada web e persistência.

---

Estrutura de Pastas relevante

src/main/resources
├─ application.properties (ativa perfil dev)
├─ application-dev.properties (H2, JWT, logging)
└─ static/ (index.html, css, js)

src/test/java
└─ ... testes de integração/unidade (ex.: IdeaFeedIntegrationTest)

---

Relatórios (Especificação)

• Especificações no arquivo RELATORIOS.md:
  • RELATORIO-ENGAJAMENTO-01: métricas de submissões, votos, comentários, funil por status/pilar, tops e tendências
  • RELATORIO-IMPACTO-01: economia (custo/tempo), público impactado, processos melhorados, por pilar e tops; inclui notas de ROI e payback
• Parâmetros como valor_hora_interna e investimento devem ser informados para cálculos financeiros.

---

Observações para IAs (contextualização)

• Este repositório segue monólito modular: mantenha mudanças limitadas ao módulo correto.
• Nomes de DTOs e campos são sensíveis à ordem (ex.: IdeaResponseDto possui 17 argumentos; veja o arquivo para evitar quebras de compilação).
• SecurityConfig já libera rotas públicas do feed; alterações de segurança devem preservar acesso a arquivos estáticos e /api/ideas/**.
• Para novas features de governança, prefira adicionar DTOs e casos de uso no módulo ideamanagement e expor endpoints em GovernanceController.

---

Roadmap

🔄 Próximos Passos

• Empacotar frontend com build (Vite/CRA) para produção
• Migrações Flyway/Liquibase (diretório db/migration já existe)
• Implementar chat entre usuários
• Disponibilizar acessibilidade
• Implementar sistema de notificações com integração ao e-mail corporativo
• Aprimorar onboarding e cadastro de novos usuários(SSO, códigos chaves e etc.)

---

Limitações Conhecidas

• SPA sem bundler (Vite/CRA) — adequado para protótipos didáticos
• Cache de segundo nível desabilitado em desenvolvimento

---

É ISSO VALEU GALERA ABRAÇOS