Retrospectiva — dias do ciclo
Status: EM REVISÃO
A Retrospectiva de Conclusão do Plano mostra dois números de dias diferentes. Esta página explica o que cada um mede, de onde vêm as datas e onde cada um aparece no portal. O contrato do endpoint está em contratos/retrospective.md. A especificação foi confirmada pela HÉLICO em 19/10/2026 e consolidada em middag-io/docker-moodle-helico#103.
Os dois termos estão no glossário com status REVISÃO até a HÉLICO validar: Duração do Ciclo do Aluno e Dias de Preparação.
Duas contagens, duas perguntas
| Duração do Ciclo do Aluno | Dias de Preparação | |
|---|---|---|
| Pergunta | Quanto tempo de acesso o Aluno contratou? | Quanto tempo o Aluno levou para concluir o plano? |
| Início | Data de Início da Matrícula; sem ela, Primeiro Acesso | Primeiro Acesso (criação do Plano do Aluno) |
| Fim | Data de Término da Matrícula; sem ela, Conclusão do Plano do Aluno | Conclusão do Plano do Aluno |
| Fórmula | ceil((fim − início) / 24 h) |
ceil((conclusão − primeiro acesso) / 24 h) |
| Limites | — | mínimo 1, máximo a Duração do Ciclo do Aluno |
| Campo da API | cycle.days |
cycle.preparationDays |
As duas contagens usam blocos de 24 horas arredondados para cima, não dias de calendário. Nenhuma recebe arredondamento para a dezena, nem no backend nem no portal.
Duração do Ciclo do Aluno
Mede a Vigência de Acesso da Matrícula: da Data de Início à Data de Término. Uma Matrícula de 30 dias tem Duração do Ciclo de 30 dias, mesmo que o Aluno conclua o plano em 10.
Quando a Matrícula não tem Data de Término (acesso sem prazo), a contagem vai até a Conclusão do Plano do Aluno.
Quando a Matrícula não tem Data de Início registrada (registro legado, anterior ao espelhamento de timestart), a contagem parte do Primeiro Acesso. Toda Matrícula criada pelo evento do Moodle grava a Data de Início, com a data do evento quando o Moodle não tem timestart, então esse caso não deve ocorrer em matrículas novas. Sem nenhuma das duas datas, a duração é 0.
A duração deixou de vir do dimensionamento do Plano do Aluno (Unidades ÷ carga semanal × 7). Esse valor estimava quanto o plano deveria durar, mas não correspondia ao acesso contratado.
Dias de Preparação
Mede o tempo entre o Primeiro Acesso e a Conclusão do Plano do Aluno. O Primeiro Acesso é a criação do Plano do Aluno, que acontece depois do Onboarding. A contagem não parte do envio do Onboarding nem da Data de Início da Matrícula.
Os limites existem para o número fazer sentido na tela:
- Mínimo 1: um Aluno que conclui em poucas horas estudou 1 dia, não 0.
- Máximo a Duração do Ciclo do Aluno: a preparação não pode passar do ciclo mostrado no título do modal. Quando a duração é 0 (sem data de início), o máximo não se aplica, para não levar a contagem abaixo de 1.
Sem Primeiro Acesso registrado, os Dias de Preparação vêm nulos.
Caso confirmado pela HÉLICO (19/10/2026)
Primeiro Acesso no dia 20 às 20h, conclusão no dia 21 às 8h: são 12 horas, um bloco de 24 h incompleto, então 1 dia. Em dias de calendário seriam 2, e por isso a contagem não usa calendário.
Fonte de cada data
| Data | Onde vem | Campo da API |
|---|---|---|
| Data de Início da Matrícula | user_enrolments.timestart do Moodle, espelhado na Matrícula do local_helico |
cycle.enrolmentStartAt |
| Data de Término da Matrícula | user_enrolments.timeend do Moodle, espelhado na Matrícula (ausente quando o acesso não tem prazo) |
cycle.enrolmentEndAt |
| Primeiro Acesso | created_at do Plano do Aluno |
cycle.startedAt |
| Conclusão do Plano do Aluno | completed_at do Plano do Aluno |
cycle.endedAt |
| Envio do Onboarding | Conclusão do Questionário de Perfil. Só informativo, fora das contagens | cycle.onboardingSentAt |
Onde cada número aparece no portal
| Lugar | Número | Texto |
|---|---|---|
| Título do modal de fim de ciclo | Duração do Ciclo do Aluno (cycle.days) |
“Seu ciclo de N dias chegou ao fim.” |
| Corpo do modal de fim de ciclo | Dias de Preparação (cycle.preparationDays) |
“nesses N dias” |
| Abertura dos slides | Dias de Preparação | — |
| Último slide | Dias de Preparação | “N dias foram só o começo.” |
| Capa do PDF | Dias de Preparação | — |
| Card de compartilhar | Dias de Preparação | — |
A Duração do Ciclo aparece só no título do modal. O portal lê os dois campos do backend como vêm, sem recalcular pelas datas.
Exemplo de aceite: a Retrospectiva de uma Matrícula de 30 dias mostra “Seu ciclo de 30 dias” no título e os Dias de Preparação reais no resto.
Referências
- Contrato: contratos/retrospective.md
- Matrícula, Vigência de Acesso e Primeiro Acesso: Engine — Acesso
- Especificação: middag-io/docker-moodle-helico#103
- Service:
classes/extensions/engine/retrospective/service/retrospective_view_service.php - Contagem dos dias:
classes/extensions/engine/retrospective/support/cycle_days.php