Insights de Engajamento

Visao Geral

O modulo de Engajamento analisa o envolvimento dos membros em 4 dimensoes — frequencia em cultos, participacao em celulas, regularidade de dizimo e envolvimento em eventos/escalas — para calcular um score de engajamento e identificar membros em risco de evasao. O painel oferece KPIs agregados, graficos e drill-down por membro.

Arquitetura

Score de Engajamento

Cada membro recebe um score de 0 a 100, calculado diariamente pelo comando engagement:calculate. O score e um snapshot armazenado na tabela member_engagement_scores, nao e real-time.

Pesos fixos (v1):

Dimensao	Peso	Verde (100%)	Amarelo (50%)	Vermelho (0%)
Culto	35%	3+ checkins/mes	1-2 checkins/mes	0 checkins/mes
Celula	25%	3+ presencas/mes	1-2 presencas/mes	0 ou nao participa
Dizimo	20%	Dizimo no mes atual	Dizimo ha 1-2 meses	Sem dizimo ha 3+ meses
Eventos/Escalas	20%	Participou no mes	Participou ha 1-2 meses	Sem participacao ha 3+ meses

Formula: score_total = (culto * 0.35) + (celula * 0.25) + (dizimo * 0.20) + (eventos * 0.20)

Classificacao de risco:

Nivel	Score	Cor
Verde (engajado)	>= 60	`#22c55e`
Amarelo (atencao)	>= 30 e < 60	`#eab308`
Vermelho (em risco)	< 30	`#ef4444`

Fase futura: os pesos serao configuraveis por tenant.

Eventos Recorrentes

Cultos regulares sao modelados como eventos recorrentes. Um evento "template" define o padrao de recorrencia (semanal, quinzenal, mensal) e o comando events:generate-recurring gera automaticamente as ocorrencias futuras (proximas 4 semanas).

Presenca em Celulas

O lider do grupo marca presenca individual dos membros ao registrar uma atividade, via lista de checkbox. Os dados sao armazenados em group_activity_attendances.

Models

MemberEngagementScore

Namespace: App\Domain\Engagement\Models\MemberEngagementScore

Campo	Tipo	Descricao
member_id	FK unique	Membro (1:1)
score_total	decimal(5,2)	Score composto 0-100
score_culto	decimal(5,2)	Score da dimensao culto
score_celula	decimal(5,2)	Score da dimensao celula
score_dizimo	decimal(5,2)	Score da dimensao dizimo
score_eventos	decimal(5,2)	Score da dimensao eventos
risk_level	string	green, yellow, red
last_checkin_at	timestamp	Ultimo checkin do membro
last_tithe_at	timestamp	Ultimo dizimo do membro
calculated_at	timestamp	Data do ultimo calculo

Scopes: atRisk(), byRiskLevel(string)

GroupActivityAttendance

Namespace: App\Domain\Group\Models\GroupActivityAttendance

Registra presenca individual de membros em atividades de grupo.

Campo	Tipo	Descricao
ulid	string	Identificador publico
group_activity_id	FK	Atividade do grupo
member_id	FK	Membro
presente	boolean	Presente na atividade

Unique constraint: (group_activity_id, member_id)

MemberStatusHistory

Namespace: App\Domain\Member\Models\MemberStatusHistory

Registra mudancas de status (situacao) do membro, populada automaticamente via MemberObserver.

Campo	Tipo	Descricao
member_id	FK	Membro
old_status_id	FK nullable	Status anterior
new_status_id	FK	Novo status
changed_by	FK nullable	Usuario que fez a alteracao
changed_at	timestamp	Data da mudanca
motivo	text nullable	Motivo da mudanca

Actions

CalculateEngagementScoreAction

Namespace: App\Domain\Engagement\Actions\CalculateEngagementScoreAction

Calcula o score de um membro individual. Consulta checkins, presencas em celula, dizimos e participacoes em eventos/escalas do periodo atual.

php

$action = new CalculateEngagementScoreAction();
$scores = $action->execute($member);
// Retorna: score_culto, score_celula, score_dizimo, score_eventos, score_total, risk_level, last_checkin_at, last_tithe_at

CalculateBulkEngagementScoresAction

