Contrato — Retrospectiva de Conclusão do Plano
Status: Implementado
Termos: Plano do Aluno, Retrospectiva, Matrícula, Duração do Ciclo do Aluno, Dias de Preparação
Controller: retrospective_api_controller
Regra de alerta: retrospective_available_rule (ver study.md /alerts)
A conclusão que dispara esta retrospectiva usa exclusivamente o Critério de
Conclusão Pedagógica “Conclusão Total do Plano” (todos os Fluxos do sequence
esgotados) — os demais critérios configuráveis por Trilha (Percentual Mínimo
de Execução, Aprovação em Avaliação Final, Cumprimento de Prazo, etc.; ver
.vigim/ddd/terms/terms-activity.yaml) não são avaliados por esta feature.
Endpoints
| Método | Path | Função |
|---|---|---|
| GET | /api/v1/platform/study/{enrolment_id}/retrospective |
Dados agregados da retrospectiva do ciclo concluído |
| POST | /api/v1/platform/study/{enrolment_id}/retrospective/ack |
Marca o popup automático como já exibido (idempotente) |
Todos exigem Authorization: Bearer {wstoken}.
GET /study/{enrolment_id}/retrospective
Só retorna dados quando student_plan.student_plan_status === 'completed'
(todos os módulos do plano concluídos). Fora disso, 404.
Response 200
{
"student": { "name": "João Silva", "firstName": "João" },
"cycle": {
"days": 30,
"startedAt": "2026-07-03T20:00:00+00:00",
"endedAt": "2026-07-25T08:00:00+00:00",
"onboardingSentAt": "2026-07-03T19:52:00+00:00",
"preparationDays": 22,
"enrolmentStartAt": "2026-07-01T00:00:00+00:00",
"enrolmentEndAt": "2026-07-31T00:00:00+00:00",
"unitsAnalyzed": 60,
"activities": 214,
"questionsAnswered": 342,
"simulationsCount": 6,
"studyHours": 71,
"reviews": 48
},
"overallPerformance": 78.0,
"disciplines": [
{
"id": "5",
"name": "Direito Constitucional",
"performance": 82.0,
"units": 20,
"sources": { "law": 88.0, "doctrine": 79.0, "jurisprudence": 76.0 }
}
],
"units": {
"5": [
{ "id": "1602", "n": 1, "title": "Teoria da Constituição", "pct": 91.0, "level": "Avançado" }
]
},
"simulations": [
{ "id": "550e...", "date": "2026-07-16T00:00:00+00:00", "score": 61.0 }
],
"writtenSimulation": {
"title": "Simulado Escrito",
"performance": 74.0
},
"nextSteps": [
{ "unit": "Direito Penal", "disc": "Direito Penal", "reason": "Menor consolidação do ciclo", "accent": "#12C9C2" }
]
}Datas e contagens de cycle
A regra completa, com a fonte de cada data e onde cada número aparece no portal, está em Retrospectiva — dias do ciclo (especificação em middag-io/docker-moodle-helico#103). Nenhum dos dois números recebe arredondamento para a dezena, nem aqui nem no portal.
| Campo | Termo | Definição |
|---|---|---|
days |
Duração do Ciclo do Aluno | ceil((enrolmentEndAt − enrolmentStartAt) / 24 h). Sem Data de Término da Matrícula, o fim é endedAt. Sem Data de Início da Matrícula (registro legado), o início é startedAt. Matrícula de 30 dias = 30, independentemente de quando o Aluno concluiu. 0 quando não há nenhuma data de início. Não é mais a duração planejada pelo dimensionamento do plano (Unidades ÷ carga semanal × 7). |
preparationDays |
Dias de Preparação | ceil((endedAt − startedAt) / 24 h), com mínimo 1 e máximo days (o máximo não se aplica quando days é 0). Primeiro Acesso no dia 20 às 20h e conclusão no dia 21 às 8h = 1. No exemplo acima: 21 dias e 12 h = 22. Null sem startedAt. |
startedAt |
Primeiro Acesso | Criação do Plano do Aluno (meta created_at), que acontece depois do Onboarding. Início dos Dias de Preparação. |
endedAt |
Conclusão do Plano do Aluno | Meta completed_at do Plano do Aluno. Fim dos Dias de Preparação e fim da Duração do Ciclo quando a Matrícula não tem Data de Término. |
onboardingSentAt |
— | Envio do Questionário de Perfil do Onboarding. Informativo: não entra em nenhuma contagem. Null sem registro do Onboarding. |
enrolmentStartAt |
Data de Início da Matrícula | Início da Vigência de Acesso (user_enrolments.timestart, espelhado na Matrícula). ISO 8601. |
enrolmentEndAt |
Data de Término da Matrícula | Fim da Vigência de Acesso (user_enrolments.timeend, espelhado na Matrícula). ISO 8601; null quando a Matrícula não tem Data de Término. |
Diferenças conhecidas em relação ao mock original de referência (app-helico,
commit 141262d6a133ba1e3640e69b07156eb32e55266b):
| Campo do mock | Status nesta versão |
|---|---|
student.memberSince |
Não retornado — campo morto nos slides reais |
disciplines[].accent, disciplines[].short |
Não retornados — sem fonte confirmada / campo morto |
topics.strong[]/topics.review[] |
Não retornado — granularidade de tópico não existe no plugin, sub-iniciativa futura |
simulations[].name/.questions |
Não retornados — só usados no export PDF do frontend, fora de escopo |
writtenSimulation.criteria[]/.aiFeedback |
Não retornados — sem fonte estruturada confirmada |
Frontend trata todos os campos acima como ausentes/opcionais.
POST /study/{enrolment_id}/retrospective/ack
Marca que o popup automático já foi exibido pro aluno desta matrícula.
Idempotente — chamar mais de uma vez não tem efeito colateral. Não afeta a
presença do alerta retrospective_available na lista de Alertas do Estudo
(esse permanece enquanto o plano estiver completed).
Response 200
{ "success": true }Erros
| HTTP | error |
Causa |
|---|---|---|
| 401 | unauthorized |
wstoken ausente/inválido |
| 404 | plan_not_completed |
Plano do Aluno ainda não concluído |
| 404 | retrospective_disabled |
Feature desligada via retrospective_feature_flag::ENABLED |
Referências
- Source:
classes/extensions/platform/controller/retrospective_api_controller.php - Contagem dos dias:
classes/extensions/engine/retrospective/support/cycle_days.php - Regra de alerta:
classes/extensions/engine/alerts/service/rule/retrospective_available_rule.php - Feature flag:
classes/extensions/engine/retrospective/retrospective_feature_flag.php