Mapa de Ajustes para Conformidade com os Documentos

Objetivo: alinhar integralmente o código às definições contidas em docs/ (vision, ADRs, PRD, UI).

Última atualização: 2025-03-01

Visão geral

Camada	Itens	Prioridade
Backend Domain	9 entidades	Alta
Backend Application	Use cases e serviços	Alta
Backend Infrastructure	Repositórios, Firestore	Alta
Frontend Domain	9 entidades	Alta
Frontend Presentation	Home, presença, aulas	Média
Migração/Planejamento	ADR-0017 (config/data)	Média

1. Backend — Entidades de Domínio

Referência: ADR-0005, plano-adr-legacy-fields.md

1.1 Entidades inexistentes (criar)

Entidade	Status	Observação
Ministry	Ausente	id, name, created_at, status (ACTIVE \| INACTIVE)
OrganizationalUnit (completa)	Parcial	Existe apenas `SignupChurchOption` (unitId, label). Falta entidade com ministry_id, parent_unit_id, code, phone_primary, phone_secondary, email, address, group, pastor_id, secretary_id, foundation_date, status
ClassGroup	Ausente	id, ministry_id, unit_id, name, age_group, display_order, status
EbdSession	Ausente	id, ministry_id, unit_id, date, status, type, replace_cause, weather_type, temperature, totals, principals[], observation
Lesson	Ausente	id, ministry_id, unit_id, ebd_session_id, class_group_id, date, theme, material_id, teacher_id, monitor_id, status, contagens, observation
Attendance	Ausente	id, ministry_id, unit_id, lesson_id, user_id, category, timestamp, method (QR \| WIFI \| GEO), validated_by_backend
Material	Ausente	id, ministry_id, name, publisher, edition, reference_period

1.2 Entidades existentes — ajustes

Entidade	Campo/Regra faltante	ADR
UserAccount	Já alinhado em grande parte	ADR-0005, ADR-0013
Person	Mapear como extensão de User (dados pessoais)	ADR-0005
Role / MinistryRoleCatalog	Verificar enums vs ADR-0005 (EbdReplaceCause, ClassAgeGroup, EbdSessionType, etc.)	ADR-0005
OrganizationNodeRef	Incluir `parent_unit_id` explícito; validar pathIds/pathNames vs ADR-0016	ADR-0016

1.3 Enums a implementar

ClassAgeGroup (NURSERY, KINDERGARTEN, GARDEN, JUNIORS, TEENAGERS, YOUNG_ADULTS, LEVITES, BAPTISM, EVANGELISM, INTEGRATION, WORKERS, COUPLES, ADULTS, MASTERS, NONE)
EbdSessionType (FULL_CLASS, REGULAR_CLASS, UNIQUE_CLASS, ONLINE_CLASS, CANCELED, REPLACED_BY_EVENT, REPLACED_BY_CULT)
EbdReplaceCause (LOCAL_EVENT, MINISTERIAL_EVENT, BAPTISM, WEATHER_CONDITION, etc.)
LessonStatus (CREATED, IN_PROGRESS, CONCLUDED, CLOSED, NOT_HELD_TODAY, NOT_EXISTS)
AttendanceCategory (STUDENT, VISITOR, LEADER, WORKER, PASTOR)
AttendanceMethod (QR, WIFI, GEO) — ADR-0004

2. Backend — Application (Use Cases e Serviços)

Referências: ADR-0004, ADR-0013, ADR-0014

2.1 Presença (ADR-0004)

Funcionalidade	Status	Responsável
Gerar QR Code dinâmico para Lesson (unit_id, lesson_id, janela temporal)	Ausente	Use case + handler
Validar scan QR e registrar Attendance	Ausente	Handler USER_ATTENDANCE_REGISTER ou equivalente
Validação por Wi-Fi (faixa IP cadastrada, confirmação explícita)	Ausente	Use case
Geolocalização opcional (confirmação explícita)	Ausente	Use case
BLE	Fora da Fase 1	Não implementar

2.2 Perfil e ciclo de vida (ADR-0013)

Funcionalidade	Status	Observação
Matriz de transição de status (backend como autoridade)	Parcial	Verificar se todas as transições estão validadas
Auditoria de mudança de status (actor_id, from_status, to_status, reason, timestamp)	Verificar	AuditLogRepository existe
Onboarding pós-autenticação (dados obrigatórios pendentes)	Verificar	Backend restringir operações não essenciais até conclusão
Preferências segmentadas (notifications, appearance, usage)	Parcial	UserPreferences em UserAccount

2.3 Gateway único (ADR-0014)

Ação sugerida	Status
USER_ATTENDANCE_REGISTER (QR)	Ausente
USER_ATTENDANCE_REGISTER (WIFI)	Ausente
USER_ATTENDANCE_REGISTER (GEO)	Ausente
USER_LESSONS_LIST / USER_MY_LESSONS	Ausente
USER_ATTENDANCE_HISTORY	Ausente

3. Backend — Infrastructure

Referências: ADR-0005, ADR-0017

3.1 Firestore — Estrutura alvo (ADR-0017)

platform/ministrys/{domain}/
├── config/           ← apenas configuração
└── data/
    ├── churchs/{unit_id}/
    │   └── classes/  ← ClassGroup
    │   └── ebd_sessions/  ← EbdSession
    │       └── lessons/   ← Lesson
    │           └── attendances/  ← Attendance
    └── users/

Item	Status
Migração config/churchs → data/churchs	Pendente
Fallback de leitura (config → data)	Verificar repo atual
Coleções: ministrys, churchs (data), classes, ebd_sessions, lessons, attendances, materials	Parcial (churchs em config)

3.2 Repositórios

