Skip to content

Contrato — Caderno Online

Contrato — Caderno Online

Status: Implementado Termos: Caderno Online, Artefato do Caderno Online, Atividade Produtiva, Notebook Disciplines View Controller: notebook_api_controller Services: notebook_view_service, notebook_artifact_service, notebook_disciplines_view_service, notebook_autosave_service UC: UC-009 — Caderno Online

Endpoints

Método Path Função
GET /api/v1/platform/study/{enrolment_id}/notebook Lista agrupada por disciplina (legacy, append-only)
GET /api/v1/platform/study/{enrolment_id}/notebook/{artifact_id} Detalhe com content_html completo (legacy)
GET /api/v1/platform/study/{enrolment_id}/notebook/disciplines Index leve por Disciplina (counts)
GET /api/v1/platform/study/{enrolment_id}/notebook/disciplines/{discipline_id}/units Primeira Unidade completa + sumário das demais
GET /api/v1/platform/study/{enrolment_id}/notebook/disciplines/{discipline_id}/units/{unit_id} Drill completo (performance + topics + flashcards)
POST /api/v1/platform/study/{enrolment_id}/notebook/disciplines/{discipline_id}/units/{unit_id}/topics/{topic_id} Autosave do artefato (full ou patch incremental)

Todos exigem Authorization: Bearer {wstoken}. Auth hardening (2026-05-22): todos os endpoints validam explicitamente que enrolment_id pertence ao usuário autenticado — 404 enrolment_not_found em mismatch.

Visão por Disciplina lista apenas Disciplinas/Unidades dos Módulos já atravessados pelo Aluno (study_flow.sort_order ≤ current_module.sort_order). Apenas artefatos de atividades concluídas — Bloco Atual fica no Roteiro. Simulado Escrito não compõe o Caderno.

GET /study/{enrolment_id}/notebook

Lista preview de artefatos, agrupada por disciplina.

Path params

Param Tipo Descrição
enrolment_id integer ID da Matrícula

Response 200

{
  "artifacts_count": 7,
  "disciplines": [
    {
      "id": 5,
      "name": "Direito Constitucional",
      "artifacts": [
        {
          "id": 101,
          "title": "Princípios fundamentais",
          "type": "resumo",
          "preview": "Os princípios fundamentais da CF/88...",
          "updated_at": 1714579200
        }
      ]
    }
  ]
}
Campo Tipo
artifacts_count integer (total cross-disciplinas)
disciplines[].id integer
disciplines[].name string
disciplines[].artifacts[].id integer
disciplines[].artifacts[].title string
disciplines[].artifacts[].type resumo|leitura|reforco|hibrido
disciplines[].artifacts[].preview string (snippet textual)
disciplines[].artifacts[].updated_at integer (Unix timestamp)

Erros

HTTP error Causa
401 unauthorized wstoken ausente/inválido
404 enrolment_not_found Matrícula não pertence ao user

GET /study/{enrolment_id}/notebook/{artifact_id}

Conteúdo completo de um artefato.

Path params

Param Tipo Descrição
enrolment_id integer ID da Matrícula
artifact_id integer ID do artefato

Response 200

{
  "id": 101,
  "type": "resumo",
  "title": "Princípios fundamentais",
  "discipline": { "id": 5, "name": "Direito Constitucional" },
  "unit": { "id": 12, "name": "Princípios fundamentais da CF/88" },
  "content_html": "<h2>Princípios...</h2><p>...</p>",
  "word_count": 1240,
  "status": "notebook",
  "origin": "student",
  "updated_at": 1714579200,
  "source_activity": {
    "slot_id": 8765,
    "session_id": 9032,
    "type": "guided_study",
    "format": "resumo"
  }
}
Campo Tipo
type resumo|leitura|reforco|hibrido
discipline.id integer | null
unit.id integer | null
content_html string (HTML completo)
word_count integer (derivado de strip_tags(content_html))
status current_block|notebook|archived
origin student|helico|merged
updated_at integer (Unix timestamp)
source_activity.slot_id integer | null
source_activity.session_id integer | null
source_activity.type string (tipo da atividade-fonte)
source_activity.format string (formato do artefato gerado)

Erros

HTTP error Causa
401 unauthorized wstoken ausente/inválido
404 artifact_not_found Artefato não existe
404 artifact_not_in_enrolment Artefato existe mas não pertence à matrícula

GET /study/{enrolment_id}/notebook/disciplines

Index leve por Disciplina cobrindo apenas Módulos já atravessados pelo Aluno.

Response 200

