Skip to content

Piloto — migração Vue→React do fluxo admin/disciplina (Index + Edit)

Piloto — migração Vue→React do fluxo admin/disciplina (Index + Edit)

  • Data: 2026-04-23
  • Escopo: plugin local/helico
  • Tipo: spec de design validada via brainstorming estruturado
  • Status: rascunho para revisão
  • Arquivos alvo da migração: ui/src/pages/admin/disciplina/Index.vue e ui/src/pages/admin/disciplina/Edit.vue

1. Objetivo

Provar ponta a ponta que o local_helico pode ter um frontend em React reutilizando a stack React já madura do local_middag, migrando o fluxo admin/disciplina (Index + Edit) com paridade funcional completa. O piloto descobre, formaliza e valida os padrões de build, AMD dedup, Inertia-React e consumo cross-plugin que as 29 telas Vue restantes vão herdar nos épicos seguintes.

Objetivos não-objetivos:

  • Não adota o ContractPage/PageContract do middag no helico (decisão explícita — ver §2.3).
  • Não migra as outras 29 telas Vue. Elas continuam funcionando em paralelo.
  • Não introduz suíte de testes automatizados no frontend.
  • Não reformula o backend: rotas, serviços e endpoints REST do helico permanecem inalterados.

2. Decisões travadas

2.1 Modelo de consumo (opção C)

Helico possui ui/ React próprio e importa do middag via alias Vite @middag → ../middag/ui/src. Não duplica o sistema de design localmente, nem reusa o bundle AMD do middag como fonte de páginas.

2.2 Escopo do piloto (opção B)

End-to-end mínimo viável: ao final, o usuário abre /admin/disciplina no Moodle e vê o Index React renderizado, navega para /disciplinas/{id}/edit e vê o Edit React renderizado, executa as ações de ponta a ponta (filtrar, sincronizar, excluir, salvar, processar, gerar flashcards) com paridade funcional 1:1 com a versão Vue.

2.3 Sem ContractPage / PageContract

O piloto não usa o page builder PHP do middag nem o runtime ContractPage React. Os componentes React são escritos no padrão tradicional (useState/useEffect + chamadas REST via axios), mantendo paralelo direto com o código Vue atual. Avaliado e rejeitado ao descobrir gaps no framework (polling, confirmação declarativa, loading em page_action) que fariam o piloto inchar em contribuições ao middag.

2.4 Reuso do middag (opção B)

