Skip to content

UC-005: Roteiro de Estudos

UC-005: Roteiro de Estudos

Status: EM REVISÃO Data: 2026-04-29 Domínio: platform / engine.plan Ator: Aluno Terms: Roteiro de Estudos, Fluxo Atual, Bloco Atual, Módulo, Etapa, Bloco CDA, Sequência do Plano de Estudo, Plano do Aluno, Atividade, Status do Bloco de Estudo, Status do Fluxo de Estudo

Contexto

O Roteiro de Estudos é a visão principal de execução do Aluno. Sempre exibe o Bloco Atual do Fluxo Atual. Atividades específicas são acessadas via sub-rota (/roteiro-de-estudos/{slot_id}).

Arquitetura de slots: O Motor de Execução pré-gera slots quando processa o Fluxo Atual. Cada slot é uma posição pré-alocada para uma atividade. Garante idempotência — atividade não pode ser submetida duas vezes porque o slot já existe antes da submissão.

Módulos dinâmicos: Não é possível listar módulos futuros — são gerados quando o current é fechado. A resposta mostra apenas o fluxo/bloco/etapa atuais.

Endpoints

GET  /platform/study/{enrolment_id}                        → Roteiro (bloco atual + slots + result agregado)
GET  /platform/study/{enrolment_id}/results                → Resultados detalhados (histórico)
POST /platform/study/{enrolment_id}/slots/{slot_id}        → Submeter atividade no slot

Detalhamento de atividades individuais (/roteiro-de-estudos/{slot_id}) em anexo: uc-005-anexo-atividades.md.

GET /platform/study/{enrolment_id} — Roteiro

GET /platform/study/{enrolment_id}
Authorization: Bearer {wstoken}

Resposta:

{
  "current_flow": {
    "id": 10,
    "name": "Módulo 1",
    "type": "regular",
    "context": {}
  },
  "current_block": {
    "id": 15,
    "type": "cda",
    "name": "Bloco CDA",
    "status": "in_progress",
    "context": {
      "phase": "post_di_activities",
      "di": { "completed": true, "score": 72 },
      "svd": { "available": false }
    }
  },
  "stage": {
    "id": 1,
    "name": "Etapa 1",
    "modules_completed": 0,
    "modules_total": 4
  },
  "plan": {
    "disciplines": [
      {
        "id": 5,
        "name": "Direito Constitucional",
        "units": [
          { "id": 101, "name": "Controle de Constitucionalidade", "order": 1 },
          { "id": 102, "name": "Direitos Fundamentais", "order": 2 },
          { "id": 103, "name": "Organização do Estado", "order": 3 }
        ]
      },
      {
        "id": 8,
        "name": "Direito Penal",
        "units": [
          { "id": 201, "name": "Teoria do Crime", "order": 1 },
          { "id": 202, "name": "Penas", "order": 2 }
        ]
      }
    ]
  },
  "result": {
    "slots_total": 8,
    "slots_completed": 3,
    "slots_in_progress": 1,
    "slots_locked": 4,
    "slots_skipped": 0,
    "slots_dispensed": 0,
    "completion_percentage": 37,
    "time_spent_minutes": 120,
    "last_activity_at": "2026-04-28T14:30:00Z"
  },
  "slots": [
    {
      "id": "550e8400-0001-0000-0000-000000000001",
      "order": 1,
      "type": "diagnostic_initial",
      "status": "completed",
      "label": "Diagnóstico Inicial",
      "scope": [
        { "type": "discipline", "id": 5, "name": "Direito Constitucional" }
      ],
      "context": {},
      "result": {
        "level": "intermediario",
        "score": 72,
        "completed_at": "2026-04-25T14:30:00Z"
      },
      "locked": null,
      "action": null
    },
    {
      "id": "550e8400-0001-0000-0000-000000000002",
      "order": 2,
      "type": "guided_study",
      "status": "in_progress",
      "label": "Resumo — Controle de Constitucionalidade",
      "scope": [
        { "type": "discipline", "id": 5, "name": "Direito Constitucional" },
        { "type": "unit", "id": 101, "name": "Controle de Constitucionalidade" }
      ],
      "context": {
        "format": "summary"
      },
      "result": null,
      "locked": null,
      "action": {
        "type": "navigate",
        "label": "Continuar",
        "route": "/roteiro-de-estudos/550e8400-0001-0000-0000-000000000002"
      }
    },
    {
      "id": "550e8400-0001-0000-0000-000000000003",
      "order": 3,
      "type": "guided_study",
      "status": "not_started",
      "label": "Leitura — Direitos Fundamentais",
      "scope": [
        { "type": "discipline", "id": 5, "name": "Direito Constitucional" },
        { "type": "unit", "id": 102, "name": "Direitos Fundamentais" }
      ],
      "context": {
        "format": "reading"
      },
      "result": null,
      "locked": null,
      "action": {
        "type": "navigate",
        "label": "Começar",
        "route": "/roteiro-de-estudos/550e8400-0001-0000-0000-000000000003"
      }
    },
    {
      "id": "550e8400-0001-0000-0000-000000000004",
      "order": 4,
      "type": "diagnostic_verify",
      "status": "locked",
      "label": "SVD — Direito Constitucional",
      "scope": [
        { "type": "discipline", "id": 5, "name": "Direito Constitucional" }
      ],
      "context": {},
      "result": null,
      "locked": {
        "reason": "prerequisite",
        "message": "Conclua as atividades pós-DI primeiro.",
        "depends_on": [
          "550e8400-0001-0000-0000-000000000002",
          "550e8400-0001-0000-0000-000000000003"
        ],
        "unlock_rule": "all_completed"
      },
      "action": null
    }
  ]
}