{
  "current_module_ordinal": 3,
  "disciplines": [
    {
      "id": 5,
      "name": "Direito Constitucional",
      "units_count": 8,
      "artifacts_count": 7
    }
  ]
}
Campo Tipo Origem
current_module_ordinal integer sort_order do study_flow atual (flow_type='module')
disciplines[].id integer distinct discipline_id dos snapshots
disciplines[].name string unit_snapshot.snapshot_data.discipline_name
disciplines[].units_count integer Unidades atravessadas dessa Disciplina
disciplines[].artifacts_count integer notebook_artifact com visibility_scope='notebook' cobrindo essas Unidades

current_module_ordinal = 0 e disciplines = [] quando o Aluno ainda não iniciou nenhum Módulo.

Erros

HTTP error Causa
401 unauthorized wstoken ausente/inválido
404 enrolment_not_found Matrícula não pertence ao usuário

GET /study/{enrolment_id}/notebook/disciplines/{discipline_id}/units

Detalhe completo da primeira Unidade da Disciplina + sumário das demais.

Response 200

{
  "discipline": { "id": 5, "name": "Direito Constitucional" },
  "first_unit": { /* mesmo shape do drill abaixo */ },
  "other_units": [
    {
      "id": 13,
      "name": "Princípios fundamentais II",
      "order": 2,
      "module_ordinal": 2,
      "level": "intermediate",
      "score": 6.5,
      "source": "svd",
      "has_artifacts": true
    }
  ]
}

first_unit é a primeira Unidade dessa Disciplina na ordem canônica do student_plan.sequence. Pode ser null quando o Aluno ainda não atravessou Unidades dessa Disciplina. other_units[].level é 'basic'|'intermediate'|'advanced' ou null quando não há classificação.

Erros

HTTP error Causa
401 unauthorized wstoken ausente/inválido
404 enrolment_not_found Matrícula não pertence ao usuário
404 discipline_not_in_enrolment Disciplina fora dos Módulos atravessados

GET /study/{enrolment_id}/notebook/disciplines/{discipline_id}/units/{unit_id}

Drill completo de uma Unidade: classificação CDA, performance por simulado (mesmo shape que general_review_performance_view_service entrega no slot/{slot_id}/session para slot RG), tópicos com flags de artifact/anotações, e summary de Flashcards.

Response 200

{
  "discipline": { "id": 5, "name": "Direito Constitucional" },
  "unit": {
    "id": 12,
    "name": "Princípios fundamentais",
    "order": 1,
    "module_ordinal": 1
  },
  "classification": {
    "level": "advanced",
    "score": 8.7,
    "source": "svd",
    "classified_at": null
  },
  "performance": {
    "unit_score": { "latest_truefalse": 8.0, "latest_objective": 7.5, "latest_written": 7.0 },
    "exam_truefalse": [],
    "exam_objective": [],
    "exam_written":   []
  },
  "topics": {
    "total": 8,
    "with_artifact": 3,
    "with_observation": 2,
    "items": [
      {
        "id": 101,
        "title": "Hierarquia das normas",
        "order": 1,
        "has_artifact": true,
        "artifact_id": 555,
        "artifact_type": "resumo",
        "has_observation": true,
        "annotations": [
          {
            "id": 9001,
            "topic_id": 101,
            "annotation_key": "obs_10944568",
            "mark_id": "obs_10944568",
            "color": null,
            "comment": "DSD",
            "note": "DSD",
            "x_pct": 10.25,
            "y_pct": 17.87,
            "created_at": 1714579200,
            "updated_at": 1714579200
          }
        ],
        "preview": "Normas constitucionais ocupam o topo..."
      }
    ]
  },
  "flashcards": {
    "total": 24,
    "reviewed": 18,
    "last_accuracy": 75.0,
    "last_practiced_at": 1779000000
  }
}

classification é null quando ainda não há classificação. topics.items[].has_observation reflete a presença de notebook_annotation reconciliada via lexical_mark_walker (ADR-91). flashcards.last_accuracy e last_practiced_at são null quando a Unidade nunca foi praticada.

topics.items[].annotations[] carrega cada observação/destaque no shape canônico (notebook_annotation::to_api_array):

Campo Tipo Descrição
id integer ID interno da annotation
topic_id integer | null Tópico ao qual pertence
annotation_key string Key do mark no editor_state (mark.ids[]); prefixos hl_/obs_
mark_id string Alias de annotation_key (frontend casa a observação pelo mark)
color string | null Cor do destaque (yellow|green|pink|blue) ou null
comment string Texto da nota
note string Alias de comment
x_pct number | null Posição horizontal do balão sobre o documento (0–100) ou null
y_pct number | null Posição vertical do balão (0–100) ou null
created_at integer Unix timestamp
updated_at integer Unix timestamp

