Contratos — Platform API
Documentação detalhada por recurso. Cada arquivo cobre:
- Endpoints (método + path)
- Auth
- Request: path/query params, body
- Response: schemas + exemplos reais
- Erros (HTTP +
errorslug + causa) - Invariantes / regras de negócio
- Diagramas (quando aplicável)
Fonte de verdade dos contratos: anotações #[OA] nos controllers
em classes/extensions/platform/controller/. Este texto humaniza
e amplia o que openapi.yaml expõe — não substitui.
Endpoints
| Recurso | Status | Doc |
|---|---|---|
Identidade — /me |
Implementado | me.md |
| Perfil do Usuário | Implementado (feature flag) | perfil.md |
Identidade — /enrolments |
Implementado | enrolments.md |
| Onboarding (questionário) | Implementado (lake) | onboarding.md |
| Roteiro / Estudo | Implementado | study.md |
| Desempenho / Métricas | Implementado | performance.md |
| Simulados — lista | Implementado | exam.md |
| Simulados — detalhe | Implementado | exam.md#detalhe |
| Flashcards | Implementado | flashcard.md |
| Caderno | Implementado | notebook.md |
| Notificações | Mock (pendente domínio) | notification.md |
| Dashboard | Implementado | dashboard.md |
| Retrospectiva de Conclusão | Implementado | retrospective.md |
| Estado de Interface do Aluno | Em implementação | user-state.md |
| Admin — Correção | Implementado | admin/corrections.md |
Como ler
- Status
Implementadosignifica: o controller chama serviço de domínio real; payload reflete dados reais do usuário autenticado e da matrícula. - Status
Mocksignifica: o endpoint retorna payload hardcoded até o serviço upstream ficar pronto. O contrato (shape) é estável mesmo assim — o frontend pode codificar contra o shape; só os valores serão substituídos. - Mudanças de contrato (shape) seguem o processo de ADR + revisão.
Referências cruzadas
- autenticacao.md — login + uso de
wstoken - openapi.yaml — schema OpenAPI gerado de
#[OA] - Postman collection{ :download=“helico-platform.postman_collection.json” } — testes manuais
- UC-001 — Login, UC-002 — Inscrições, UC-003 — Onboarding, UC-004 — Área do Aluno, UC-005 — Roteiro, UC-006 — Detalhe Slot, UC-007 — Desempenho, UC-008 — Simulados, UC-009 — Caderno, UC-010 — Flashcards