Estrutura do Slot (padronizada, agnóstica)

Todos os slots seguem a mesma forma, independente do tipo de atividade:

Campo Tipo Descrição
id UUID Identificador único, pré-gerado. Garante idempotência
order int Ordem no bloco
type string Tipo de atividade (agnóstico)
status string not_started, in_progress, completed, locked, skipped, dispensed
label string Nome visível para o Aluno
scope array Referências flexíveis (discipline, unit, ou ambos, ou múltiplos)
context object Dados específicos do tipo. Aninhamento livre (objetos encadeados conforme necessidade)
result object|null Presente quando completed. Conteúdo varia por type
locked object|null Presente quando locked
action object|null Presente quando acionável

scope — Referências flexíveis

scope: [{ type: "discipline"|"unit", id: int, name: string }]

Exemplos:

  • DI: [{ discipline }]
  • Resumo/Leitura: [{ discipline }, { unit }]
  • Simulado Objetivo: [{ discipline }, { discipline }, { discipline }]
  • Revisão Geral: [{ unit }, { unit }, { unit }]

context — Aninhamento livre

Objeto livre com aninhamento conforme necessidade:

// guided_study
{ "format": "summary", "instruction": "Resuma os pontos principais." }

// diagnostic_initial
{
  "questions_count": 20,
  "time_limit_minutes": 30,
  "segments": {
    "di": { "questions": 10 },
    "svd": { "questions": 10 }
  }
}

// exam_written
{
  "submission": {
    "deadline": "2026-05-15T23:59:00Z",
    "max_pages": 5,
    "formats_accepted": ["pdf", "docx"]
  }
}

locked — Granularidade

Campo Tipo Descrição
reason string prerequisite, progression, availability, dispensed
message string Texto legível para o Aluno
depends_on UUID[]|null Slots que precisam ser concluídos
unlock_rule string|null all_completed, any_completed, scheduled
unlock_at datetime|null Para availability/scheduled

result — Dois níveis

Raiz (result top-level): progresso agregado do bloco atual.

Campo Tipo
slots_total int
slots_completed int
slots_in_progress int
slots_locked int
slots_skipped int
slots_dispensed int
completion_percentage int
time_spent_minutes int
last_activity_at datetime|null

Slot (slot.result): resultado individual. Estrutura varia por type — detalhado no anexo.

GET /platform/study/{enrolment_id}/results — Histórico

GET /platform/study/{enrolment_id}/results
Authorization: Bearer {wstoken}

Resposta:

{
  "summary": {
    "total_time_minutes": 480,
    "blocks_completed": 2,
    "blocks_total": 12,
    "overall_score": 68,
    "last_activity_at": "2026-04-28T14:30:00Z"
  },
  "blocks": [
    {
      "block_id": 14,
      "block_type": "cda",
      "flow_name": "Módulo 1",
      "status": "completed",
      "completed_at": "2026-04-20T16:00:00Z",
      "slots": [
        {
          "slot_id": "550e8400-0000-0000-0000-000000000001",
          "type": "diagnostic_initial",
          "label": "DI — Direito Constitucional",
          "status": "completed",
          "result": {
            "level": "intermediario",
            "score": 72,
            "completed_at": "2026-04-18T10:00:00Z"
          }
        }
      ]
    }
  ]
}

POST /platform/study/{enrolment_id}/slots/{slot_id} — Submissão

POST /platform/study/{enrolment_id}/slots/{slot_id}
Authorization: Bearer {wstoken}
Content-Type: application/json

Request body padronizado:

{
  "action": "submit",
  "data": { }
}

Resposta:

{
  "success": true,
  "slot": {
    "id": "550e8400-0001-0000-0000-000000000002",
    "status": "completed",
    "result": {
      "score": 85,
      "completed_at": "2026-04-29T15:00:00Z"
    }
  },
  "effects": [
    { "type": "slot_unlocked", "slot_id": "550e8400-0001-0000-0000-000000000004" },
    { "type": "block_progress", "completion_percentage": 50 }
  ]
}

effects[] informa ao Frontend o que mudou como consequência da submissão.

Erros esperados

HTTP Código Situação
401 unauthorized Token inválido ou expirado
404 enrolment_not_found Matrícula não encontrada
404 slot_not_found Slot não existe
409 slot_already_completed Slot já foi submetido (idempotência)
409 slot_locked Tentativa de submeter slot travado
422 validation_error Dados de submissão inválidos

Decisões

  • D-01: /study/{enrolment_id} É o Roteiro — sem sub-rota study-guide redundante
  • D-02: Slots pré-gerados pelo Motor de Execução — idempotência garantida por UUID
  • D-03: Slot agnóstico: campos fixos (id, order, type, status, label, scope, context, result, locked, action)
  • D-04: scope[] flexível: discipline, unit, ambos, múltiplos — array de referências tipadas
  • D-05: context{} aninhamento livre com objetos encadeados conforme necessidade
  • D-06: result em dois níveis: raiz (agregado do bloco) e slot (individual)
  • D-07: effects[] na resposta do POST informa consequências da submissão
  • D-08: Módulos futuros invisíveis — dinâmicos, gerados ao fechar current
  • D-09: Detalhamento de atividades em anexo separado (uc-005-anexo-atividades.md)
  • D-10: /results endpoint separado para histórico detalhado cross-blocos
Navigation

Type to search…

↑↓ navigate↵ selectEsc close