Skip to content

Plano — Documentação Completa da Platform API

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.md está como stub (“Em construção”).
  • docs/plataforma/api-integracoes/openapi.yaml tem servers.url: /webservice/restful/server.php — incorreto (entry real é /local/helico/ajax.php/).
  • composer build:openapi script existe mas tem --server-url apontando 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 com helico/ redundante.
  • 6 controllers retornam dados mockados (TODOs).
  • Não há testes de contrato.
  • Vocabulário canônico (.vigim/ddd/terms/) tem API REST HÉLICO mas falta Método de Login e 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.json build: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.php com local_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.php
  • onboarding_api_controller.php
  • enrolment_api_controller.php
  • exam_api_controller.php
  • study_api_controller.php
  • slot_api_controller.php
  • dashboard_api_controller.php
  • flashcard_api_controller.php
  • notebook_api_controller.php
  • notification_api_controller.php
  • performance_api_controller.php
  • admin/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:openapi regenera 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 collection

Fase 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.md lista 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.md
  • onboarding.md ← prioritário, qualidade lake
  • study.md (slots, performance)
  • exam.md (após F6.exam)
  • flashcard.md (após F6.flashcard)
  • notebook.md
  • notification.md (após F6.notification)
  • dashboard.md (após F6.dashboard)
  • admin/corrections.md

Cada página:

  1. Endpoint (método + path novo D1=B)
  2. Auth requerida
  3. Path/query params
  4. Request body schema + exemplo JSON real
  5. Response 200 schema + exemplo JSON real (não mock — A2)
  6. Tabela de erros
  7. Invariantes (citando termos canônicos)
  8. Diagrama ASCII para fluxos com estado
  9. 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 value em answers[]
  • Fluxo assíncrono pós-submit (student_plan = {id: null, status: "creating"}) → polling em /enrolments
  • T3: estado failed visí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.md se 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. Auth com 2 sub-requests:
    • POST /login/token.php (Moodle nativo) — body form-encoded username + password + service=moodle_mobile_app. Test script grava wstoken.
    • POST /local/middag/api/auth/login (social) — body JSON. Test script grava wstoken + 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:

  1. Identificar service que provê dados (provavelmente já existe em extensions/platform/service/ ou domínios upstream).
  2. Wire DI no controller.
  3. Validar payload retornado bate com #[OA] declarado.
  4. 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_id em onboarding_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_controller retorna 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.php com método assert_matches_openapi(string $path, string $method, $response_status, array $response_body):
    1. Lê openapi.yaml.
    2. Resolve schema do response para path + method + status.
    3. Valida $response_body contra schema.
    4. Falha descritiva.
  • 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):

  1. Endpoints estáveis (não-mock): onboarding, enrolments, study, slots, performance, admin corrections.
  2. 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_middag middleware 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:glossary roda sem erro.
  • Método de Login aparece em docs/glossary/index.md com 2 subterms.

Fase 4 (contratos.md)

  • Cada .md referencia 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:openapi regenera com servers.url correto.
  • 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:

  1. F0 isolado (preparação).
  2. F1 isolado (foundation, breaking change, aceita risco A1).
  3. Após F1: B, C1..C8, D em paralelo (worktrees separadas).
  4. 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.md reescrito conforme estrutura proposta, EM REVISÃO (F2).
  • terms-platform.yaml com Método de Login; glossário gerado (F3).
  • composer.json:build:openapi corrigido; OpenAPI yaml com servers.url correto e securitySchemes adicionado (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>.md por recurso, com onboarding.md em 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.md
  • docs/plataforma/arquitetura/09-platform.md
  • docs/plataforma/adrs/adr-90_*.md
  • docs/plataforma/adrs/ref/ref-30-e_contract-specifications.md
  • .vigim/ddd/terms/terms-platform.yaml
  • classes/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).
Navigation

Type to search…

↑↓ navigate↵ selectEsc close