Erros

HTTP error Causa
401 unauthorized wstoken ausente/inválido
404 enrolment_not_found Matrícula não pertence ao usuário
404 discipline_not_in_enrolment Disciplina fora dos Módulos atravessados
404 unit_not_in_enrolment Unidade fora da Disciplina informada ou ainda não atravessada

POST /study/{enrolment_id}/notebook/disciplines/{discipline_id}/units/{unit_id}/topics/{topic_id}

Autosave do artefato de um Tópico fora do fluxo de slot/sessão — edição direta no Caderno Online. Mesmo contrato de autosave do Estudo Dirigido (POST /slots/{slot_id}), porém a identidade vem da rota.

Dois modos, selecionados pelo Content-Type:

Content-Type Modo Comportamento
application/json full editor_state completo + annotations[]. Cria o artifact quando o Tópico não tem um (escopo notebook, status draft, source_type = scenario), ou atualiza preservando identidade e escopo.
application/json-patch+json patch patch_editor_state (JSON Patch) + annotations_delta + base_version. Optimistic concurrency. Exige artifact existente — a criação inicial é sempre via full.

Path params

Param Tipo Descrição
enrolment_id integer ID da Matrícula
discipline_id integer ID da Disciplina
unit_id integer ID da Unidade
topic_id integer ID do Tópico

Request (full)

{
  "action": "autosave",
  "data": {
    "editor_state": { "root": { "type": "root", "children": [] } },
    "annotations": [
      { "id": "obs_10944568", "mark_id": "obs_10944568", "note": "DSD", "x_pct": 10.25, "y_pct": 17.87 }
    ],
    "content_html": "<p>...</p>",
    "scenario": "resumo"
  }
}

content_html e scenario são opcionais. scenario (resumo|leitura|reforco) define o source_type apenas na criação; em update a identidade do artifact existente é preservada. annotations[] aceita o shape de observação posicionada (id/mark_id como key, note como texto, x_pct/y_pct 0–100) — a key continua ancorada num mark.ids[] do editor_state (ADR-91).

Request (patch)

Content-Type: application/json-patch+json:

{
  "action": "autosave",
  "data": {
    "base_version": 3,
    "patch_editor_state": [ { "op": "add", "path": "/root/children/-", "value": { } } ],
    "annotations_delta": { "upsert": [ { "id": "obs_1", "note": "x", "x_pct": 5, "y_pct": 9 } ], "remove": [] }
  }
}

Response 200

Draft consolidado do Tópico (mesmo shape do units[].topics[].draft na sessão de Estudo Dirigido):

{
  "artifact_id": 555,
  "version": 4,
  "status": "draft",
  "editor_state": { "root": { } },
  "editor_state_format": "lexical-json",
  "content_html": "<p>...</p>",
  "annotations": [
    { "id": 9001, "topic_id": 1, "annotation_key": "obs_10944568", "mark_id": "obs_10944568", "color": null, "comment": "DSD", "note": "DSD", "x_pct": 10.25, "y_pct": 17.87, "created_at": 1714579200, "updated_at": 1714579200 }
  ],
  "annotation_count": 1,
  "last_saved_at": 1714579200
}

Erros

HTTP error Causa
401 unauthorized wstoken ausente/inválido
404 enrolment_not_found Matrícula não pertence ao usuário
409 version_conflict (patch) base_version diferente da versão atual (carrega current_version)
409 invalid_patch (patch) sem artifact para aplicar — envie um full save primeiro
422 invalid_editor_state editor_state ausente/inválido ou identidade incompleta
422 invalid_payload Corpo não é JSON válido

Referências

  • Source: classes/extensions/platform/controller/notebook_api_controller.php
  • View services: classes/extensions/platform/service/notebook_view_service.php, classes/extensions/platform/service/notebook_disciplines_view_service.php, classes/extensions/platform/service/unit_topics_view_service.php
  • Autosave service: classes/extensions/platform/service/notebook_autosave_service.php
  • Sequence canon: classes/extensions/engine/plan/service/sequence_units_materializer_service.php
  • Entity: classes/extensions/activity/productive/notebook_artifact/entity/notebook_artifact.php
  • Design: .vigim/content/plans/2026-05-22-notebook-disciplines-view-design.md
  • Test plan: .vigim/content/plans/2026-05-22-notebook-disciplines-view-test-plan.md
  • openapi.yaml
Navigation

Type to search…

↑↓ navigate↵ selectEsc close