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 slotDetalhamento 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/jsonRequest 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-rotastudy-guideredundante - 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:
resultem 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:
/resultsendpoint separado para histórico detalhado cross-blocos