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.vueeui/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/PageContractdo 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 — incluibutton,dialog,input,card,badge,separator,spinner,sonner,tooltip,table,data-grid/*)system/theme/appearance(dark/light)- Fonts via
@fontsource-variable/figtree - Ícones via
lucide-reacte@hugeicons/react
Helico NÃO importa:
runtime/ContractPage,contracts/page-contract,runtime/registries,system/blocks/*app/register-defaults.ts,app/register-extensions.tsframework/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ênciabuild:react—vite buildcomvite.config.tsbuild:vue—vite build --config vite.vue.config.jsdev:react/dev:vue— watches independenteslint,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/srcbuild.rollupOptions.input→{ 'react-app': 'src/main.tsx' }build.rollupOptions.output.format→amdbuild.rollupOptions.external→ marca como externals:react,react-dom,scheduler→ mapeados no wrapper AMD paralocal_middag/react-vendor-lazy@radix-ui/*,class-variance-authority→local_middag/react-ui-lazy@tanstack/react-table,@tanstack/react-virtual→local_middag/react-table-lazycore/ajax,core/str,core/notification,jquery(externals Moodle padrão)
O plugin vite-plugin-moodle-amd (adaptação do middag) é responsável por:
- Marcar os imports npm listados como externals.
- Emitir o arquivo AMD final (
define([...], factory)) com os IDs AMD corretos. - 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
createInertiaAppcom@inertiajs/react resolve: delega aopage-resolver.tslocal- Sem registries de Shell/Layout/Block
- Providers mínimos inicialmente (só o que for necessário para o piloto):
<ErrorBoundary>(cópia simplificada deNavErrorBoundarydo middag)<Toaster />(sonner) — montado globalmente; helico precisa montar porque middag ainda não monta
- Aplica
setAppearance/getStoredAppearancede@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 emuseEffect([props.data]), equivalente aowatch(deep:true, immediate:true)do Vue- Form com 3 campos:
fullName(obrigatório, validação manual viashowValidation),categoryNameeidentifier(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 embtnFlashcardsIsDisable) com tooltip de razão <ConfirmDialog>para processamento e flashcards, com spinner inline quandodialog.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=truee não há timer, iniciasetInterval - Quando
active=false, chamaclearInterval - Cleanup do
useEffectpara 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 basedisciplinaApiService.ts—list,listProcessed,delete,saveFilename,getEditData,startProcess,startFlashcardProcesssyncApiService.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> renderiza5.2 Index — polling
loadData termina
→ hasActiveProcessing() = loadingSync || files.some(is_processing)
→ true: useServerPolling dispara setInterval(loadData silent, 4000)
→ false: clearInterval
cleanup(unmount)
→ clearInterval5.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.error5.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 effects5.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 doGET /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}/editvia 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:reactgera../amd/src/react-app.jse chunks -
npm run build:vueainda gera../amd/src/app.jssem mudança - Build do middag continua funcional (sem mudança no diretório dele)
- Abrindo
/admin/disciplina: Network tab carregalocal_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.jsenxuto (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 viainertia_app.jsVue -
node_moduleshelico e middag sem conflito de versões de React/Radix
7.5 Documentação
-
local/helico/ui/README.mdcurto cobrindo: stack React, alias@middag, dedup AMD, como adicionar nova página React - Nota em
.vigim/BACKLOG.mdlistando os 29.vuerestantes 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)
- Coluna
status/displaystatusvia HTML arbitrário. Evoluir para contrato estruturado ({label, tone}+<StatusBadge>). - Tratamento de 401/403 no axios (hoje inexistente em Vue e React).
- Suíte de testes frontend (
vitest) não introduzida — decidir se vale em épico futuro. <Toaster />do sonner é montado localmente no helico. Se mais plugins passarem a consumir, considerar promover o monte para o middag.- 29 telas
.vuerestantes — plano de migração gradual a partir do padrão descoberto. - 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/PageContractno 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.yamlou documentação de metodologia