US3.2

Registro de Frequência e Carga Horária (RF14)

História de Usuário

Como organização, quero registrar a presença e atestar a carga horária dos estudantes aprovados para documentar a participação nas atividades.

Rastreabilidade

Item	Código / Referência
User Story	US3.2
Requisito Funcional	RF14 — Registrar frequência
Característica de Produto	CP03 — Acompanhamento e Certificação Acadêmica
Requisitos Não-Funcionais	RNF04 (responsivo iOS/Android), RNF08 (imutabilidade de certificados)
Release Planejada	R4 — Certificação

Descrição

Implementar a funcionalidade de registro de frequência para a organização. Após a realização da atividade de voluntariado, a organização deve poder marcar a presença de cada estudante aprovado e atestar a carga horária efetivamente cumprida. Este registro constitui a base documental para a emissão do certificado digital (RF15). Sem o registro de presença, o estudante não poderá receber o certificado de horas complementares. O escopo é full-stack.

Critérios de Aceite (BDD / Gherkin)

Cenário 1: Registro de presença com carga horária integral

Dado que a organização acessa a lista de aprovados da vaga "Apoio em Eventos", cuja carga horária prevista é de 20 horas
Quando marca presença para a estudante "Maria Silva" e confirma a carga horária de 20 horas
Então o sistema registra a presença, atesta 20 horas cumpridas e atualiza a situação da participante para presente

Cenário 2: Registro de carga horária parcial

Dado que o estudante "João Souza" foi aprovado para uma vaga de 40 horas, mas compareceu apenas 30 horas
Quando a organização registra presença com carga horária de 30 horas
Então o sistema registra 30 horas cumpridas e exibe um alerta de divergência em relação à carga horária prevista, solicitando confirmação

Cenário 3: Ausência do estudante

Dado que o estudante "Pedro Alves" foi aprovado, mas não compareceu à atividade
Quando a organização marca sua situação como ausente
Então o sistema registra a ausência e não contabiliza horas cumpridas para este estudante

Cenário 4: Tentativa de registrar presença duplicada

Dado que a presença da estudante "Maria Silva" já foi registrada para a vaga "Apoio em Eventos"
Quando a organização tenta registrar novamente
Então o sistema bloqueia a duplicidade e exibe a mensagem "Presença já registrada para este estudante nesta vaga"

Cenário 5: Organização tenta registrar frequência em vaga alheia

Dado que a organização B tenta registrar presença em uma vaga pertencente à organização A
Quando envia a solicitação
Então o sistema recusa a operação e informa que a ação não é permitida

Regras de Negócio

Apenas a organização responsável pela vaga pode registrar a frequência dos estudantes naquela atividade.
Somente estudantes previamente aprovados para a vaga podem ter sua presença registrada.
Cada estudante pode ter no máximo um registro de frequência por vaga de voluntariado.
A carga horária atestada pela organização não pode exceder a carga horária prevista da vaga.
É permitido o registro de carga horária parcial quando o estudante comparece, mas não cumpre a totalidade das horas previstas.
A situação de frequência de um estudante em uma atividade pode ser: presente (cumpriu a carga horária integral), presente parcialmente (cumpriu parte da carga horária) ou ausente (não compareceu).
Uma vez registrada, a frequência não pode ser alterada sem que haja uma justificativa documentada e rastreável, em respeito ao princípio de imutabilidade dos dados que servem de base para certificação acadêmica.

Requisitos Técnicos

Backend: Django + DRF. Criar modelo Attendance com campos: application (FK → Application), student (FK → StudentProfile), opportunity (FK → Opportunity), status (choices: present/absent/partial), hours_attested (PositiveIntegerField), attested_at (DateTimeField), attested_by (FK → User).
Endpoint: POST /api/v1/attendances/ — registrar presença. GET /api/v1/organizations/me/attendances/ — histórico de frequências.
Constraint: unique_together = ('student', 'opportunity') para impedir duplicidade.
Segurança: Verificar que opportunity.organization == request.user.organization_profile.
Frontend: React Native + Expo + NativeWind. Tela de registro de frequência com lista de aprovados, indicador de presente/ausente, campo de carga horária com validação.
Responsividade: Layout adaptável a iOS e Android (RNF04).
Testes: pytest para testar registro de presença, validação de carga horária, bloqueio de duplicidade e permissões de organização.

Referências de Design

Protótipo Figma (Geral): https://www.figma.com/design/f6bQuVohTvZLF5WWPEbNob/Liaison?node-id=0-1
Observação: A tela de registro de frequência precisa ser confirmada no protótipo Figma.

Dependências

Relacionada a: #26 (Listagem de Aprovados — RF13/US3.1), #24 (Avaliação de Candidaturas — RF11/US2.8)
Bloqueada por: #26 (RF13 — Listar aprovados)
Bloqueia: #31 (Geração de Certificado — RF15/US3.3)

Notas

ICE Score: I=9 C=7 E=4 = 252 | MoSCoW: Must | Quadrante: Plan
RF14 é classificada como Plan (E=4) devido à complexidade das validações de negócio e às exigências de imutabilidade. Recomendação: fatiar em (1) estrutura de dados e operação básica de registro, (2) validações de carga horária, (3) interface de registro no frontend.
A imutabilidade do registro de frequência (RNF08) é um requisito crítico: uma vez atestada a presença, esse dado fundamenta a emissão do certificado e não pode ser modificado sem rastreabilidade de auditoria.
Este item pertence à cadeia longa de dependências que culmina em RF15 (emitir certificado). Atrasos nesta funcionalidade impactam toda a release R4.

Definição de Preparado (DoR)

Item de Verificação (Universal)	Evidência / Rastreabilidade	Situação
A história está bem descrita e com critérios de aceite?	Documentada e alinhada com o escopo do MVP.	✔ Sim
Possui protótipos de interface necessários?	Interface mapeada e disponível no Figma da equipe.	✔ Sim
A história é independente o suficiente para ser entregue?	Cadeia de dependências resolvida (vide Matriz MVP).	✔ Sim
Foi estimada pela equipe?	Estimada utilizando o método ICE Score.	✔ Sim

Definição de Pronto (DoD)

Pergunta Fundamental (Universal)	Evidência de Implementação	Status
O código foi implementado e revisado?	Pull Request aprovado e fundido na branch principal.	✔ Sim
Coerente com o protótipo validado?	O layout segue os componentes e tokens de design.	✔ Sim
Passou nos testes necessários?	Testes (unitários/integração) executados e aprovados.	✔ Sim
A documentação está atualizada?	Atualizada no repositório de requisitos.	✔ Sim

Critérios de Aceitação (CA)

Presença com carga horária integral: A organização registra presença de um estudante com a carga horária prevista da vaga — o sistema confirma as horas e atualiza o status do estudante para presente.
Carga horária parcial: Se o estudante foi por menos horas do que o previsto, a organização informa a quantidade real — o sistema registra com um alerta de divergência e solicita confirmação.
Ausência: A organização marca o estudante como ausente — nenhuma hora é contabilizada para ele.
Presença duplicada: Se a presença do estudante já foi registrada para aquela vaga, o sistema bloqueia e exibe "Presença já registrada para este estudante nesta vaga".
Segurança: A organização não consegue registrar presença em vagas de outras organizações.

Acesso & Evidência

Código Homologado: Repositório Principal
Status de Conclusão: 100% Entregue (conforme Matriz de Completude).