Repositório	Status
FirestoreOrganizationalUnitRepository	Existe; retorna SignupChurchOption. Adicionar getById, listByParent, campos completos
MinistryRepository	Ausente
ClassGroupRepository	Ausente
EbdSessionRepository	Ausente
LessonRepository	Ausente
AttendanceRepository	Ausente
MaterialRepository	Ausente

4. Frontend — Entidades de Domínio

Referência: ADR-0005

4.1 Entidades inexistentes

Entidade	Status
Ministry	Ausente
OrganizationalUnit	Parcial (SignupChurchOption é referência leve)
ClassGroup	Ausente
EbdSession	Ausente
Lesson	Ausente
Attendance	Ausente
Material	Ausente

4.2 Ajustes em entidades existentes

Entidade	Ajuste
UserProfile	Verificar campos vs ADR-0013: avatar_source, avatar_updated_at, last_login_at, deletion_requested_at, preferences segmentadas
RoleCatalogItem	Verificar conformidade com enum de papéis do ADR-0005

5. Frontend — Presentation (UI)

Referências: docs/ui/pages/home.md, docs/ui/components/action-card.md, ADR-0009

5.1 Home Page (docs/ui/pages/home.md)

Componente	Status	Ajuste
_NavTabs (Início, Frequência, Aulas)	Existe	As abas Frequência e Aulas exibem o mesmo conteúdo que Início. Implementar conteúdo distinto:
		— Frequência: histórico/resumo de presenças, ou lista de aulas com status de presença
		— Aulas: lista "Minhas aulas" (classes do usuário, próximas sessões)
ActionCard "Registrar presença"	Existe	`onTap: () {}` — placeholder. Implementar navegação para tela de scan QR (ou fluxo WIFI/GEO)
ActionCard "Minhas aulas"	Existe	`onTap: () {}` — placeholder. Implementar navegação para lista de aulas do usuário
_Footer	Ok	"Fiel a todo momento" + versão

5.2 Fluxo de presença (ADR-0004)

Tela/Fluxo	Status
Tela de scan QR	Ausente
Tela de confirmação WIFI (quando em rede da unidade)	Ausente
Tela de confirmação GEO (opcional)	Ausente
Feedback de sucesso/falha no registro	Ausente

5.3 Fluxo "Minhas aulas"

Tela/Fluxo	Status
Lista de classes do usuário (como aluno/professor/monitor)	Ausente
Detalhes de aula (Lesson) com opção de registrar presença	Ausente
Histórico de presença	Ausente

6. Governança e Regras Cross-Cutting

Referências: ADR-0002, ADR-0003, ADR-0016

Regra	Onde validar
Toda entidade com ministry_id	Domain + backend validation
Entidades com unit_id validam escopo (SAME, ANCESTOR, DESCENDANT, UNRELATED)	Backend handlers
Backend como autoridade de autorização	Todos os handlers
Escopo hierárquico por parent_unit_id (ADR-0016)	Repositórios e use cases
Firestore somente em infrastructure	ADR-0007

7. Priorização sugerida

Fase 1 — Fundação de domínio

Criar entidades backend: Ministry, OrganizationalUnit (completa), ClassGroup, EbdSession, Lesson, Attendance, Material
Criar entidades frontend correspondentes
Repositórios Firestore conforme ADR-0017

Fase 2 — Presença (core do produto)

Use case de geração de QR dinâmico (professor/responsável)
Use case de registro de presença (aluno escaneia QR)
Handler USER_ATTENDANCE_REGISTER no gateway
Telas: scan QR, confirmação, feedback
Conectar ActionCard "Registrar presença" ao fluxo

Fase 3 — Minhas aulas

Use case USER_LESSONS_LIST / USER_MY_LESSONS
Tela lista de aulas
Conectar ActionCard "Minhas aulas" e aba Aulas
Aba Frequência com histórico de presença

Fase 4 — Refinamentos

Migração config/churchs → data/churchs (ADR-0017)
WIFI e GEO como mecanismos complementares de presença
Onboarding pós-autenticação (ADR-0013)
Preferências segmentadas completas

8. Checklist de conformidade (resumo)

Entidades ADR-0005 implementadas em backend e frontend
Estrutura Firestore data/churchs (ADR-0017)
Presença por QR implementada (ADR-0004)
ActionCards "Registrar presença" e "Minhas aulas" funcionais
Abas Frequência e Aulas com conteúdo distinto
Ciclo de vida de usuário (ADR-0013) e matriz de transição no backend
Escopo hierárquico (parent_unit_id, ANCESTOR/DESCENDANT) validado
Gateway único (ADR-0014) com handlers de presença e aulas

Visão geral​

1. Backend — Entidades de Domínio​

1.1 Entidades inexistentes (criar)​

1.2 Entidades existentes — ajustes​

1.3 Enums a implementar​

2. Backend — Application (Use Cases e Serviços)​

2.1 Presença (ADR-0004)​

2.2 Perfil e ciclo de vida (ADR-0013)​

2.3 Gateway único (ADR-0014)​

3. Backend — Infrastructure​

3.1 Firestore — Estrutura alvo (ADR-0017)​

3.2 Repositórios​

4. Frontend — Entidades de Domínio​

4.1 Entidades inexistentes​

4.2 Ajustes em entidades existentes​

5. Frontend — Presentation (UI)​

5.1 Home Page (docs/ui/pages/home.md)​

5.2 Fluxo de presença (ADR-0004)​

5.3 Fluxo "Minhas aulas"​

6. Governança e Regras Cross-Cutting​

7. Priorização sugerida​

Fase 1 — Fundação de domínio​

Fase 2 — Presença (core do produto)​

Fase 3 — Minhas aulas​

Fase 4 — Refinamentos​

8. Checklist de conformidade (resumo)​