Namespace: App\Domain\Engagement\Actions\CalculateBulkEngagementScoresAction

Itera todos os membros ativos do tenant e faz upsert dos scores em member_engagement_scores.

php

$action = new CalculateBulkEngagementScoresAction();
$count = $action->execute(); // Retorna numero de membros processados

GenerateRecurringEventsAction

Namespace: App\Domain\Event\Actions\GenerateRecurringEventsAction

Gera ocorrencias futuras para eventos com recurrence_type != 'none'. Nao duplica ocorrencias ja existentes.

php

$action = new GenerateRecurringEventsAction();
$count = $action->execute(); // Retorna numero de eventos gerados

Comandos Artisan

Comando	Schedule	Descricao
`engagement:calculate`	Diario 03:00	Recalcula scores para todos os tenants ativos
`events:generate-recurring`	Diario 02:00	Gera eventos recorrentes para proximas 4 semanas

O engagement:calculate aceita --tenant=ID para processar um tenant especifico.

Rotas

Tenant (requer feature `member_insights_full`)

Metodo	Rota	Controller	Permissao
GET	`/engagement`	`EngagementDashboardController@index`	`member_insights.view_full`
GET	`/engagement/members`	`EngagementDashboardController@members`	`member_insights.view_full`
GET	`/engagement/members/{member}`	`EngagementDashboardController@memberDetail`	`member_insights.view_full`

Permissoes

Permissao	Roles
`member_insights.view_full`	admin-igreja, secretario
`member_insights.view_basic`	admin-igreja, secretario, admin-congregacao, lider-grupo
`member_insights.export`	admin-igreja

O lider de celula nao acessa o painel de insights diretamente. Ele ve um indicador visual (bolinha verde/amarelo/vermelho) ao lado de cada membro na tela de gestao do grupo — sem informacoes financeiras.

Feature Flags

Feature	Descricao	Plano
`member_insights_basic`	Semaforo simplificado no dashboard	Basico+
`member_insights_full`	Painel completo com drill-down	Intermediario+
`member_insights_export`	Exportacao PDF	Premium

Frontend

Paginas

Pagina	Rota	Descricao
`Engagement/Index.vue`	`/engagement`	Dashboard com KPIs, graficos de distribuicao e score medio
`Engagement/Members.vue`	`/engagement/members`	Lista paginada de membros com filtros e semaforo
`Engagement/MemberDetail.vue`	`/engagement/members/{ulid}`	Drill-down: scores, checkins, presencas, dizimos, historico

Componentes

Componente	Uso
`RiskBadge.vue`	Bolinha verde/amarelo/vermelho com tooltip
`AttendanceChecklist.vue`	Lista de checkbox para presenca em atividade de grupo

Quando a feature member_insights_basic esta ativa, o dashboard do tenant exibe um card com:

Quantidade de membros em risco
Top 5 membros com maior risco
Link para painel completo (ou upgrade)

Separacao Central vs Tenant (LGPD)

Somente no Tenant: dados pessoais, scores individuais, drill-down, lista de presenca.

No Painel Central: metricas agregadas por tenant (% verde/amarelo/vermelho, tendencia). O central nunca acessa dados pessoais de membros.

Fases Futuras

Pesos configuraveis por tenant
Checkin automatico via app mobile (geolocalizacao)
Integracao WhatsApp/AI (notificacao ao pastor quando membro entra em vermelho)
Benchmark entre igrejas de porte similar
KPI de adocao do app mobile

Insights de Engajamento ​

Visao Geral ​

Arquitetura ​

Score de Engajamento ​

Eventos Recorrentes ​

Presenca em Celulas ​

Models ​

MemberEngagementScore ​

GroupActivityAttendance ​

MemberStatusHistory ​

Actions ​

CalculateEngagementScoreAction ​

CalculateBulkEngagementScoresAction ​

GenerateRecurringEventsAction ​

Comandos Artisan ​

Rotas ​

Tenant (requer feature member_insights_full) ​

Permissoes ​

Feature Flags ​

Frontend ​

Paginas ​

Componentes ​

Widget no Dashboard ​

Separacao Central vs Tenant (LGPD) ​

Fases Futuras ​