ADR-90: Domínio Platform — Gateway e Contratos de Tela
Status: Aceito Data: 2026-04-24 Autor: Michael Meneses (Arquiteto)
Contexto
O domínio platform (anteriormente referido como api no discovery) é a camada de interface entre o Backend (Moodle + local_helico) e o Frontend (Plataforma HÉLICO, aplicação NextJS). Ele não possui regras de negócio nem entities persistidas — é um gateway que orquestra chamadas aos domínios de negócio e entrega contratos de tela ao frontend.
A página arquitetura/09-platform.md (Passo 10) já detalha as visões do Aluno. Este ADR consolida a arquitetura formal do gateway: responsabilidades, regras de segurança, estratégia de migração e decisões abertas.
As decisões aqui formalizadas absorvem D-47 a D-50 do BL-009 (API Discovery Review, 2026-03-31). O domínio foi renomeado de api para platform para refletir que é a camada de plataforma (gateway + contratos de tela), não apenas endpoints técnicos.
Natureza do domínio
| Aspecto | Platform |
|---|---|
| Aggregate Roots | Nenhum |
| Tabelas próprias | Nenhuma |
| Item types EAV | Nenhum |
| Persistência | Não persiste — consome e compõe dados de outros domínios |
| Regras de negócio | Não define — delega aos domínios de negócio |
Platform é stateless. Toda a lógica de estado vive nos domínios product, engine, activity e metrics.
Responsabilidades
- Autenticação e autorização — valida tokens Moodle, verifica permissões por Matrícula
- Composição multi-domínio — orquestra chamadas a engine, activity, metrics e content para montar contratos de tela
- Validação de entrada — valida parâmetros antes de delegar ao domínio
- Contrato de resposta — garante shape consistente mesmo com dados parciais (defaults, não omissão)
- Migração incremental — migra endpoints de
external.phppara controllers emextensions/platform/
Telas × Services de orquestração (absorve D-47 + R-03)
| Tela | Service de orquestração | Domínios consumidos |
|---|---|---|
| Área do Aluno | student_area_service |
engine, metrics, product |
| Roteiro de Estudos | study_roadmap_service |
engine, content |
| Flashcards | flashcard_view_service |
activity, content |
| Revisão | review_view_service |
engine, activity |
| Diagnóstico | diagnostic_view_service |
engine, activity |
| Desempenho | performance_view_service |
metrics |
| Simulados | exam_view_service |
activity, engine |
| Biblioteca Online | library_view_service |
content |
| Caderno Online | notebook_view_service |
activity |
| Perfil | profile_view_service |
product, engine |
Cada service de orquestração é stateless — compõe dados dos domínios, aplica formatação de tela e retorna o contrato.
Regras de segurança (absorve D-48)
| # | Regra | Tipo |
|---|---|---|
| 1 | Todo endpoint requer token de autenticação Moodle válido | permissão |
| 2 | Endpoints de leitura validam que userid pertence ao token autenticado | permissão |
| 3 | Gestor acessa apenas dados de alunos vinculados ao seu produto | permissão |
| 4 | Parâmetros validados antes da delegação ao domínio | consistência |
| 5 | Respostas seguem contrato de tela mesmo com dados parciais (defaults, não omissão) | consistência |
Migração incremental (absorve D-49)
Endpoints em classes/external.php serão migrados incrementalmente para controllers em classes/extensions/platform/controller/, mantendo compatibilidade com Moodle External API.
Padrão de nomeação: {tela}_{operacao} (ex: student_area_get_courses, study_roadmap_get_modules)
Estratégia:
- Novo endpoint criado em controller (extensions/platform/)
external.phpredirecionado para o novo controller (proxy)- Frontend atualizado para chamar novo endpoint
- Proxy removido quando frontend migrado
Decisões abertas registradas (absorve D-50)
| # | Item | Tipo | Status |
|---|---|---|---|
| 1 | Composição multi-domínio: no controller ou em service de orquestração? | decisão validada | Service de orquestração (tabela acima). Controller delega. |
| 2 | Endpoints de escrita: na API ou expostos diretamente pelos domínios? | decisão futura | Submissão de respostas, início de sessão — tratar por tela |
| 3 | Versionamento de contratos de API | decisão futura | Estratégia a definir quando frontend estabilizar |
| 4 | Estratégia de cache entre API e domínios | decisão futura | Afeta performance — tratar quando métricas de uso existirem |
Consequências
- Domínio platform especificado como gateway stateless — sem ARs, sem tabelas, sem EAV
- Rename
api→platformreflete melhor o papel de camada de plataforma - 10 services de orquestração mapeados por tela
- 5 regras de segurança formalizadas
- Migração incremental de external.php especificada
- Composição multi-domínio resolvida: services de orquestração, não controllers
- Endpoints de escrita ainda não especificados por tela
- Versionamento de API adiado
- Cache strategy adiada
ADRs relacionados
- ADR-01 — Separação de responsabilidades (platform é camada de interface, não de negócio)
- ADR-50 — Domínio Product (consumido pela Área do Aluno, Perfil)
- ADR-60 — Domínio Engine (consumido pelo Roteiro, Diagnóstico, Simulados)
- ADR-70 — Domínio Metrics (consumido pelo Desempenho)
- ADR-80 — Domínio Activity (consumido por Flashcards, Revisão, Caderno Online)
Histórico
| Data | Evento |
|---|---|
| 2026-04-24 | Criado — consolida decisões da sessão 15 + absorve BL-009 D-47..D-50 + R-03 |