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