Helico importa do @middag/:

  • tailwind.css (design tokens e base Tailwind v4)
  • components/reui/* (biblioteca de componentes Radix/Base UI — inclui button, dialog, input, card, badge, separator, spinner, sonner, tooltip, table, data-grid/*)
  • system/theme/appearance (dark/light)
  • Fonts via @fontsource-variable/figtree
  • Ícones via lucide-react e @hugeicons/react

Helico NÃO importa:

  • runtime/ContractPage, contracts/page-contract, runtime/registries, system/blocks/*
  • app/register-defaults.ts, app/register-extensions.ts
  • framework/shared/ui/* no PHP middag (page_builder/crud_builder/etc.)

2.5 Dedup de libs em runtime (opção B.2)

Helico declara React, ReactDOM, Radix, @tanstack/react-table, @tanstack/react-virtual e scheduler como AMD externals apontando para os chunks do middag (local_middag/react-vendor-lazy, local_middag/react-ui-lazy, local_middag/react-table-lazy). Uma única instância de cada em runtime. Resolvido em vite.config.ts via adaptação do vite-plugin-moodle-amd que o middag já usa.

2.6 Seleção de motor (Vue ou React) por rota

Pequena lista MIGRATED_PAGES lida pelo inertia_adapter (ou pelo controller que invoca $this->inertia(...)). Rotas migradas disparam js_call_amd('local_helico/inertia_app_react', 'init'); rotas não migradas continuam com js_call_amd('local_helico/inertia_app', 'init') (Vue). O piloto inicia com MIGRATED_PAGES = ['admin/disciplina/Index', 'admin/disciplina/Edit'].

2.7 Coexistência Vue + React durante a migração

Ambos os bundles vivem em paralelo em amd/src/:

  • app.js (Vue, inalterado)
  • inertia_app.js (wrapper AMD Vue, inalterado)
  • react-app.js (novo, React)
  • inertia_app_react.js (novo, wrapper AMD React)

Duas invocações AMD diferentes, duas builds Vite separadas (ver §3.2). A convivência dura até a última página .vue ser migrada.

2.8 Namespace CSS

Helico roda dentro do seletor .middag-root (reuso direto). Sem criar .helico-root paralelo. ensurePortalContainer() do middag cria #middag-portals globalmente; helico herda.

2.9 Paridade de status HTML

A coluna status da tabela Index (e displaystatus das versões em Edit) continua sendo HTML arbitrário servido pelo backend. Na versão React é renderizado via dangerouslySetInnerHTML. Migrar para contrato estruturado ({label, tone} + <StatusBadge>) fica como débito técnico registrado no backlog, fora do piloto.

2.10 Navegação Index → Edit

Ambos estão no piloto e usam router.visit(urledit) do @inertiajs/react. SPA-like, sem full page reload.

3. Arquitetura

3.1 Visão em camadas

┌─ LOCAL/HELICO/UI (fonte) ──────────────────────────────────┐
│ src/main.tsx                 entry React                    │
│ src/app/inertia-app.tsx      boot Inertia-React             │
│ src/app/page-resolver.ts     nome → import dinâmico .tsx    │
│ src/pages/admin/disciplina/                                 │
│   Index.tsx                  migração piloto (Index)        │
│   Edit.tsx                   migração piloto (Edit)         │
│ src/services/                axios, puro TS                 │
│ src/hooks/                   useServerPolling (novo)        │
│ src/components/              ConfirmDialog (novo local)     │
│                                                             │
│ Importa de @middag (alias Vite):                            │
│   @middag/tailwind.css                                      │
│   @middag/components/reui/*                                 │
│   @middag/system/theme/appearance                           │
└─────────────────────────────────────────────────────────────┘
              │ Vite build (React config)
              ▼
┌─ LOCAL/HELICO/AMD/SRC (output) ────────────────────────────┐
│ react-app.js                 bundle React helico enxuto     │
│ inertia_app_react.js         wrapper AMD novo               │
│ app.js                       bundle Vue inalterado          │
│ inertia_app.js               wrapper AMD Vue inalterado     │
│ launcher.js                  inalterado                     │
└─────────────────────────────────────────────────────────────┘
              │ Moodle AMD loader em runtime
              ▼
┌─ RUNTIME (navegador) ──────────────────────────────────────┐
│ local_middag/react-vendor-lazy   React 19, ReactDOM        │
│ local_middag/react-ui-lazy       Radix, CVA                │
│ local_middag/react-table-lazy    @tanstack/react-table     │
│ local_helico/react-app           código helico + pieces    │
│                                  importadas do @middag     │
└─────────────────────────────────────────────────────────────┘

3.2 Estrutura de pastas em local/helico/ui/

local/helico/ui/
├── package.json              React 19, @inertiajs/react, axios, sonner (via @middag), lucide-react, @hugeicons/react, devDeps: @vitejs/plugin-react, @tailwindcss/vite, tailwindcss
├── vite.config.ts            (novo) config React — ver §3.3
├── vite.vue.config.js        (renomeado a partir do vite.config.js atual) config Vue — sem mudanças
├── tsconfig.json / .app / .node
├── plugins/
│   └── vite-plugin-moodle-amd.ts   cópia/adaptação do plugin do middag
├── src/                      código React novo
│   ├── main.tsx
│   ├── app/
│   │   ├── inertia-app.tsx
│   │   └── page-resolver.ts
│   ├── runtime/
│   │   └── inertia-resolver.ts   equivalente React do atual (Vue)
│   ├── pages/admin/disciplina/
│   │   ├── Index.tsx
│   │   └── Edit.tsx
│   ├── services/
│   │   ├── baseApiService.ts
│   │   ├── disciplinaApiService.ts
│   │   └── syncApiService.ts
│   ├── hooks/
│   │   └── useServerPolling.ts
│   └── components/
│       └── ConfirmDialog.tsx
└── src-vue/                  renomeado a partir do src/ atual (Vue legado intacto)
    ├── app.js
    ├── pages/ (.vue)
    ├── components/ (.vue)
    └── ...

Scripts no package.json:

  • build — executa ambas as builds (React + Vue) em sequência
  • build:react — vite build com vite.config.ts
  • build:vue — vite build --config vite.vue.config.js
  • dev:react / dev:vue — watches independentes
  • lint, format — mantidos

3.3 Vite config (React)

Pontos-chave de vite.config.ts:

  • Plugins: @vitejs/plugin-react, @tailwindcss/vite, vite-plugin-moodle-amd (local)
  • Alias: @ → ./src, @middag → ../middag/ui/src
  • build.outDir → ../amd/src
  • build.rollupOptions.input → { 'react-app': 'src/main.tsx' }
  • build.rollupOptions.output.format → amd
  • build.rollupOptions.external → marca como externals:
    • react, react-dom, scheduler → mapeados no wrapper AMD para local_middag/react-vendor-lazy
    • @radix-ui/*, class-variance-authority → local_middag/react-ui-lazy
    • @tanstack/react-table, @tanstack/react-virtual → local_middag/react-table-lazy
    • core/ajax, core/str, core/notification, jquery (externals Moodle padrão)

O plugin vite-plugin-moodle-amd (adaptação do middag) é responsável por:

  1. Marcar os imports npm listados como externals.
  2. Emitir o arquivo AMD final (define([...], factory)) com os IDs AMD corretos.
  3. Preservar code splitting dos chunks específicos do helico.

3.4 Bootstrap Inertia-React (src/app/inertia-app.tsx)

Adaptação simplificada de middag/ui/src/app/inertia-app.tsx:

  • Cria createInertiaApp com @inertiajs/react
  • resolve: delega ao page-resolver.ts local
  • Sem registries de Shell/Layout/Block
  • Providers mínimos inicialmente (só o que for necessário para o piloto):
    • <ErrorBoundary> (cópia simplificada de NavErrorBoundary do middag)
    • <Toaster /> (sonner) — montado globalmente; helico precisa montar porque middag ainda não monta
  • Aplica setAppearance/getStoredAppearance de @middag/system/theme/appearance
  • Chama ensurePortalContainer() (ou reusa o do middag se exportado)

Side-effect de mount: main.tsx chama startInertiaApp() assim que o módulo carrega, mesmo padrão do middag.

3.5 Page resolver (src/app/page-resolver.ts)

Mapa explícito inicial:

const pages = {
  'admin/disciplina/Index': () => import('@/pages/admin/disciplina/Index'),
  'admin/disciplina/Edit': () => import('@/pages/admin/disciplina/Edit'),
};

Retorna a função correspondente ao nome recebido pelo Inertia. À medida que novas telas forem migradas, o mapa cresce. Alternativa (import.meta.glob) fica deferida — mapa explícito é mais explícito e mais fácil de auditar neste estágio.

3.6 Seleção de motor por rota (PHP)

Ponto de integração mínimo no helico (ou via adição ao inertia_adapter do middag, dependendo de como handle() é resolvido):

// abordagem proposta: hook simples no controller base ou no inertia_adapter
const MIGRATED_PAGES = [
    'admin/disciplina/Index',
    'admin/disciplina/Edit',
];

// em inertia_adapter::render() ou equivalente:
if (in_array($component, MIGRATED_PAGES, true)) {
    $PAGE->requires->js_call_amd('local_helico/inertia_app_react', 'init');
} else {
    $PAGE->requires->js_call_amd('local_helico/inertia_app', 'init');
}

A forma exata (atributo no $this->inertia(), constante global, helper no controller) é refinada no plano de implementação. A intenção é: lista declarativa, pequena, auditável, fácil de estender.

4. Componentes do piloto

4.1 src/pages/admin/disciplina/Index.tsx

Paridade funcional 1:1 com Index.vue:

Feature Implementação React
Tabela com colunas id, idnumber, fullname, status, lastprocess, ações <DataGrid> de @middag/components/reui/data-grid
Paginação server-side onParamChange do DataGrid → setPage/setPerPage → loadData()
Filtro por fullname (Enter + input) <Input> @middag/components/reui/input + handler que dispara loadData()
Botão “Sincronizar arquivos” com loading e ícone rotativo <Button> + <RefreshCw className="animate-spin"> condicional
Dialog de confirm sync <ConfirmDialog> local (wrapper de @middag/components/reui/dialog)
Ícone de editar (lápis) <Button variant="ghost"><Pencil/></Button> + router.visit(urledit)
Ícone de lixeira <Button variant="ghost"><Trash2/></Button> + abre <ConfirmDialog>
Coluna status como HTML dangerouslySetInnerHTML={{ __html: row.status }}

Estado (useState): files, totalRecords, loading, page, perPage, fullnameFilter, syncModalOpen, loadingSync, deleteModalOpen, deleteItemId. Ref: pollingTimerRef.

Serviços: DisciplinaApiService.list, .delete; SyncApiService.startSync.

Polling: useServerPolling({ active: hasActiveProcessing, intervalMs: 4000, onTick: () => loadData(silent=true) }).

4.2 src/pages/admin/disciplina/Edit.tsx

Paridade funcional 1:1 com Edit.vue (727 linhas):

  • Props injetadas pelo Inertia: usePage<{data: WidgetData; id: string|number}>()
  • applyData(props.data) disparado em useEffect([props.data]), equivalente ao watch(deep:true, immediate:true) do Vue
  • Form com 3 campos: fullName (obrigatório, validação manual via showValidation), categoryName e identifier (disabled/readonly)
  • DataTable interna de versões com 6 colunas: id, name, displaystatus (HTML), unidades, flashcards, version
  • Coluna “Arquivos”: botões download Word (<FileText>) e Markdown (<FileCode>) condicionais
  • Coluna “Ações”: botão “Processar” (regras em btnProcessIsDisable) e “Flashcards” (regras em btnFlashcardsIsDisable) com tooltip de razão
  • <ConfirmDialog> para processamento e flashcards, com spinner inline quando dialog.loading
  • Polling em 2 dimensões: useEffect([widgetState.isProcessing, widgetState.flashcardsProcessing]) — start/stop + auto-close modais + toast success quando flag cai para false
  • Toast: sonner — success em save/process/flashcards; error em falhas
  • Botões rodapé: “Cancelar” → router.visit('/local/helico/index.php/disciplinas'); “Salvar” → DisciplinaApiService.saveFilename + redirect

Regras de negócio portadas 1:1 (strings de mensagem idênticas):

  • getFlashcardsDisabledReason(item), btnFlashcardsIsDisable(item)
  • getProcessDisabledReason(item), btnProcessIsDisable(item)
  • canShowFlashcardsBtn(item)

Para manter Edit.tsx enxuto, essas funções podem morar em src/pages/admin/disciplina/rules.ts.

4.3 src/components/ConfirmDialog.tsx

Wrapper local (não contribuído ao middag) sobre @middag/components/reui/dialog:

<ConfirmDialog
  open={boolean}
  title={string}
  loading={boolean}
  onCancel={() => void}
  onConfirm={() => void}
  confirmLabel="Confirmar"
  cancelLabel="Cancelar"
  intent="danger" | "primary"
>
  {children}
</ConfirmDialog>

Usado 4 vezes no piloto (Index: sync + delete; Edit: process + flashcards).

4.4 src/hooks/useServerPolling.ts

useServerPolling({
  active: boolean,
  intervalMs: number,
  onTick: () => void | Promise<void>,
})
  • Quando active=true e não há timer, inicia setInterval
  • Quando active=false, chama clearInterval
  • Cleanup do useEffect para no unmount
  • Guarda o timer em useRef<number | null>
  • Usado no Index e no Edit

4.5 Services (src/services/)

Portados com mudança mínima dos arquivos Vue atuais — são TS puro + axios, sem dependência de framework UI.

  • baseApiService.ts — axios instance base
  • disciplinaApiService.ts — list, listProcessed, delete, saveFilename, getEditData, startProcess, startFlashcardProcess
  • syncApiService.ts — startSync

Base URL e error handling inalterados.

5. Fluxo de dados

5.1 Index — carga + paginação + filtro

Moodle carrega /admin/disciplina
  → admin_controller::index() → $this->inertia('admin/disciplina/Index', [])
  → inertia_adapter vê MIGRATED_PAGES → dispara inertia_app_react
  → Inertia-React boota → page-resolver → Index.tsx monta
  → useEffect(loadData, [])
  → DisciplinaApiService.list({ page, limit, fullname })
  → axios GET /disciplinas?page=0&limit=10
  → setFiles / setTotalRecords / setLoadingSync
  → syncPollingState()
  → <DataGrid> renderiza

5.2 Index — polling

loadData termina
  → hasActiveProcessing() = loadingSync || files.some(is_processing)
  → true: useServerPolling dispara setInterval(loadData silent, 4000)
  → false: clearInterval
cleanup(unmount)
  → clearInterval

5.3 Index — delete

clique na lixeira → setDeleteItemId(X) + setDeleteModalOpen(true)
<ConfirmDialog> → Confirmar → confirmDeleteFile(X)
  → DisciplinaApiService.delete(X) → DELETE /disciplinas/X
  → success: await loadData()
  → failure: toast.error('Erro ao excluir registro.')

5.4 Index — sync

clique em Sincronizar → setSyncModalOpen(true)
<ConfirmDialog> → Confirmar → registerStartSyncFiles()
  → setLoadingSync(true)
  → SyncApiService.startSync() → POST /sync/start
  → success:        await loadData() → polling inicia
  → code === 1001:  console.error(message)
  → erro genérico:  console.error

5.5 Edit — carga

Moodle carrega /disciplinas/{id}/edit
  → admin_controller::edit() → $this->inertia('admin/disciplina/Edit', { data, id })
  → Edit.tsx monta com props = { data, id }
  → useEffect([props.data]) → applyData(props.data)
  → useEffect([isProcessing, flashcardsProcessing]) → avalia polling + side effects

5.6 Edit — save

Salvar → setShowValidation(true)
  → form.fullName vazio? return
  → setSaving(true)
  → DisciplinaApiService.saveFilename(id, fullName)
  → success: router.visit('/local/helico/index.php/disciplinas')
  → failure: toast.error(content)

5.7 Edit — process / flashcards

openProcessDialog(file) → setProcessDialog({ visible: true, file })
<ConfirmDialog> → Confirmar
  → processDialog.loading = true
  → widgetState.isProcessing = true
  → DisciplinaApiService.startProcess(fileId) / startFlashcardProcess(disciplinaId)
  → success: await reloadData() + startPolling()
  → failure: toast.error + reverter flags
  → closeProcessDialog()

polling → getEditData(id) → applyData(response.content)
  → isProcessing passa a false
  → useEffect observa → closeProcessDialog() + toast.success('Processamento concluído.')

6. Tratamento de erro

Paridade estrita com Vue, com pequeno upgrade onde o Vue usa alert():

Caso Vue atual React piloto
loadData() rede console.error silencioso idem
confirmDeleteFile() rede console.error + alert console.error + toast.error
confirmDeleteFile() API success:false nada idem
registerStartSyncFiles() rede console.error idem
registerStartSyncFiles() code 1001 console.error(message) idem
save() Edit toast.error idem
confirmProcess() / confirmFlashcards() toast.error + reverter flags idem
Polling (reloadData) catch {} silencioso idem

Error boundary global em inertia-app.tsx evita tela branca em erro de render.

Axios 401/403 não são tratados (paridade com Vue). Débito registrado no BACKLOG.

7. Verificação

Todos os itens abaixo são UAT manual. Sem suíte automatizada neste piloto.

7.1 Index

  • Abre /admin/disciplina — tabela renderiza linhas do GET /disciplinas
  • Paginação (mudar página) — dispara nova chamada
  • Filtro por nome (Enter e input live) — re-chama com fullname=
  • Botão “Sincronizar arquivos” → modal → Confirmar — dispara POST /sync/start
  • Polling inicia após sync — tabela atualiza a cada 4s enquanto sincronizando
  • Polling para quando sync termina e nenhum arquivo tem is_processing
  • Ícone de editar — navega para /disciplinas/{id}/edit via Inertia-React (sem full reload)
  • Ícone de lixeira → modal → Confirmar — linha some
  • Coluna “Status” renderiza HTML retornado pelo backend (spans, cores)

7.2 Edit

  • Campos do form recebem valores via props Inertia
  • “Salvar” com nome vazio mostra erro de validação e não envia
  • “Salvar” com nome válido salva e redireciona para Index
  • “Cancelar” redireciona para Index sem salvar
  • DataTable de versões renderiza com 6 colunas
  • Botões download Word + Markdown abrem em nova aba
  • “Processar” aparece só na última versão com unidadeProcessStatus !== 'completed'
  • “Processar” → modal → Confirmar — dispara, modal mostra spinner
  • Polling inicia; quando isProcessing → false, modal fecha e toast “Processamento concluído”
  • “Flashcards” respeita regras de disabled (tooltip mostra razão correta)
  • “Flashcards” → modal → Confirmar — dispara, toast ao concluir

7.3 Build e runtime

  • npm run build:react gera ../amd/src/react-app.js e chunks
  • npm run build:vue ainda gera ../amd/src/app.js sem mudança
  • Build do middag continua funcional (sem mudança no diretório dele)
  • Abrindo /admin/disciplina: Network tab carrega local_middag/react-vendor-lazy, react-ui-lazy, react-table-lazy + local_helico/react-app — uma vez cada
  • Console sem warning “you might have more than one copy of React” ou “Invalid hook call”
  • Bundle react-app.js enxuto (50–150 KB esperado, SEM React/Radix/tanstack inline)

7.4 Não-regressão

  • Rotas Vue não migradas (ex.: /trilha/{id}, learning-path, unidade) continuam renderizando via inertia_app.js Vue
  • node_modules helico e middag sem conflito de versões de React/Radix

7.5 Documentação

  • local/helico/ui/README.md curto cobrindo: stack React, alias @middag, dedup AMD, como adicionar nova página React
  • Nota em .vigim/BACKLOG.md listando os 29 .vue restantes e o padrão de migração descoberto

8. Rollback

Git revert do commit que altera MIGRATED_PAGES (ou o equivalente). Rotas voltam a servir Vue. Artefatos React em amd/src/react-*.js ficam órfãos mas inofensivos. Nenhum arquivo Vue é removido no piloto.

9. Débitos técnicos registrados (backlog)

  1. Coluna status / displaystatus via HTML arbitrário. Evoluir para contrato estruturado ({label, tone} + <StatusBadge>).
  2. Tratamento de 401/403 no axios (hoje inexistente em Vue e React).
  3. Suíte de testes frontend (vitest) não introduzida — decidir se vale em épico futuro.
  4. <Toaster /> do sonner é montado localmente no helico. Se mais plugins passarem a consumir, considerar promover o monte para o middag.
  5. 29 telas .vue restantes — plano de migração gradual a partir do padrão descoberto.
  6. ADR opcional em docs/plataforma/adrs/ formalizando “Adoção de React no helico via reuso do middag (decisões C/B/B.2, sem ContractPage)”.

10. Não-escopo

  • Migração das outras 29 telas Vue
  • Adoção de ContractPage / PageContract no helico
  • Criação de builders PHP equivalentes aos do local_middag/framework/shared/ui
  • Contribuições ao framework middag (confirm declarativo, poll declarativo, loading em page_action)
  • Testes automatizados
  • Mudanças em rotas, serviços PHP, endpoints REST
  • Reorganização do classes/ do helico
  • Alterações em terms.yaml ou documentação de metodologia
Navigation

Type to search…

↑↓ navigate↵ selectEsc close