PRD — Relatório de EBD (Preencher)

Status

Proposta (aguardando aprovação)

Tipo de documento

PRD (Product Requirements Document) — requisitos de produto para a funcionalidade de preenchimento do relatório de EBD (dados da sessão e das classes).

Contexto

O relatório de EBD registra os dados de uma ocorrência da Escola Bíblica Dominical em uma unidade em uma data específica. Inclui totais gerais, informações de clima, tipo de ocorrência e, por classe, professor, assistente, contagens por categoria (alunos, visitantes, líderes, obreiros, pastores), revista/lição e observações.

O projeto legado (_legacy) já implementa esse fluxo; o EBDbe novo deve evoluir o modelo conforme ADR-0005 (EbdSession, Lesson) e permitir preenchimento por perfis autorizados.

Referências: ADR-0005 — Modelo de Domínio Conceitual, ADR-0024 — Controle de visibilidade de ações por perfil, plano-adr-legacy-fields.

Objetivo de negócio

Coletar informações confiáveis sobre as ocorrências da EBD em cada igreja, com fluxo operacional por fases e colaboração entre papéis que se complementam e se sobrepõem de forma controlada.

A coleta é orientada por classe e consolidada por igreja.
O ciclo de vida do relatório deve permitir trabalho incremental até envio.
Após envio, o relatório fica bloqueado para edição operacional.

Separação de responsabilidades (obrigatória)

A implementação deve separar duas ações distintas:

Criar sessão de EBD (ocorrência da igreja)
- registra a ocorrência da EBD na data;
- define classes participantes da sessão;
- define responsáveis da EBD presentes na sessão;
- executado por quem governa a ocorrência da igreja.
Preencher classe da sessão (execução pedagógica)
- registra dados de participantes por classe;
- registra observações, lição/material e dados da classe;
- executado por papéis vinculados à classe (professor e assistente).

Regra:

A sessão é pré-requisito para o preenchimento das classes.
Não misturar, na mesma ação, governança da sessão e execução de classe.

Ciclo de vida do relatório

Estados funcionais:

PREENCHIMENTO
REVISAO
CONCLUIDO
ENVIADO
DEVOLVIDO (retorno para correção por papel de governança)
APROVADO (encerramento por governança)

Regras:

Papéis autorizados podem avançar e retroceder entre PREENCHIMENTO, REVISAO e CONCLUIDO conforme escopo.
ENVIADO bloqueia edição para papéis operacionais (classe/igreja).
DEVOLVIDO reabre o ciclo para correção.
APROVADO encerra o ciclo.

Acesso e visibilidade

Critério	Regra
Visibilidade da ação	Regra híbrida (`minRole` + matriz de acesso)
Privilégio de escrita	Definido por papel + vínculo + escopo (classe/igreja/ministério)
Validação final	Backend (RBAC + escopo unit_id) conforme ADR-0003

Papéis e escopos operacionais

Papel	Escopo	Pode executar
Assistente de classe	Classe em que está vinculado como assistente	Preencher, revisar, concluir
Professor de classe	Classe em que está vinculado como professor	Preencher, revisar, concluir
Superintendente	Classes da igreja sob sua responsabilidade	Preencher, revisar, concluir, enviar
Secretaria local	Igreja de atuação	Preencher, revisar, concluir, enviar
Secretaria geral / Coordenador de ministério	Ministério (governança)	Preencher, revisar, concluir, enviar, devolver, aprovar

Regras complementares:

Todos os papéis acima podem retornar fases enquanto o relatório não estiver em estado final bloqueado.
Após ENVIADO, somente papéis de governança podem DEVOLVER ou APROVAR.

Dados do relatório (nível EbdSession)

Campo	Descrição
data	Data da ocorrência
unidade (unit_id)	Igreja onde ocorreu
status	CREATED, IN_PROGRESS, CONCLUDED, CLOSED
tipo	FULL_CLASS, REGULAR_CLASS, UNIQUE_CLASS, ONLINE_CLASS, CANCELED, REPLACED_BY_EVENT, REPLACED_BY_CULT
causa (se tipo anormal)	LOCAL_EVENT, MINISTERIAL_EVENT, BAPTISM, WEATHER_CONDITION, etc.
observação causa	Texto livre
clima (weather_type)	SUNNY, PARTLY_CLOUDY, CLOUDY, LIGHT_RAIN, HEAVY_RAIN, THUNDERSTORM, FOG
temperatura	VERY_COLD, COLD, MILD, WARM, VERY_WARM
totais gerais da igreja	Derivados automaticamente da soma dos totais de todas as classes da sessão
observação geral	Texto livre
responsáveis (principals)	Lista de usuários responsáveis pela EBD naquele dia

