Skip to content

Contrato — Retrospectiva de Conclusão do Plano

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
Navigation

Type to search…

↑↓ navigate↵ selectEsc close