Plano — Documentação Completa da Platform API
Status: PARTIALLY IMPLEMENTED — F0 + F1 + F2 + F3 + F4 + F5a + F5b + F7-infra entregues 2026-05-04. F6 parcial (3/6 wirados). T2 + T3 + 3 controllers mock pendentes.
Data: 2026-05-04
Branch: feature/new-contracts
Autor: Gabriel Sousa
Domínio: platform (docs/plataforma/, classes/extensions/platform/)
1. Contexto
A Platform API expõe os endpoints consumidos pelo Frontend NextJS HÉLICO. Hoje:
- Frontend está iniciando integração e precisa de contratos estáveis e documentados.
docs/plataforma/api-integracoes/autenticacao.mdestá como stub (“Em construção”).docs/plataforma/api-integracoes/openapi.yamltemservers.url: /webservice/restful/server.php— incorreto (entry real é/local/helico/ajax.php/).composer build:openapiscript existe mas tem--server-urlapontando para o legacy.- Postman collection (
docs/_archive/helico-onboarding-flow.postman_collection.json) usa cookie sessão Moodle (POST /login/index.php) — desalinhada de UC-001 (docs/operacao/uc-001-login.md, EM REVISÃO 2026-04-29). - BASE_PATH dos 12 controllers
helico/api/v1/platform/*resulta em URL comhelico/redundante. - 6 controllers retornam dados mockados (TODOs).
- Não há testes de contrato.
- Vocabulário canônico (
.vigim/ddd/terms/) temAPI REST HÉLICOmas faltaMétodo de Logine variantes.
A entrega tem que ser suficiente para o time de Frontend desenvolver sem perguntar.
2. Objetivo
Estabilizar e documentar contratos da Platform API com qualidade de entrega, alinhando código → OpenAPI → Postman → docs MkDocs → terms canônicos. Garantir que o que está documentado é o que é retornado (testes contract com data generator + JsonSchema).
3. Decisões de escopo (D-series e revisão /plan-eng-review)
Decisões de escopo (D)
| ID | Decisão | Motivo |
|---|---|---|
| D1 | BASE_PATH muda de helico/api/v1/platform para api/v1/platform |
Remove redundância. URL final: /local/helico/ajax.php/api/v1/platform/*. |
| D2 | Login email+senha via Moodle nativo (POST /login/token.php); login social/Google via MIDDAG (POST /local/middag/api/auth/login) |
Alinha a UC-001. Doc-first: documentar como se MIDDAG já retornasse wstoken; backend MIDDAG implementa para bater com contrato. |
| D3 | Authorization: Bearer <token> e ?wstoken=<token> documentados como equivalentes |
Mantém UC-001. Sem prescrição editorial. |
| D4 | Postman collection reescrita completa, alinhada a D1+D2+D3 | É o artefato mais prático para o frontend testar. |
| D5 | Escopo lake completo: doc + refactor BASE_PATH + contratos detalhados + testes contract + fechar TODOs lógica negócio | AI compressa custo de completeness. |
Revisão /plan-eng-review 2026-05-04
| ID | Decisão | Resumo |
|---|---|---|
| A1 | Aceita risco frontend | Frontend NextJS ainda não em produção; sem coordenação prévia, deploy direto. |
| A2 | F6 (TODO real data) bloqueia F4 (contratos.md) por endpoint | Garante exemplos com payload real, não mock. |
| A3 | Stack de testes: PHPUnit + justinrainbow/json-schema + plugin generator (tests/generator/lib.php) |
Foundation reutilizável. |
| A4 | Fix composer.json:build:openapi --server-url=/local/helico/ajax.php antes de regenerar |
Corrige fonte do bug. |
| A5 | Mover Postman de _archive/ para docs/plataforma/api-integracoes/postman/ |
Caminho semântico correto. |
| CQ1 | #[OA] path: usa '/' . self::BASE_PATH . '/...' (mesmo concat do #[Route]) |
Const única fonte de verdade. |
| CQ2 | Adicionar só Método de Login (com subterms Email/Senha, Social) em terms-platform.yaml. wstoken e detalhes técnicos ficam apenas em autenticacao.md |
Evita poluir glossário canônico com detalhes de implementação. |
| CQ3 | Doc-first MIDDAG: autenticacao.md documenta resposta MIDDAG como se já retornasse wstoken |
Contrato definido pressiona implementação. Sem workaround documentado. |
| T1 | IRON RULE: smoke test obrigatório regression — request 1 endpoint por controller via path novo, valida 2xx/4xx esperado | Previne quebra silenciosa em F1. |
| T2 | Idempotência em onboarding submit + teste de race | Race em fluxo crítico de criação de Plano. |
| T3 | student_plan.status='failed' visível em /enrolments quando handler async falhar; frontend mostra erro + retry |
Evita loop infinito de polling. |
| P1 | Documentar contrato de polling (intervalo mínimo 2s, backoff exponencial até 30s, max 60 tentativas) + rate limit servidor por user | Defesa em camada. |
| P2 | Apenas documentar perf esperada nos contratos (sem assert query budget no CI) | Risco N+1 em prod aceito; revisitar se incidente. |
4. NÃO faz parte do escopo
- Implementação de SSO Google novo (já existe).
- Reformulação do schema de banco para suportar dados reais nos endpoints com mock (presume-se que o domínio já tem o que precisa).
- Frontend NextJS (consumidor) — fora do repositório.
- APM / observabilidade externa (Tideways/NewRelic) — perf monitoring delegado a iniciativa futura (P2).
- Mover endpoints para REST nativo Moodle (
/webservice/restful/server.php) — ajax.php delegando a MIDDAG é a arquitetura aprovada (ADR-90). - Feature flags ou strangler fig para deprecation do BASE_PATH antigo — A1 aceita risco direto.
- Pact/Dredd consumer-driven contracts — A3 escolheu json-schema.
- Glossário técnico paralelo para detalhes de implementação (wstoken, Bearer, etc.) — CQ2 mantém só conceitos editorialmente relevantes.
5. O que já existe e vamos reutilizar
| Artefato | Estado | Uso no plano |
|---|---|---|
docs/operacao/uc-001-login.md |
EM REVISÃO | Fonte canônica para autenticacao.md. |
docs/plataforma/adrs/ref/ref-30-e_contract-specifications.md |
Vivo | Padrão de documentação de contratos por domínio. |
classes/extensions/platform/controller/*.php com #[OA] |
12 controllers anotados | Anotações inline ficam, só ajusta paths via CQ1. |
composer.json:build:openapi |
Existe, com bug em --server-url |
A4 corrige; passa a ser comando oficial. |
composer.json:build:docs:glossary |
Existe | Regenera glossário após CQ2. |
local_middag\base\api_controller |
Estável | Refactor BASE_PATH não toca. |
terms-platform.yaml (com API REST HÉLICO já definido) |
Vivo | CQ2 adiciona só Método de Login + subterms. |
docs/plataforma/arquitetura/09-platform.md + ADR-90 |
Vivo | Não toca; só linka. |
| Postman test scripts existentes (estrutura, asserts) | Vivo | D4 reaproveita estrutura; auth + paths reescritos. |
6. Mudanças propostas — fases
PARALLEL LANES (após F1 mergeado)
│
├── Lane A (foundational, sequencial dentro):
│ F1 [smoke test T1] → F2 → F5a → F5b
│
├── Lane B (independente, paralelo a Lane A):
│ F3 (.vigim/ddd/terms — vocabulário canônico, CQ2)
│
├── Lane C (depende de F1 + plugin generator):
│ F6 paralelo entre 6 controllers (cada um story)
│
├── Lane D (depende de F1 + Lane C por endpoint):
│ F4 contratos.md por endpoint (bloqueado pelo F6 daquele endpoint, A2)
│
└── Lane E (depende de F1 + plugin generator + endpoints estáveis):
F7 testes contract (golden + JsonSchema, A3)Fase 0 — Preparação
- F0.1 Fix
composer.jsonbuild:openapi:--server-url=/local/helico/ajax.php(A4). - F0.2 Validar com time MIDDAG plano de implementar wstoken na resposta de
/local/middag/api/auth/login(CQ3 doc-first). - F0.3 Plugin generator esqueleto:
tests/generator/lib.phpcomlocal_helico_generator extends component_generator_base. Stubs vazios (preenchidos sob demanda em F7).
Fase 1 — Refactor BASE_PATH (foundation, IRON regression)
Toca: 12 controllers + qualquer fixture/test que referencie path velho.
Arquivos:
me_api_controller.phponboarding_api_controller.phpenrolment_api_controller.phpexam_api_controller.phpstudy_api_controller.phpslot_api_controller.phpdashboard_api_controller.phpflashcard_api_controller.phpnotebook_api_controller.phpnotification_api_controller.phpperformance_api_controller.phpadmin/exam_correction_controller.php
Mudanças (CQ1):
-public const BASE_PATH = 'helico/api/v1/platform';
+public const BASE_PATH = 'api/v1/platform';
# Em cada #[OA\Get/Post]:
-#[OA\Get(path: '/helico/api/v1/platform/me', ...)]
+#[OA\Get(path: '/' . self::BASE_PATH . '/me', ...)]Para controllers com BASE_PATH específico (...platform/study, ...platform/admin/corrections), mesma regra: remove helico/ prefix, mantém sub-path.
T1 — Smoke test regression (IRON RULE):
- Arquivo novo:
tests/regression/platform_routes_test.php. - Para cada controller, faz
$_SERVER['PATH_INFO'] = '/api/v1/platform/<endpoint>'+middag::handle()e valida que rota resolve (status code esperado, não 404). - Roda em CI bloqueando merge se path velho estiver linkado em algum lugar.
Checklist Fase 1:
-
grep -r 'helico/api/v1/platform' classes/retorna zero ocorrências. -
grep -r 'helico/api/v1/platform' docs/retorna apenas histórico/changelog (não contratos vivos). -
composer build:openapiregenera yaml com paths novos. - Smoke test T1 passa (todos endpoints respondem em path novo).
Fase 2 — Auth doc completa (autenticacao.md)
Reescrever docs/plataforma/api-integracoes/autenticacao.md. Estrutura:
# Autenticação
Status: EM REVISÃO
Termos: API REST HÉLICO, Método de Login, Permissão, Perfil do Sistema
## Visão geral
[diagrama ASCII do fluxo: login → token → uso → refresh/logout]
## Cenário 1: Login email + senha (Moodle nativo)
- Endpoint: POST /login/token.php?service=moodle_mobile_app
- Body: form-encoded username + password
- Response 200: { token, privatetoken }
- Response 4xx: { error, errorcode } com tabela
- Exemplo cURL completo
- Quando usar: web app, mobile, qualquer cliente que coleta credenciais
## Cenário 2: Login social/SSO (MIDDAG)
- Endpoint: POST /local/middag/api/auth/login
- Body: JSON { provider, code|idtoken }
- Response 200: { token, user: { id, fullname, email, avatar_url } }
- Response 4xx: tabela de erros
- Exemplo cURL completo
- Quando usar: Google, Microsoft (futuro), qualquer SSO
- (CQ3 doc-first: contrato define wstoken na resposta — backend MIDDAG implementação em andamento)
## Uso do token nas requisições
- `Authorization: Bearer <wstoken>` (padrão web)
- `?wstoken=<token>` na query string (alternativa)
- Comportamento idêntico no backend; cliente escolhe baseado em contexto
- AVISO: ambas opções enviam segredo — proteger logs/referrer no cliente
## Erros
[tabela HTTP+code+causa+ação]
## Polling (P1)
- Após onboarding submit, frontend pollea /api/v1/platform/enrolments
- Contrato: intervalo mínimo 2s, backoff exponencial até 30s, max 60 tentativas
- Backend rate limit: 30 req/min/user em /enrolments
- Após max, frontend mostra erro de timeout
## Fluxo end-to-end
[diagrama ASCII: cliente → login → token → /me → /enrolments → onboarding/área-aluno]
## Referências
- UC-001 (operação)
- ADR-90 (arquitetura platform)
- OpenAPI / Postman collectionFase 3 — Vocabulário canônico (lane B paralela)
Editar terms-platform.yaml adicionando (CQ2):
-
term: 'Método de Login'
identifier: login_method
short: 'Modalidade pela qual um Perfil do Sistema autentica e adquire wstoken para consumir a API REST HÉLICO.'
long: 'Modalidade pela qual um Perfil do Sistema realiza autenticação na Plataforma HÉLICO. Cada modalidade resulta em um wstoken vinculado à sessão do Aluno ou Gestor, que passa a ser usado em chamadas subsequentes à API REST HÉLICO.'
type: technical_component
domain: platform
parent: 'API REST HÉLICO'
subterms:
- 'Login Email/Senha'
- 'Login Social'
see_also:
- 'Permissão'
- 'Perfil do Sistema'Subterms Login Email/Senha e Login Social ficam embutidos no termo agregador (não criam entradas separadas no glossário, pelo schema atual).
Após editar:
composer build:docs:glossary- Validar
docs/glossary/index.mdlista termo novo.
Fase 4 — Contratos detalhados por endpoint (bloqueado por F6 daquele endpoint, A2)
Criar docs/plataforma/api-integracoes/contratos/<resource>.md:
me.md(após F6.me)enrolments.mdonboarding.md← prioritário, qualidade lakestudy.md(slots, performance)exam.md(após F6.exam)flashcard.md(após F6.flashcard)notebook.mdnotification.md(após F6.notification)dashboard.md(após F6.dashboard)admin/corrections.md
Cada página:
- Endpoint (método + path novo D1=B)
- Auth requerida
- Path/query params
- Request body schema + exemplo JSON real
- Response 200 schema + exemplo JSON real (não mock — A2)
- Tabela de erros
- Invariantes (citando termos canônicos)
- Diagrama ASCII para fluxos com estado
- Cross-link para terms.yaml e UCs
Para onboarding.md especificamente (lake total):
- Estrutura step (info vs question)
- Tipos input (multi_select, single_select, slider) com exemplos cada
label_template+inputs[]embarcados (renderização inline)- Heterogeneidade
valueemanswers[] - Fluxo assíncrono pós-submit (
student_plan = {id: null, status: "creating"}) → polling em/enrolments - T3: estado
failedvisível, retry button - T2: idempotência (mesma resposta para submit duplicado)
- Fases (general → complement) com diagrama de estados
- Erros 422 com array
errors[](step_key + field + message)
Fase 5 — OpenAPI + Postman
F5a — OpenAPI:
composer build:openapi(já corrigido em F0.1).- Adicionar securitySchemes manualmente (ou via PR no MIDDAG CLI):
components: securitySchemes: BearerAuth: type: http scheme: bearer WstokenQuery: type: apiKey in: query name: wstoken security: - BearerAuth: [] - WstokenQuery: [] - Atualizar
openapi.mdse houver narrativa.
F5b — Postman (D4=A + A5):
- Criar
docs/plataforma/api-integracoes/postman/helico-platform.postman_collection.json. - Apagar
docs/_archive/helico-onboarding-flow.postman_collection.json(substituído). - Pasta
0. Authcom 2 sub-requests:POST /login/token.php(Moodle nativo) — body form-encoded username + password + service=moodle_mobile_app. Test script gravawstoken.POST /local/middag/api/auth/login(social) — body JSON. Test script gravawstoken+ atributos user.
- Variáveis Postman:
{{wstoken}},{{api_prefix}}=/local/helico/ajax.php/api/v1/platform,{{base_url}}. - Cada request usa
Authorization: Bearer {{wstoken}}no header. Variante URL param documentada na descrição. - Reorganização: 0.Auth → 1.Identidade → 2.Onboarding → 3.Roteiro → 4.Atividade → 5.Métricas → 6.Admin Correção.
- Cada request com descrição (input/output/quando-usar).
Fase 6 — Fechar TODOs em controllers (mocks → dados reais)
Cada um vira história individual, paralelizáveis entre si:
| Story | Arquivo | Linha | Critério aceite | Bloqueia F4 do endpoint |
|---|---|---|---|---|
| F6.me | me_api_controller.php |
79 | Retorna id/fullname/email/avatar_url do usuário autenticado | F4.me |
| F6.exam-list | exam_api_controller.php |
128 | Lista exam slots da matrícula com status real | F4.exam |
| F6.exam-detail | exam_api_controller.php |
266 | Detalhe slot+sessão+questões reais | F4.exam |
| F6.dashboard | dashboard_api_controller.php |
85 | Métricas reais via metrics domain | F4.dashboard |
| F6.notification | notification_api_controller.php |
120 | Notificações reais do usuário | F4.notification |
| F6.flashcard | flashcard_api_controller.php |
121 | Flashcards do dia (engine flashcard) | F4.flashcard |
Cada uma:
- Identificar service que provê dados (provavelmente já existe em
extensions/platform/service/ou domínios upstream). - Wire DI no controller.
- Validar payload retornado bate com
#[OA]declarado. - Plugin generator ganha helpers necessários para teste contract (Fase 7).
T2 (idempotência onboarding submit) entra como história F6.onboarding-idempotent:
- Implementar lock por
enrolment_idemonboarding_service::submit. - Submit duplicado retorna mesmo resultado (não emite signal duas vezes).
- Teste de race: 2 POSTs simultâneos → ambos retornam mesmo payload, signal emitido 1x.
T3 (async student_plan failure visible) entra como F6.async-failure:
- Handler async catch exception →
student_plan.status = 'failed'+error_message. enrolment_api_controllerretorna esse status em/enrolments.- Onboarding submit response inclui novo enum
creating | failed. - Frontend renderiza estado de erro com retry button (re-emit signal).
Fase 7 — Testes contract (lane E, A3)
Estabelecer infraestrutura definitiva:
- Lib:
composer require --dev justinrainbow/json-schema. - Local:
tests/contract/platform/<resource>_test.php. - Helper base:
tests/contract/platform/base_contract_test.phpcom métodoassert_matches_openapi(string $path, string $method, $response_status, array $response_body):- Lê
openapi.yaml. - Resolve schema do response para
path+method+status. - Valida
$response_bodycontra schema. - Falha descritiva.
- Lê
- Plugin generator (F0.3) preenchido sob demanda — cada teste cria seus próprios dados (User + Enrolment + StudentPlan + Slot + …) via generator.
- Cada teste: (a) cria dados via generator, (b) login via API real, (c) request endpoint, (d)
assert_matches_openapi. - CI gate: contract test obrigatório para todo endpoint listado em
openapi.yaml.
Ordem de implementação (segue F6):
- Endpoints estáveis (não-mock): onboarding, enrolments, study, slots, performance, admin corrections.
- Endpoints após F6 fechar TODO: me, exam, dashboard, notification, flashcard.
7. Diagramas
7.1 Fluxo de autenticação (alto nível)
┌──────────────────┐
│ Frontend NextJS │
└────────┬─────────┘
│
▼
tipo de login?
│
┌─────┴─────┐
│ │
▼ ▼
email+senha social/SSO
│ │
▼ ▼
┌─────────────────────────────────┐ ┌─────────────────────────────────┐
│ Cenário 1: Moodle nativo │ │ Cenário 2: MIDDAG (social) │
│ POST /login/token.php │ │ POST /local/middag/api/auth/ │
│ ?service=moodle_mobile_app │ │ login │
│ form: username, password │ │ JSON: { provider, code|idtoken }│
└────────────┬────────────────────┘ └────────────┬────────────────────┘
│ │
▼ ▼
200 { token, privatetoken } 200 { token, user{id,fullname,...} }
│ │
└──────────────────┬────────────────────┘
▼
┌───────────────────────────────────┐
│ Authorization: Bearer <wstoken> │
│ OR query: ?wstoken= │
└────────────┬──────────────────────┘
▼
┌───────────────────────────────────┐
│ /local/helico/ajax.php/ │
│ api/v1/platform/* │
│ /local/middag/api/* │
└───────────────────────────────────┘7.2 Fluxo Onboarding (questionário) — máquina de estados
POST /onboarding/{id}/submit (general)
answers: [...]
│
▼
[pending_general] ──────────► [pending_complement] ──────────► [completed]
│ │ │
│ GET │ GET │ GET 409
▼ ▼ ▼
200 OK steps general 200 OK steps complement onboarding_already_completed
Erros submit:
422 validation_error → answers fora de schema/limite
404 enrolment_not_found
401 unauthorized
409 onboarding_already_completed (se submit em fase concluída)
Idempotência (T2):
Lock por enrolment_id durante submit. Submit duplicado retorna mesmo
payload, signal emitido 1x.
Pós-conclusão (completed):
response: { student_plan: { id: null, status: "creating" } }
async signal → engine/plan/student_plan_service::create_for_enrolment
│
├── handler success: student_plan = { id: 42, status: "active" }
│ Frontend redireciona para Roteiro
│
└── handler failure (T3):
student_plan = { id: null, status: "failed", error_message: "..." }
Frontend mostra erro + botão "Tentar de novo" → re-emit signal
Polling de /enrolments (P1):
intervalo mínimo 2s, backoff exp até 30s, max 60 tentativas.
Backend rate limit 30 req/min/user.7.3 Estrutura entre artefatos da doc
docs/operacao/uc-001-login.md ───────┐
│ canon source
docs/plataforma/api-integracoes/ │
autenticacao.md ◄─────────────────┤
openapi.yaml ◄────── #[OA] ◄── classes/extensions/platform/controller/*.php
openapi.md │ ▲
contratos/<resource>.md ◄──────────┤ │
postman/helico-platform.json ◄─────┘ │
│
.vigim/ddd/terms/terms-platform.yaml ──── linkado ──┤
(canon vocab + Método de Login CQ2) │
│
tests/contract/platform/<resource>_test.php ────────┘
(valida response body contra openapi.yaml schema)8. Failure modes (codepath × cobertura × handling)
| Endpoint/Codepath | Falha plausível | Coberto por teste? | Tratado? | Visível ao user? |
|---|---|---|---|---|
| Login Moodle nativo | Service moodle_mobile_app não habilitado |
T1 smoke + F7 | Sim (errorcode em response) | Sim |
| Login MIDDAG social | MIDDAG retorna sem token (estado atual, durante CQ3) | F7 quando MIDDAG implementar | NÃO durante transição — autenticacao.md documenta contrato futuro | Frontend pode quebrar até MIDDAG implementar |
| Bearer + URL param simultâneos | Conflito qual prevalece | NÃO (gap aceito) | Comportamento implícito | Erro confuso |
| Onboarding submit duplicado | Race → dois plans criados | T2 cobre | T2 fix com lock | Sim, idempotente |
| Onboarding submit final | Async student_plan creation falha | T3 cobre | T3 fix com status=‘failed’ | Sim, retry visível |
| Endpoints com mock (6) | Bate em mock, retorna fake | F7 após F6 | F6 troca por dados reais | — |
| Endpoint após F6 com N+1 invisível | Lentidão em prod | NÃO (P2 risco aceito) | NÃO | Sim, latência |
| Polling de /enrolments abusivo | Stampede em prod | F7 cobre rate limit | P1 fix com rate limit | Frontend recebe 429 |
Lacunas críticas remanescentes (sem teste E sem error handling E silencioso):
- F1: Login MIDDAG durante transição CQ3 — backend não retorna token até MIDDAG implementar. Mitigação: comunicação direta com time MIDDAG (F0.2).
- F2: Bearer+URL token simultâneos — comportamento não definido. Adicionar TODO: validar precedência no
local_middagmiddleware e documentar.
9. Plano de testes
Fase 1 (BASE_PATH + smoke regression T1)
grep -r 'helico/api/v1/platform' classes/→ zero ocorrências.tests/regression/platform_routes_test.php(T1 IRON RULE) — todos endpoints respondem path novo.- Postman antigo com path velho retorna 404.
Fase 2 (autenticacao.md)
- Validar links internos (
mkdocs serve). - Lint markdown.
- Cross-check com UC-001: mesmo conteúdo de fluxo.
Fase 3 (terms)
composer build:docs:glossaryroda sem erro.Método de Loginaparece emdocs/glossary/index.mdcom 2 subterms.
Fase 4 (contratos.md)
- Cada
.mdreferencia termos canônicos válidos. - Schema JSON dos exemplos passa em validador OpenAPI.
- Exemplos refletem payload real (post-F6 daquele endpoint).
Fase 5
- F5a:
composer build:openapiregenera comservers.urlcorreto. - F5a: OpenAPI passa em linter (Spectral ou similar — opcional).
- F5b: Newman roda collection completa → todos requests verde.
Fase 6 (TODOs)
- Cada controller após remover mock: payload bate com #[OA] (manual ou via Fase 7 quando implementada).
- F6.onboarding-idempotent: teste de race (2 submits simultâneos → mesmo resultado, signal 1x).
- F6.async-failure: teste de handler exception → status=‘failed’ + retry funcional.
Fase 7 (golden contract tests, A3)
- PHPUnit suite passa.
- Adição de novo endpoint em #[OA] sem teste → CI falha.
- Plugin generator cobre criação de User+Enrolment+StudentPlan+Slot+…
10. Estratégia de paralelização (worktrees)
| Lane | Fases | Modules | Depende de |
|---|---|---|---|
| 0 | F0.1, F0.2, F0.3 | composer.json, tests/generator/ | — |
| A | F1 | classes/extensions/platform/ + tests/regression/ | F0.3 |
| B | F3 | .vigim/ddd/terms/ | — |
| C1..C6 | F6 (6 stories paralelas) | classes/extensions/platform/controller/{me,exam,dashboard,notification,flashcard} | F1 |
| C7 | F6.onboarding-idempotent | classes/extensions/engine/onboarding/ | F1 |
| C8 | F6.async-failure | classes/extensions/engine/onboarding/, plan/ | F1 |
| D | F2 + F5a + F5b | docs/plataforma/api-integracoes/ | F1, F0.1 |
| E | F4 (por endpoint) | docs/plataforma/api-integracoes/contratos/ | F1, C correspondente daquele endpoint |
| F | F7 (por endpoint) | tests/contract/platform/ + tests/generator/ | F1, F0.3, C correspondente |
Execução sugerida:
- F0 isolado (preparação).
- F1 isolado (foundation, breaking change, aceita risco A1).
- Após F1: B, C1..C8, D em paralelo (worktrees separadas).
- Conforme C cada um termina: começa o F4 daquele endpoint (Lane E) e o F7 daquele endpoint (Lane F).
11. Pendências externas e TODOs
| ID | Descrição | Responsável | Crítica? |
|---|---|---|---|
| B-pend-1 | MIDDAG /local/middag/api/auth/login retornar wstoken no payload do login social (CQ3 doc-first) |
Time MIDDAG | Sim — frontend dependente |
| B-pend-2 | Async student_plan creation: dead letter / retry / alerta operacional | Time Engine/Plan | Sim — observabilidade prod |
| TODO-1 | Bearer + URL token simultâneos: validar precedência no middleware local_middag e documentar |
Time MIDDAG | Não, edge case |
| TODO-2 | Adicionar APM (Tideways/NewRelic) para regressão perf real (P2) | Backlog futuro | Não |
F0.2 e B-pend-1 sincronizados com time MIDDAG antes de F2 começar (F2 depende do contrato).
12. Critério de pronto (Definition of Done)
- BASE_PATH refatorado, zero ocorrências do velho em código (F1).
- T1 smoke regression test passa em CI (F1).
-
autenticacao.mdreescrito conforme estrutura proposta, EM REVISÃO (F2). -
terms-platform.yamlcomMétodo de Login; glossário gerado (F3). -
composer.json:build:openapicorrigido; OpenAPI yaml comservers.urlcorreto esecuritySchemesadicionado (F5a + F0.1). - OpenAPI gerado bate com paths reais dos controllers (F5a).
- Postman collection oficial em
docs/plataforma/api-integracoes/postman/; Newman roda 100% verde (F5b). - Pelo menos um arquivo
contratos/<resource>.mdpor recurso, comonboarding.mdem qualidade lake (F4). - 6 TODOs nos controllers fechados (F6.me, F6.exam-list, F6.exam-detail, F6.dashboard, F6.notification, F6.flashcard).
- T2 idempotência onboarding implementada + teste passa (F6.onboarding-idempotent).
- T3 async failure visible + retry implementado + teste passa (F6.async-failure).
- P1 polling rate limit implementado + documentado (F2 + middleware).
- Plugin generator com helpers para User+Enrolment+StudentPlan+Slot+… (F0.3 + sob demanda).
- Testes contract para cada endpoint estável; CI gate ativado (F7).
- Cross-links entre artefatos consistentes.
- B-pend-1, B-pend-2, TODO-1, TODO-2 registrados em pendencias.md ou tracker.
13. Riscos
| Risco | Probabilidade | Impacto | Mitigação |
|---|---|---|---|
| Frontend já consome paths velhos em ambiente | Baixa (A1 valida assumindo not-prod) | Alto | A1: aceito risco. Se prod surgir, reverter F1 e suportar alias temporário. |
Service moodle_mobile_app não habilitado em prod/staging |
Média | Alto | Validar config Moodle como pré-requisito de release. |
| MIDDAG não implementa wstoken a tempo (B-pend-1) | Média | Alto (frontend social bloqueado) | F0.2 sincronia direta com time MIDDAG; CQ3 doc-first cria pressão. |
| Async student_plan handler instável (B-pend-2) | Média | Alto | T3 visibilidade + B-pend-2 follow-up operacional. |
| N+1 silencioso pós-F6 (P2 não cobre) | Média | Médio | Risco aceito; revisitar se incidente em prod. |
| Plugin generator insuficiente (F0.3 stubs) | Média | Médio (Lane F bloqueia) | Implementação incremental: cada teste adiciona helpers que precisa. |
| Spectral/linter de OpenAPI revela problemas estruturais que exigem reescrita ampla | Baixa | Médio | F5a fica como story própria se isso ocorrer. |
14. Referências
docs/operacao/uc-001-login.mddocs/plataforma/arquitetura/09-platform.mddocs/plataforma/adrs/adr-90_*.mddocs/plataforma/adrs/ref/ref-30-e_contract-specifications.md.vigim/ddd/terms/terms-platform.yamlclasses/extensions/platform/composer.json(build:openapi,build:docs:glossary)
GSTACK REVIEW REPORT
| Review | Trigger | Why | Runs | Status | Findings |
|---|---|---|---|---|---|
| CEO Review | /plan-ceo-review |
Scope & strategy | 0 | — | — |
| Codex Review | /codex review |
Independent 2nd opinion | 0 | — | — |
| Eng Review | /plan-eng-review |
Architecture & tests (required) | 1 | CLEAR (PLAN) | 5 architecture + 3 code quality + 3 test + 2 perf decisions; 1 IRON regression test added |
| Design Review | /plan-design-review |
UI/UX gaps | 0 | — | n/a (backend) |
| DX Review | /plan-devex-review |
Developer experience | 0 | — | — |
- UNRESOLVED: 0 decisões abertas após revisão
- VERDICT: ENG CLEARED — pronto para implementação. DX review opcional (impacto frontend).