Dados por classe (nível Lesson)

As classes são armazenadas como subcoleção dentro da EbdSession (ebds/{sessionId}/lessons/{lessonId}). São incluídas pelo usuário que cria a sessão; não derivam automaticamente dos ClassGroups.

Sugestão na criação: Ao criar nova EbdSession, o sistema sugere as classes usadas no domingo anterior (mesma unidade). O criador pode aceitar, remover ou adicionar classes.

Campo	Descrição
classe (ClassGroup)	Nome e tipo (age_group)
status	CREATED, IN_PROGRESS, CONCLUDED, CLOSED, NOT_HELD_TODAY, NOT_EXISTS
professor (teacher_id)	Referência a User
assistente (monitor_id)	Referência a User
totais	total_students, total_visitors, total_leaders, total_workers, total_pastors
editora (publisher)	CPAD, EBENEZER, OTHERS, DO_NOT_USE
revista (material)	Ano e nome da revista
lição (theme)	Número e título da lição ministrada
observação	Texto livre

Consistência de vínculos

No agregado (conta do usuário): um usuário com papel de professor deve estar vinculado a pelo menos uma classe em algum momento operacional; idem para assistente — referem-se ao perfil/conta, não ao conteúdo obrigatório de cada ocorrência de lesson.
Por lesson (sessão): uma lesson pode ter só professor, só assistente(s), ambos ou nenhum ainda preenchido; não é requisito para gravar o preenchimento que a mesma lesson tenha professor e assistente simultaneamente. O backend autoriza gravação quando o usuário logado está vinculado àquela lesson no papel adequado (professor ou assistente) e demais regras de fase/matriz forem atendidas.
Uma classe pode possuir múltiplos professores e múltiplos assistentes habilitados.

As regras de conta/transição de fase devem ser validadas no backend onde aplicável; a independência professor/assistente na mesma lesson segue o TDD de relatório EBD (cenários CL12/CL13).

Fluxo de uso (visão geral)

Fluxo A — Criar sessão de EBD

Usuário autorizado para governança da igreja acessa Criar sessão de EBD.
Seleciona unidade (quando aplicável) e data (domingo).
Cria ocorrência da sessão.
Define classes que ocorrerão na sessão (aceitar sugestão anterior, remover, adicionar).
Define responsáveis da EBD presentes na sessão.
Salva sessão.

Fluxo B — Preencher classes da sessão

Usuário vinculado à classe acessa Preencher classe da sessão.
Seleciona sessão já criada.
Preenche dados da sua classe (participantes, lição/material, observações).
Conclui/revisa conforme regra de fase e escopo.
Sistema recalcula totais gerais da igreja pela soma das classes.
Governança envia/devolve/aprova conforme regra de ciclo de vida.

Regra transversal

Backend valida RBAC + vínculo + escopo + fase em toda operação de escrita.

Estrutura de frontend

O módulo de relatório deve ter frente próprio (pasta dedicada), permitindo evolução independente:

frontend/lib/presentation/modules/ebd_report/
├── ebd_report_page.dart
├── widgets/
└── ...

Critérios de aceite (resumo)

A ação “Preencher relatório de EBD” aparece na aba Ações somente para perfis com hierarchyLevel ≤ 5.
Ação de criar sessão separada da ação de preencher classe.
Ao tocar, navega para a página do relatório.
A página permite seleção de unidade e data.
Classes como subcoleção: Lessons em ebds/{sessionId}/lessons/.
Inclusão pelo criador: Quem cria a EbdSession define quais classes farão parte da sessão.
Sugestão na criação: Ao criar nova sessão, sugere classes do domingo anterior (mesma unidade); o criador pode aceitar, remover ou adicionar.
Estrutura preparada para integração com backend (entidades EbdSession, Lesson).
Totais gerais da igreja são sempre derivados das classes (sem entrada manual conflitante).
Regras de fase respeitam escopo por papel.
Relatório enviado não é editável por papéis operacionais.
Governança pode devolver/aprovar conforme política de acesso.
Backend validará RBAC e escopo em todas as operações de escrita.

Referências

Tipo	Documento
ADR	ADR-0005, ADR-0003, ADR-0024
Docs	plano-adr-legacy-fields, PRD-0002