Piloto Vue→React disciplina — Plano de Implementação
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: Migrar pages/admin/disciplina/Index.vue e pages/admin/disciplina/Edit.vue para React 19 com paridade funcional 1:1, estabelecendo a stack React no plugin local_helico via reuso do design system de local_middag.
Architecture: Helico recebe um novo pipeline Vite/React paralelo ao Vue existente. Os bundles Vue continuam servindo as 29 telas não migradas. As 2 telas migradas usam local_helico/inertia_app_react (novo AMD wrapper) que carrega o bundle local_helico/react-app — que importa em build-time componentes de @middag/components/reui/* e em runtime resolve React/Radix/tanstack via externals AMD apontando para os chunks do local_middag. Nenhuma modificação em local_middag.
Tech Stack: React 19, TypeScript, Vite 5, @vitejs/plugin-react, @inertiajs/react, @tailwindcss/vite, Tailwind v4 (via @middag/tailwind.css), axios, sonner (via @middag/components/reui/sonner), lucide-react.
Reference docs: docs/_archive/specs/2026-04-23-pilot-disciplina-react-migration-design.md
Phase 0 — Prep
Task 0.1: Rename vite.config.js e src/ para deixar espaço ao novo pipeline React
Files:
-
Rename:
ui/vite.config.js→ui/vite.vue.config.js -
Rename:
ui/src/→ui/src-vue/ -
Step 1: Rename arquivos
cd local/helico
git mv ui/vite.config.js ui/vite.vue.config.js
git mv ui/src ui/src-vue- Step 2: Ajustar referência ao alias
@no config Vue (continua apontando para o código Vue)
Abrir ui/vite.vue.config.js e trocar:
// antes
alias: {
'@': path.resolve(__dirname, './src'),
},por:
alias: {
'@': path.resolve(__dirname, './src-vue'),
},Também trocar a linha do entry:
// antes
entry: path.resolve(__dirname, './src/app.js'),
// depois
entry: path.resolve(__dirname, './src-vue/app.js'),- Step 3: Rodar build Vue para confirmar que não quebramos nada
cd ui && npm run buildExpected: build gera amd/src/app.js como antes. Se falhar, revisar alias e entry.
- Step 4: Commit
cd ../..
git add local/helico/ui/vite.vue.config.js local/helico/ui/src-vue/
git commit -m "chore(ui): renomear src/ para src-vue/ e vite.config.js para vite.vue.config.js
Prepara espaço para o pipeline React paralelo (piloto disciplina).
Vue continua funcional — build testado."Task 0.2: Adicionar dependências React no package.json
Files:
-
Modify:
ui/package.json -
Step 1: Abrir
ui/package.jsone adicionar emdependencies
"@inertiajs/react": "^2.2.20",
"lucide-react": "^1.8.0",
"react": "^19.2.5",
"react-dom": "^19.2.5"E em devDependencies:
"@tailwindcss/vite": "^4.2.2",
"@types/react": "^19.2.14",
"@types/react-dom": "^19.2.3",
"@vitejs/plugin-react": "^4.3.2",
"tailwindcss": "^4.2.2"Manter tudo que já existe.
- Step 2: Ajustar scripts em
package.json
"scripts": {
"build": "npm run build:react && npm run build:vue",
"build:react": "vite build",
"build:vue": "vite build --config vite.vue.config.js",
"dev:react": "vite",
"dev:vue": "vite --config vite.vue.config.js",
"watch:react": "vite build --watch",
"watch:vue": "vite build --config vite.vue.config.js --watch",
"lint": "eslint .",
"format": "prettier --write '**/*.{js,vue,html,css,ts,tsx}'",
"postbuild": "shx mv ../amd/src/style.css ./css 2>/dev/null || true"
},- Step 3: Instalar dependências
cd ui && npm installExpected: 0 vulnerabilidades, sem erros de peer dep. react e react-dom aparecem em node_modules/.
- Step 4: Verificar que o build Vue ainda passa após as novas deps
npm run build:vueExpected: ../amd/src/app.js é gerado normalmente.
- Step 5: Commit
cd ../..
git add local/helico/ui/package.json local/helico/ui/package-lock.json
git commit -m "feat(ui): adicionar dependências React 19 + Tailwind v4
React/Radix/tanstack ficam como externals no build (dedup via AMD para
os chunks do local_middag). Vue continua instalado em paralelo."Task 0.3: Criar tsconfig.json React-aware (compartilhado com src-vue/ via inclusão)
Files:
-
Modify:
ui/tsconfig.json -
Create:
ui/tsconfig.react.json -
Step 1: Criar
ui/tsconfig.react.json
{
"compilerOptions": {
"target": "ES2022",
"lib": ["ES2022", "DOM", "DOM.Iterable"],
"jsx": "react-jsx",
"module": "ESNext",
"moduleResolution": "bundler",
"allowImportingTsExtensions": false,
"resolveJsonModule": true,
"isolatedModules": true,
"esModuleInterop": true,
"strict": true,
"noUncheckedIndexedAccess": true,
"skipLibCheck": true,
"baseUrl": ".",
"paths": {
"@/*": ["./src/*"],
"@middag/*": ["../middag/ui/src/*"]
}
},
"include": ["src/**/*.ts", "src/**/*.tsx"]
}- Step 2: Manter
ui/tsconfig.jsonatual referenciando ambos os projetos
Se tsconfig.json atualmente já referencia tsconfig.app.json (Vue), adicionar também tsconfig.react.json:
{
"files": [],
"references": [
{ "path": "./tsconfig.app.json" },
{ "path": "./tsconfig.node.json" },
{ "path": "./tsconfig.react.json" }
]
}- Step 3: Commit
git add local/helico/ui/tsconfig.json local/helico/ui/tsconfig.react.json
git commit -m "chore(ui): adicionar tsconfig.react.json com paths @ e @middag"Phase 1 — Build pipeline: Vite React + AMD dedup + Hello React
Task 1.1: Criar plugin Vite vite-plugin-moodle-amd adaptado para helico
Files:
- Create:
ui/plugins/vite-plugin-moodle-amd.ts
O plugin reescreve AMD chunks para prefixar com local_helico/* e mantém referências cross-plugin apontando para local_middag/* quando o chunk não é do helico.
- Step 1: Criar o arquivo
/**
* vite-plugin-moodle-amd — Rewrites Rollup AMD output for Moodle's RequireJS.
*
* Adaptation of middag's plugin:
* - Chunks do helico ganham prefixo `local_helico/`
* - Dependências cross-plugin (React, Radix, tanstack) ficam em externals
* apontando para chunks do middag (`local_middag/react-*-lazy`)
*/
import type { Plugin, ResolvedConfig } from 'vite';
import { copyFileSync, existsSync, mkdirSync, readdirSync } from 'node:fs';
import { basename, resolve } from 'node:path';
const PLUGIN_PREFIX = 'local_helico';
export default function moodleAmd(): Plugin {
let config: ResolvedConfig;
return {
name: 'vite-plugin-moodle-amd',
apply: 'build',
configResolved(resolved) {
config = resolved;
},
generateBundle(_, bundle) {
for (const [fileName, chunk] of Object.entries(bundle)) {
if (chunk.type !== 'chunk') continue;
let code = chunk.code;
const moduleName = fileName.replace(/\.js$/, '');
code = code.replace(
/define\(\[([\s\S]*?)\]/,
(match, deps: string) => {
const rewritten = deps.replace(
/(["'])\.\/([^"']+)\1/g,
`$1${PLUGIN_PREFIX}/$2$1`,
);
return `define([${rewritten}]`;
},
);
if (!code.includes(`define('${PLUGIN_PREFIX}/${moduleName}'`)) {
code = code.replace(
/define\(\[/,
`define('${PLUGIN_PREFIX}/${moduleName}',[`,
);
}
chunk.code = code;
}
},
closeBundle() {
const outDir = config.build.outDir;
const pluginRoot = resolve(config.root, '..');
const amdSrc = resolve(pluginRoot, 'amd/src');
const amdBuild = resolve(pluginRoot, 'amd/build');
if (!existsSync(outDir)) return;
if (!existsSync(amdBuild)) mkdirSync(amdBuild, { recursive: true });
const jsFiles = readdirSync(outDir).filter((f) => f.endsWith('.js'));
for (const file of jsFiles) {
const src = resolve(outDir, file);
const name = basename(file, '.js');
copyFileSync(src, resolve(amdSrc, file));
copyFileSync(src, resolve(amdBuild, `${name}.min.js`));
}
if (jsFiles.length > 0) {
console.log(`[moodle-amd] ${jsFiles.length} chunk(s) → amd/src/ + amd/build/`);
}
},
};
}- Step 2: Commit
git add local/helico/ui/plugins/vite-plugin-moodle-amd.ts
git commit -m "feat(ui): criar vite-plugin-moodle-amd adaptado para helico"Task 1.2: Criar vite.config.ts React
Files:
-
Create:
ui/vite.config.ts -
Step 1: Criar o arquivo
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import tailwindcss from '@tailwindcss/vite';
import moodleAmd from './plugins/vite-plugin-moodle-amd';
import path from 'node:path';
export default defineConfig({
plugins: [react(), tailwindcss(), moodleAmd()],
resolve: {
alias: {
'@': path.resolve(__dirname, './src'),
'@middag': path.resolve(__dirname, '../../middag/ui/src'),
},
},
build: {
outDir: path.resolve(__dirname, 'dist'),
emptyOutDir: true,
minify: 'esbuild',
cssCodeSplit: false,
rollupOptions: {
input: {
'react-app': path.resolve(__dirname, './src/main.tsx'),
},
external: (id) => {
// React e submodules (react/jsx-runtime, react-dom/client, etc.)
if (/^react($|\/)/.test(id)) return true;
if (/^react-dom($|\/)/.test(id)) return true;
if (id === 'scheduler') return true;
// Radix monorepo (@radix-ui/react-*)
if (/^@radix-ui\//.test(id)) return true;
if (id === 'class-variance-authority') return true;
// tanstack
if (/^@tanstack\//.test(id)) return true;
// Moodle AMD externals
if (['core/ajax', 'core/str', 'core/notification', 'jquery'].includes(id)) return true;
return false;
// NOTA: @inertiajs/react e @inertiajs/core NÃO estão em externals.
// O middag não expõe esses como chunks AMD dedicados; bundlamos
// no react-app.js do helico. Inertia é singleton por bundle, mas
// Vue e React nunca convivem no mesmo page lifetime (Moodle faz
// full reload entre plugins), logo não há conflito.
// Mesmo raciocínio para sonner e lucide-react.
},
output: {
format: 'amd',
dir: path.resolve(__dirname, 'dist'),
entryFileNames: '[name].js',
chunkFileNames: '[name].js',
paths: (id: string): string => {
if (/^react($|\/)/.test(id)) return 'local_middag/react-vendor-lazy';
if (/^react-dom($|\/)/.test(id)) return 'local_middag/react-vendor-lazy';
if (id === 'scheduler') return 'local_middag/react-vendor-lazy';
if (/^@radix-ui\//.test(id)) return 'local_middag/react-ui-lazy';
if (id === 'class-variance-authority') return 'local_middag/react-ui-lazy';
if (/^@tanstack\//.test(id)) return 'local_middag/react-table-lazy';
return id;
},
},
},
},
});Importante sobre possível fallback (B.1 temporário):
A dedup B.2 depende de que os chunks local_middag/react-vendor-lazy, react-ui-lazy e react-table-lazy exportem exatamente os símbolos que o helico importa. Como o middag faz tree-shaking, é possível que símbolos não usados pelo próprio middag tenham sido removidos e apareçam faltando em runtime.
Se o build da Task 1.5 ou do browser apresentar erro Cannot read properties of undefined (reading 'X') vindo de módulo local_middag/react-*-lazy:
-
Diagnóstico: abrir o chunk correspondente em
../middag/amd/src/react-ui-lazy.js(ou outro) e procurar pelo símbolo. Se faltar, o middag tree-shook. -
Fallback temporário (B.1): substituir a função
externalpor uma versão mais restrita que mantém só React/Radix/tanstack na dedup e deixa os símbolos faltantes no bundle do helico:external: (id) => { // Só aquilo que sabemos que middag exporta seguramente. if (id === 'react' || id === 'react-dom' || id === 'scheduler') return true; if (/^core\//.test(id) || id === 'jquery') return true; return false; }, paths: (id: string): string => { if (id === 'react' || id === 'react-dom' || id === 'scheduler') { return 'local_middag/react-vendor-lazy'; } return id; }, -
Abrir ticket no middag para expor os símbolos faltantes no chunk
react-ui-lazy(ex.: adicionar barrel import emregister-defaults.ts). -
Voltar ao B.2 completo após o middag atualizar os chunks.
Esse fallback é documentado aqui para não bloquear a entrega do piloto caso o acoplamento de chunks se mostre frágil.
- Step 2: Commit
git add local/helico/ui/vite.config.ts
git commit -m "feat(ui): adicionar vite.config.ts React com externals AMD"Task 1.3: Criar AMD wrapper inertia_app_react.js
Files:
-
Create:
amd/src/inertia_app_react.js -
Step 1: Criar o arquivo
/* eslint-disable */
/**
* Inertia app React bootstrap — thin AMD wrapper.
*
* Called by Moodle when a React-migrated Inertia page is rendered.
* Loading react-app triggers the Inertia SPA boot as a side-effect,
* same pattern used by local_middag/inertia_app.js.
*/
define(["local_helico/react-app"], function () {
return {
init: function () {
// Boot happens as side-effect of loading react-app.
// This init() satisfies the Moodle js_call_amd(module, 'init') contract.
}
};
});- Step 2: Commit
git add local/helico/amd/src/inertia_app_react.js
git commit -m "feat(amd): adicionar wrapper AMD inertia_app_react"Task 1.4: Criar scaffold React mínimo (main.tsx + inertia-app.tsx + page-resolver.ts + ErrorBoundary.tsx)
Files:
-
Create:
ui/src/main.tsx -
Create:
ui/src/app/inertia-app.tsx -
Create:
ui/src/app/page-resolver.ts -
Create:
ui/src/app/ErrorBoundary.tsx -
Step 1: Criar
ui/src/app/ErrorBoundary.tsx
import { Component, type ReactNode } from 'react';
interface Props {
children: ReactNode;
fallback?: ReactNode;
}
interface State {
hasError: boolean;
error: Error | null;
}
export class ErrorBoundary extends Component<Props, State> {
state: State = { hasError: false, error: null };
static getDerivedStateFromError(error: Error): State {
return { hasError: true, error };
}
componentDidCatch(error: Error, info: unknown) {
console.error('[ErrorBoundary]', error, info);
}
render() {
if (this.state.hasError) {
if (this.props.fallback) return this.props.fallback;
return (
<div style={{ padding: 24, color: 'crimson' }}>
<strong>Erro ao renderizar página.</strong>
<pre style={{ whiteSpace: 'pre-wrap', fontSize: 12 }}>
{this.state.error?.message}
</pre>
</div>
);
}
return this.props.children;
}
}- Step 2: Criar
ui/src/app/page-resolver.ts
Padrão import.meta.glob com eager: true — copia o padrão validado do middag. (Spec §3.5 preferia mapa explícito, mas o mapa explícito cria dependência circular com os arquivos de página e exige atualizar o resolver a cada nova página; o glob elimina esse acoplamento sem custo real — divergência aceita, registrada aqui.)
/**
* page-resolver — maps Inertia page names to dynamic imports.
*
* Uses Vite's import.meta.glob for build-time discovery. Eager=true keeps
* all migrated pages in the main bundle (piloto has 2 pages; can switch
* to lazy later without changing the public API).
*/
const pages = import.meta.glob('../pages/**/*.tsx', { eager: true }) as Record<
string,
Record<string, unknown>
>;
export function resolvePageComponent(name: string): unknown {
const path = `../pages/${name}.tsx`;
const mod = pages[path];
if (!mod) {
throw new Error(
`Page not found: ${name}. Available: ${Object.keys(pages).join(', ')}`,
);
}
return mod.default ?? mod;
}- Step 3: Criar
ui/src/app/inertia-app.tsx
/**
* inertia-app — Inertia React SPA bootstrap for local_helico.
*
* Adapted from local_middag/ui/src/app/inertia-app.tsx but simpler:
* no ContractPage registry, no custom providers beyond ErrorBoundary +
* sonner Toaster + appearance.
*/
import type { ReactNode } from 'react';
import { createInertiaApp } from '@inertiajs/react';
import { createRoot } from 'react-dom/client';
import { resolvePageComponent } from '@/app/page-resolver';
import { ErrorBoundary } from '@/app/ErrorBoundary';
import { Toaster } from '@middag/components/reui/sonner';
import {
setAppearance,
getStoredAppearance,
onSystemThemeChange,
} from '@middag/system/theme/appearance';
function ensurePortalContainer(): void {
if (document.getElementById('middag-portals')) return;
const container = document.createElement('div');
container.id = 'middag-portals';
container.classList.add('middag-root');
document.body.appendChild(container);
}
export default function startInertiaAppReact(): void {
setAppearance(getStoredAppearance());
onSystemThemeChange();
ensurePortalContainer();
createInertiaApp({
resolve: (name) => {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
return resolvePageComponent(name) as any;
},
setup({ el, App, props }: { el: HTMLElement; App: any; props: any }) {
createRoot(el).render(
<ErrorBoundary>
<Toaster position="top-right" richColors />
<App {...props} />
</ErrorBoundary>,
);
},
});
}- Step 4: Criar
ui/src/main.tsx
/**
* main — AMD entry point for the local_helico React frontend.
*
* Auto-boots the Inertia SPA on module load. Called indirectly by
* amd/src/inertia_app_react.js, which is loaded by Moodle via
* js_call_amd when inertia_manager::set_amd_module('local_helico/inertia_app_react').
*/
import '@middag/tailwind.css';
import startInertiaAppReact from '@/app/inertia-app';
startInertiaAppReact();- Step 5: Commit
git add local/helico/ui/src/
git commit -m "feat(ui): criar scaffold React (main, inertia-app, resolver, error boundary)"Task 1.5: Criar página placeholder DisciplinaIndex “hello React”
Essa versão mínima só existe para validar o pipeline. Será substituída pela versão com paridade completa no Phase 3.
Files:
-
Create:
ui/src/pages/admin/disciplina/Index.tsx -
Step 1: Criar o arquivo
import type { ReactElement } from 'react';
export default function DisciplinaIndexPage(): ReactElement {
return (
<div className="middag-root p-6">
<h1 className="text-2xl font-bold">Disciplinas (React)</h1>
<p className="mt-2 text-muted-foreground">
Página React renderizada via Inertia — placeholder do piloto.
</p>
</div>
);
}- Step 2: Rodar build para validar pipeline
cd ui && npm run build:reactExpected:
-
dist/react-app.jsgerado -
../amd/src/react-app.jscopiado pelo plugin -
../amd/build/react-app.min.jsgerado -
Sem erros de missing module em externals
-
Logs:
[moodle-amd] N chunk(s) → amd/src/ + amd/build/ -
Step 3: Verificar tamanho do bundle
ls -lh ../amd/src/react-app.jsExpected: arquivo com tamanho modesto (~30–80 KB). Se passar de 300 KB, algo furou os externals.
- Step 4: Commit
cd ../..
git add local/helico/ui/src/pages/ local/helico/amd/src/react-app.js local/helico/amd/build/react-app.min.js
git commit -m "feat(ui): adicionar placeholder DisciplinaIndex React + primeiro build"Task 1.6: Integrar PHP — helico.admin_controller aponta AMD para React
Files:
- Modify:
classes/extensions/admin/controller/admin_controller.php
Meta: para as rotas /disciplinas e /disciplinas/{id}/edit, chamar inertia_manager::set_amd_module('local_helico/inertia_app_react') antes de $this->inertia(...). Outras rotas Vue permanecem com o AMD Vue padrão.
- Step 1: Abrir
admin_controller.phpe adicionar helper privado
Adicionar import no topo:
use local_middag\framework\infrastructure\adapter\inertia\inertia_manager;Adicionar método privado na classe:
/**
* Switch Inertia AMD module to the React bootstrap for this response.
*/
private function use_react_inertia(): void
{
inertia_manager::set_amd_module('local_helico/inertia_app_react');
}- Step 2: Modificar
index()(rota/disciplinas)
#[Route(path: self::BASE_PATH_V1, name: 'helico_admin_disciplinas', methods: ['GET'])]
public function index(): Response
{
$this->set_require_login();
$this->set_page_layout('admin');
$this->set_page_title('Disciplinas');
$this->set_page_heading('Disciplinas');
$this->use_react_inertia();
return $this->inertia('admin/disciplina/Index', []);
}- Step 3: Modificar
edit()(rota/disciplinas/{id}/edit)
#[Route(path: self::BASE_PATH_V1 . '/{id}/edit', name: 'helico_admin_disciplinas_edit', methods: ['GET'])]
public function edit(int $id): Response
{
$this->set_require_login();
$this->set_page_layout('admin');
$this->set_page_title('Disciplinas');
$this->set_page_heading('Disciplinas');
$this->use_react_inertia();
return $this->inertia('admin/disciplina/Edit', [
'data' => middag::get(discipline_service::class)->view($id),
'id' => $id,
]);
}- Step 4: Verificação manual inicial — navegar para
/local/helico/index.php/disciplinas
Limpar cache Moodle (Admin → Purge all caches) e abrir:
https://<moodle-host>/local/helico/index.php/disciplinasExpected:
- Página carrega com o placeholder “Disciplinas (React) — Página React renderizada via Inertia”
- Network tab: chunks
local_middag/react-vendor-lazy,react-ui-lazy,react-table-lazy+local_helico/react-appcarregam um por um - Console sem erros de “more than one copy of React” ou “Invalid hook call”
Se não renderizar: olhar o console para ver qual módulo AMD não resolveu, ajustar external/paths em vite.config.ts e rebuildar.
- Step 5: Commit
git add local/helico/classes/extensions/admin/controller/admin_controller.php
git commit -m "feat(backend): usar inertia_app_react nas rotas de disciplina
Placeholder React renderiza em /disciplinas e /disciplinas/{id}/edit.
Outras rotas continuam com o Inertia-Vue padrão."Task 1.7: Verificar não-regressão em rota Vue
- Step 1: Abrir uma rota Vue não migrada no Moodle
Exemplos:
https://<moodle-host>/local/helico/index.php/trilha/1(ou qualquer outra rota que use admin_controller fora de /disciplinas)
Expected:
- Página Vue renderiza normalmente
- Console sem erros novos
app.js(Vue) é carregado, nãoreact-app.js
Se a rota Vue quebrar, revisar use_react_inertia() para garantir que só é chamado nas duas rotas alvo.
- Step 2 — não comita, é só verificação
Phase 2 — Utilitários compartilhados
Task 2.1: Portar baseApiService.ts
Files:
-
Create:
ui/src/services/baseApiService.ts -
Step 1: Copiar o conteúdo de
ui/src-vue/services/baseApiService.tsparaui/src/services/baseApiService.ts
import axios, { AxiosInstance, AxiosResponse } from 'axios';
const API_BASE_URL = `${window.location.origin}/local/helico/index.php/helico/content/api/v1`;
const api: AxiosInstance = axios.create({
baseURL: API_BASE_URL,
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json',
},
timeout: 6000000,
});
api.interceptors.request.use(
(config) => {
const token = localStorage.getItem('token');
if (token) {
config.headers.Authorization = `Bearer ${token}`;
}
return config;
},
(error) => Promise.reject(error),
);
api.interceptors.response.use(
(response: AxiosResponse) => response,
(error) => {
console.error('Erro na requisição:', error.response || error);
return Promise.reject(error);
},
);
class BaseApiService {
static async get<T>(url: string, params?: Record<string, unknown>): Promise<T> {
const response = await api.get<T>(url, { params });
return response.data;
}
static async post<T>(url: string, data?: unknown, config?: unknown): Promise<T> {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const response = await api.post<T>(url, data, config as any);
return response.data;
}
static async put<T>(url: string, data?: unknown): Promise<T> {
const response = await api.put<T>(url, data);
return response.data;
}
static async delete<T>(url: string): Promise<T> {
const response = await api.delete<T>(url);
return response.data;
}
}
export default BaseApiService;- Step 2: Commit
git add local/helico/ui/src/services/baseApiService.ts
git commit -m "feat(ui): portar baseApiService.ts para pipeline React"Task 2.2: Portar disciplinaApiService.ts e syncApiService.ts
Files:
-
Create:
ui/src/services/disciplinaApiService.ts -
Create:
ui/src/services/syncApiService.ts -
Step 1: Criar
ui/src/services/disciplinaApiService.ts
import BaseApiService from './baseApiService';
const BASE = '/disciplinas';
export interface DisciplinaListParams {
page?: number;
limit?: number;
fullname?: string;
}
export interface DisciplinaListResponse {
data: FileRow[];
totalcount: number;
synchronizing: boolean;
}
export interface FileRow {
id: number;
idnumber: string;
fullname: string;
status: string;
lastprocess: string;
urledit: string;
is_processing?: boolean;
}
class DisciplinaApiService {
static list(params?: DisciplinaListParams) {
return BaseApiService.get<{
success: boolean;
content: DisciplinaListResponse;
code?: number;
message?: string;
}>(BASE, params);
}
static listProcessed() {
return BaseApiService.get<{
success: boolean;
content: { id: number; idnumber: string; fullname: string }[];
}>(`${BASE}/processed`);
}
static delete(id: number) {
return BaseApiService.delete<{ success: boolean; content: string }>(`${BASE}/${id}`);
}
static saveFilename(id: number, fullname: string) {
return BaseApiService.post<{ success: boolean; content: string }>(
`${BASE}/${id}/update`,
{ fullname },
);
}
// eslint-disable-next-line @typescript-eslint/no-explicit-any
static getEditData(id: number) {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
return BaseApiService.get<{ success: boolean; content: any }>(`${BASE}/${id}/edit`);
}
// eslint-disable-next-line @typescript-eslint/no-explicit-any
static startProcess(id: number) {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
return BaseApiService.post<{ success: boolean; content: any }>(`${BASE}/${id}/process`);
}
static startFlashcardProcess(id: number) {
return BaseApiService.post<{ success: boolean; content: string }>(
`${BASE}/${id}/flashcard-process`,
);
}
}
export default DisciplinaApiService;- Step 2: Criar
ui/src/services/syncApiService.ts
import BaseApiService from './baseApiService';
const BASE = '/sync';
export interface CohortItem {
id: number | string;
name: string;
}
export interface DisciplineItem {
id: number | string;
idnumber: string;
qtd_unidades: number;
name: string;
}
class SyncApiService {
static getCohorts() {
return BaseApiService.get<{ success: boolean; content: CohortItem[] }>(
`${BASE}/cohorts`,
);
}
static getDisciplines() {
return BaseApiService.get<{ success: boolean; content: DisciplineItem[] }>(
`${BASE}/disciplinas`,
);
}
static startSync() {
return BaseApiService.post<{
success: boolean;
// eslint-disable-next-line @typescript-eslint/no-explicit-any
content: any[];
code?: number;
message?: string;
}>(`${BASE}/start`);
}
}
export default SyncApiService;- Step 3: Commit
git add local/helico/ui/src/services/disciplinaApiService.ts local/helico/ui/src/services/syncApiService.ts
git commit -m "feat(ui): portar disciplinaApiService e syncApiService"Task 2.3: Criar hook useServerPolling
Files:
-
Create:
ui/src/hooks/useServerPolling.ts -
Step 1: Criar o hook
import { useEffect, useRef } from 'react';
interface Options {
active: boolean;
intervalMs: number;
onTick: () => void | Promise<void>;
}
/**
* Polls a side-effect at a fixed interval while `active` is true.
*
* Guards against double-start, clears timer when `active` flips to false,
* and always clears on unmount.
*/
export function useServerPolling({ active, intervalMs, onTick }: Options): void {
const timerRef = useRef<number | null>(null);
const onTickRef = useRef(onTick);
useEffect(() => {
onTickRef.current = onTick;
}, [onTick]);
useEffect(() => {
if (!active) {
if (timerRef.current !== null) {
window.clearInterval(timerRef.current);
timerRef.current = null;
}
return;
}
if (timerRef.current !== null) return;
timerRef.current = window.setInterval(() => {
void onTickRef.current();
}, intervalMs);
return () => {
if (timerRef.current !== null) {
window.clearInterval(timerRef.current);
timerRef.current = null;
}
};
}, [active, intervalMs]);
}- Step 2: Commit
git add local/helico/ui/src/hooks/useServerPolling.ts
git commit -m "feat(ui): criar hook useServerPolling"Task 2.4: Criar componente ConfirmDialog
Files:
-
Create:
ui/src/components/ConfirmDialog.tsx -
Step 1: Criar o componente
import type { ReactNode } from 'react';
import {
Dialog,
DialogContent,
DialogFooter,
DialogHeader,
DialogTitle,
} from '@middag/components/reui/dialog';
import { Button } from '@middag/components/reui/button';
interface Props {
open: boolean;
title: string;
children: ReactNode;
loading?: boolean;
onCancel: () => void;
onConfirm: () => void;
confirmLabel?: string;
cancelLabel?: string;
intent?: 'primary' | 'danger';
}
export function ConfirmDialog({
open,
title,
children,
loading = false,
onCancel,
onConfirm,
confirmLabel = 'Confirmar',
cancelLabel = 'Cancelar',
intent = 'primary',
}: Props) {
return (
<Dialog open={open} onOpenChange={(v) => !v && !loading && onCancel()}>
<DialogContent className="middag-root sm:max-w-md">
<DialogHeader>
<DialogTitle>{title}</DialogTitle>
</DialogHeader>
<div className="py-2">{children}</div>
<DialogFooter>
<Button
variant="outline"
onClick={onCancel}
disabled={loading}
>
{cancelLabel}
</Button>
<Button
variant={intent === 'danger' ? 'destructive' : 'default'}
onClick={onConfirm}
disabled={loading}
>
{confirmLabel}
</Button>
</DialogFooter>
</DialogContent>
</Dialog>
);
}- Step 2: Rodar build para confirmar que os imports do @middag resolvem
cd ui && npm run build:reactExpected: build passa sem “Cannot find module ‘@middag/components/reui/dialog’”. Se falhar, inspecionar components.json do middag e confirmar path exato.
- Step 3: Commit
cd ../..
git add local/helico/ui/src/components/ConfirmDialog.tsx
git commit -m "feat(ui): criar ConfirmDialog wrapper local sobre @middag/components/reui/dialog"Phase 3 — DisciplinaIndex com paridade completa
Task 3.1: Esqueleto do Index.tsx — estado + loadData + DataGrid mínimo
Files:
-
Modify:
ui/src/pages/admin/disciplina/Index.tsx(sobrescreve placeholder) -
Step 1: Substituir o conteúdo do arquivo
import { useEffect, useState, type ReactElement } from 'react';
import { router } from '@inertiajs/react';
import DisciplinaApiService, {
type FileRow,
} from '@/services/disciplinaApiService';
export default function DisciplinaIndexPage(): ReactElement {
const [files, setFiles] = useState<FileRow[]>([]);
const [totalRecords, setTotalRecords] = useState(0);
const [loading, setLoading] = useState(false);
const [page, setPage] = useState(0);
const [perPage, setPerPage] = useState(10);
const [fullnameFilter, setFullnameFilter] = useState('');
const [loadingSync, setLoadingSync] = useState(false);
const loadData = async (silent = false) => {
if (!silent) setLoading(true);
try {
const data = await DisciplinaApiService.list({
page,
limit: perPage,
fullname: fullnameFilter || undefined,
});
setFiles(data.content.data ?? []);
setLoadingSync(Boolean(data.content.synchronizing));
setTotalRecords(data.content.totalcount ?? 0);
} catch (err) {
console.error('Erro ao carregar files:', err);
} finally {
if (!silent) setLoading(false);
}
};
useEffect(() => {
void loadData();
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [page, perPage]);
return (
<div className="middag-root p-6">
<h1 className="mb-4 text-2xl font-bold">Disciplinas</h1>
<div className="mb-4 rounded border bg-white p-4">
<p>Total: {totalRecords}</p>
<p>Carregando: {loading ? 'sim' : 'não'}</p>
<p>Sincronizando: {loadingSync ? 'sim' : 'não'}</p>
<ul className="mt-2 list-disc pl-4">
{files.map((f) => (
<li key={f.id}>
{f.idnumber} — {f.fullname}
</li>
))}
</ul>
</div>
</div>
);
}Nota: essa primeira versão usa <ul> em vez do DataGrid para confirmar que loadData funciona. Próxima task troca para DataGrid.
- Step 2: Rodar build + abrir
/disciplinasno browser
cd ui && npm run build:reactExpected: lista de disciplinas aparece, totalRecords não é zero.
- Step 3: Commit
cd ../..
git add local/helico/ui/src/pages/ local/helico/amd/
git commit -m "feat(ui): Index.tsx com fetch funcional (lista simples)"Task 3.2: Substituir <ul> por <DataGrid> com colunas id/idnumber/fullname/lastprocess
Files:
- Modify:
ui/src/pages/admin/disciplina/Index.tsx
O componente data-grid do middag é baseado em tanstack. Vamos usar a API declarativa de @middag/components/reui/data-grid/data-grid.tsx.
- Step 1: Abrir
../middag/ui/src/components/reui/data-grid/data-grid.tsxe ler a API exportada
Objetivo: descobrir a signature do <DataGrid> e das colunas. Ler o arquivo e anotar:
- Nome do componente principal exportado
- Props aceitas (rows, columns, pagination, etc.)
- Se aceita
rowActionsinline
Se a API for mais complexa que o esperado, usar <DataGridTable> + <DataGridPagination> separados e compor manualmente (padrão equivalente ao connectors/Index do middag que já funciona).
- Step 2: Modificar
Index.tsxpara usar<DataGrid>real
(Código completo abaixo — os nomes exatos dos imports podem precisar ajuste após Step 1.)
import { useEffect, useState, type ReactElement } from 'react';
import { router } from '@inertiajs/react';
import { DataGrid, DataGridTable, DataGridPagination } from '@middag/components/reui/data-grid';
import type { ColumnDef } from '@tanstack/react-table';
import { Pencil, Trash2 } from 'lucide-react';
import { Button } from '@middag/components/reui/button';
import DisciplinaApiService, {
type FileRow,
} from '@/services/disciplinaApiService';
export default function DisciplinaIndexPage(): ReactElement {
const [files, setFiles] = useState<FileRow[]>([]);
const [totalRecords, setTotalRecords] = useState(0);
const [loading, setLoading] = useState(false);
const [page, setPage] = useState(0);
const [perPage, setPerPage] = useState(10);
const [fullnameFilter, setFullnameFilter] = useState('');
const [loadingSync, setLoadingSync] = useState(false);
const loadData = async (silent = false) => {
if (!silent) setLoading(true);
try {
const data = await DisciplinaApiService.list({
page,
limit: perPage,
fullname: fullnameFilter || undefined,
});
setFiles(data.content.data ?? []);
setLoadingSync(Boolean(data.content.synchronizing));
setTotalRecords(data.content.totalcount ?? 0);
} catch (err) {
console.error('Erro ao carregar files:', err);
} finally {
if (!silent) setLoading(false);
}
};
useEffect(() => {
void loadData();
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [page, perPage]);
const columns: ColumnDef<FileRow>[] = [
{ accessorKey: 'id', header: '#' },
{ accessorKey: 'idnumber', header: 'ID number' },
{ accessorKey: 'fullname', header: 'Nome completo' },
{
accessorKey: 'status',
header: 'Status',
cell: ({ row }) => (
<div dangerouslySetInnerHTML={{ __html: row.original.status }} />
),
},
{ accessorKey: 'lastprocess', header: 'Último processamento' },
{
id: 'actions',
header: 'Ações',
cell: ({ row }) => (
<div className="flex items-center gap-1">
<Button
variant="ghost"
size="sm"
onClick={() => router.visit(row.original.urledit)}
>
<Pencil className="h-4 w-4" />
</Button>
<Button
variant="ghost"
size="sm"
className="text-destructive"
onClick={() => {/* placeholder — preenchido na Task 3.3 */}}
>
<Trash2 className="h-4 w-4" />
</Button>
</div>
),
},
];
return (
<div className="middag-root p-6">
<h1 className="mb-4 text-2xl font-bold">Disciplinas</h1>
<DataGrid
columns={columns}
data={files}
rowCount={totalRecords}
isLoading={loading}
>
<DataGridTable />
<DataGridPagination />
</DataGrid>
</div>
);
}- Step 3: Build + verificar no browser
cd ui && npm run build:reactExpected: tabela renderiza com 5 colunas + ações. Console limpo.
Se a API de DataGrid for diferente da suposta, ajustar imports e props de acordo com o arquivo real lido no Step 1.
- Step 4: Commit
cd ../..
git add local/helico/ui/src/pages/ local/helico/amd/
git commit -m "feat(ui): Index.tsx usando DataGrid com colunas e ações esqueleto"Task 3.3: Delete com ConfirmDialog + toast de erro
Files:
-
Modify:
ui/src/pages/admin/disciplina/Index.tsx -
Step 1: Adicionar imports no topo
import { toast } from 'sonner';
import { ConfirmDialog } from '@/components/ConfirmDialog';- Step 2: Adicionar estado para modal e item
Dentro do componente, após loadingSync:
const [deleteModalOpen, setDeleteModalOpen] = useState(false);
const [deleteItemId, setDeleteItemId] = useState<number | null>(null);
const [deleting, setDeleting] = useState(false);- Step 3: Adicionar função
confirmDeleteFile
Antes do return:
const openDeleteModal = (id: number) => {
setDeleteItemId(id);
setDeleteModalOpen(true);
};
const confirmDeleteFile = async () => {
if (!deleteItemId) return;
setDeleting(true);
try {
const { success } = await DisciplinaApiService.delete(deleteItemId);
if (success) {
await loadData();
setDeleteItemId(null);
setDeleteModalOpen(false);
return;
}
toast.error('Erro ao excluir registro.');
} catch (err) {
console.error('Erro ao excluir file:', err);
toast.error('Erro ao excluir registro.');
} finally {
setDeleting(false);
}
};- Step 4: Trocar o handler placeholder da lixeira
onClick={() => openDeleteModal(row.original.id)}- Step 5: Adicionar
<ConfirmDialog>no fim do JSX, antes de</div>
<ConfirmDialog
open={deleteModalOpen}
title="Confirmação de exclusão"
loading={deleting}
onCancel={() => setDeleteModalOpen(false)}
onConfirm={() => void confirmDeleteFile()}
confirmLabel="Excluir"
intent="danger"
>
<div className="flex flex-col items-center gap-3 py-2">
<Trash2 className="h-12 w-12 text-destructive" />
<p>Você está prestes a excluir esse registro.</p>
<p>Essa ação não poderá ser desfeita.</p>
</div>
</ConfirmDialog>- Step 6: Build + UAT
cd ui && npm run build:reactNo browser: clicar lixeira → modal abre → Cancelar fecha → Excluir remove linha.
- Step 7: Commit
cd ../..
git add local/helico/ui/src/pages/ local/helico/amd/
git commit -m "feat(ui): Index.tsx delete com ConfirmDialog + toast de erro"Task 3.4: Botão “Sincronizar arquivos” + modal de confirmação + estado loading
Files:
-
Modify:
ui/src/pages/admin/disciplina/Index.tsx -
Step 1: Importar
RefreshCwde lucide eSyncApiService
import { Pencil, Trash2, RefreshCw } from 'lucide-react';
import SyncApiService from '@/services/syncApiService';- Step 2: Adicionar estado do modal de sync
const [syncModalOpen, setSyncModalOpen] = useState(false);- Step 3: Adicionar função de disparo de sync
const registerStartSyncFiles = async () => {
setSyncModalOpen(false);
setLoadingSync(true);
try {
const { success, code, message } = await SyncApiService.startSync();
if (success) {
await loadData();
return;
}
if (code === 1001) {
console.error(message);
return;
}
console.error('Erro ao iniciar a sincronização.');
} catch (err) {
console.error('Erro ao iniciar sincronização:', err);
}
};- Step 4: Adicionar barra de topo com botão de sync antes da tabela
Dentro do JSX, antes do <DataGrid>:
<div className="mb-5 flex items-center justify-end">
<Button
disabled={loadingSync}
onClick={() => setSyncModalOpen(true)}
>
<RefreshCw className={`mr-2 h-4 w-4 ${loadingSync ? 'animate-spin' : ''}`} />
Sincronizar arquivos
</Button>
</div>- Step 5: Adicionar
<ConfirmDialog>de sync no final
<ConfirmDialog
open={syncModalOpen}
title="Confirmação de sincronização"
onCancel={() => setSyncModalOpen(false)}
onConfirm={() => void registerStartSyncFiles()}
>
<div className="flex flex-col items-center gap-3 py-2">
<RefreshCw className="h-12 w-12 text-amber-500" />
<p>Você está prestes a iniciar a sincronização dos arquivos.</p>
</div>
</ConfirmDialog>- Step 6: Build + UAT
cd ui && npm run build:reactBrowser: botão “Sincronizar” visível → modal abre → Confirmar dispara POST → botão vira loading.
- Step 7: Commit
cd ../..
git add local/helico/ui/src/pages/ local/helico/amd/
git commit -m "feat(ui): Index.tsx botão Sincronizar + modal de confirmação + loading state"Task 3.5: Filtro por fullname + botão “Atualizar”
Files:
-
Modify:
ui/src/pages/admin/disciplina/Index.tsx -
Step 1: Importar
InputeSearch
import { Pencil, Trash2, RefreshCw, Search } from 'lucide-react';
import { Input } from '@middag/components/reui/input';- Step 2: Adicionar função
onFilter
const onFilter = () => {
setPage(0);
void loadData();
};- Step 3: Ajustar
useEffectpara também recarregar quandofullnameFiltermudar (debounce nativo via Enter + onInput vem depois se necessário)
Manter o useEffect como está — a recarga por filtro acontece via onFilter (Enter ou botão).
- Step 4: Adicionar barra de filtros acima da tabela, entre o botão de sync e o DataGrid
<div className="mb-3 flex flex-wrap items-center justify-between gap-3">
<div className="flex items-end gap-3">
<Input
id="fullname"
value={fullnameFilter}
placeholder="Digite o nome"
onChange={(e) => setFullnameFilter(e.target.value)}
onKeyUp={(e) => e.key === 'Enter' && onFilter()}
/>
<Button onClick={onFilter}>
<Search className="mr-2 h-4 w-4" />
Filtrar
</Button>
</div>
<div className="flex items-center gap-3">
<Button
disabled={loading}
onClick={() => void loadData()}
>
<RefreshCw className={`mr-2 h-4 w-4 ${loading ? 'animate-spin' : ''}`} />
Atualizar
</Button>
</div>
</div>- Step 5: Build + UAT
cd ui && npm run build:reactBrowser: digitar no input e Enter → tabela filtra. Botão Filtrar também funciona. Botão Atualizar recarrega.
- Step 6: Commit
cd ../..
git add local/helico/ui/src/pages/ local/helico/amd/
git commit -m "feat(ui): Index.tsx filtro por fullname + botão Atualizar"Task 3.6: Polling via useServerPolling
Files:
-
Modify:
ui/src/pages/admin/disciplina/Index.tsx -
Step 1: Importar o hook
import { useServerPolling } from '@/hooks/useServerPolling';- Step 2: Adicionar a lógica de polling no componente
Antes do return:
const hasActiveProcessing = loadingSync || files.some((f) => Boolean(f.is_processing));
useServerPolling({
active: hasActiveProcessing,
intervalMs: 4000,
onTick: () => loadData(true),
});- Step 3: Build + UAT
cd ui && npm run build:reactBrowser: disparar sincronização → loadingSync=true → polling inicia → tabela atualiza a cada 4s sem flicker de loading global → quando backend indicar synchronizing=false e nenhum is_processing, polling para.
- Step 4: Commit
cd ../..
git add local/helico/ui/src/pages/ local/helico/amd/
git commit -m "feat(ui): Index.tsx polling automático via useServerPolling"Task 3.7: UAT completo do Index
Verificação manual — sem código. Rodar no Moodle:
- Abre
/local/helico/index.php/disciplinas— tabela renderiza com paginação - Filtro: digitar texto → Enter → tabela filtra
- Paginação: clicar próxima página → recarrega com page+1
- Botão Sincronizar → modal → Confirmar → dispara POST, botão vira loading
- Polling inicia enquanto sync ativa; para quando backend indica fim
- Ícone lápis → navega para
/disciplinas/{id}/edit(ainda placeholder, será real no Phase 4) via Inertia - Ícone lixeira → modal → Confirmar → linha some
- Coluna Status renderiza HTML (spans com cores)
- Console sem warning “multiple copies of React” ou “Invalid hook call”
Se algum item falhar, abrir task isolada para corrigir e continuar o plano. Não prosseguir para Phase 4 com Index quebrado.
Phase 4 — DisciplinaEdit com paridade completa
Task 4.1: Criar rules.ts com as funções de negócio
Files:
-
Create:
ui/src/pages/admin/disciplina/rules.ts -
Step 1: Criar o arquivo
/**
* Regras de negócio do Edit de disciplina.
*
* Portadas 1:1 do Edit.vue para que a decisão de disabled/tooltip fique
* isolada do componente e possa ser revisada independentemente.
*/
export interface VersionRow {
id: number | string;
fileId: number | string;
status: string;
displaystatus: string;
unidadeProcessStatus?: string;
flashcardsStatus?: string;
flashcards: string | number;
unidades: string | number;
flashcardsProcessing: boolean;
name: string;
version: number | string;
url: string;
markdownurl: string;
}
export interface WidgetStateView {
isProcessing: boolean;
flashcardsProcessing: boolean;
}
const DISABLED_STATUSES = ['new'] as const;
export function canShowFlashcardsBtn(item: VersionRow): boolean {
return (
item.markdownurl.length > 0 &&
!['completed', 'archived'].includes(item.flashcardsStatus as string)
);
}
export function getFlashcardsDisabledReason(
item: VersionRow,
versions: VersionRow[],
state: WidgetStateView,
): string {
const lastFileVersion = versions.find(
(v) => Number(v.version) === versions.length,
);
const isNotLastVersion = lastFileVersion?.id !== item.id;
const lastVersionIsNew =
isNotLastVersion &&
DISABLED_STATUSES.includes(lastFileVersion?.status as typeof DISABLED_STATUSES[number]);
if (item.markdownurl.length === 0) {
return 'O arquivo markdown não está disponível.';
}
if (DISABLED_STATUSES.includes(item.status as typeof DISABLED_STATUSES[number])) {
return 'As unidades estão pendentes de processamento.';
}
if (lastVersionIsNew) {
return 'A alteração mais recente do arquivo ainda está pendente de processamento.';
}
if (state.isProcessing) {
return 'Aguarde o processamento do arquivo.';
}
if (state.flashcardsProcessing) {
return 'Já existe uma geração de flashcards em andamento.';
}
return '';
}
export function btnFlashcardsIsDisable(
item: VersionRow,
versions: VersionRow[],
state: WidgetStateView,
): boolean {
return getFlashcardsDisabledReason(item, versions, state).length > 0;
}
export function getProcessDisabledReason(
item: VersionRow,
state: WidgetStateView,
): string {
if (state.isProcessing) {
return 'Já existe um processamento em andamento.';
}
if (item.flashcardsProcessing) {
return 'Aguarde a geração de flashcards ser concluída.';
}
return '';
}
export function btnProcessIsDisable(
item: VersionRow,
state: WidgetStateView,
): boolean {
return getProcessDisabledReason(item, state).length > 0;
}- Step 2: Commit
git add local/helico/ui/src/pages/admin/disciplina/rules.ts
git commit -m "feat(ui): rules.ts com funções de negócio do Edit de disciplina"Task 4.2: Esqueleto do Edit.tsx — props Inertia, applyData, form base
Files:
-
Create:
ui/src/pages/admin/disciplina/Edit.tsx -
Step 1: Criar o arquivo
import { useEffect, useState, type ReactElement } from 'react';
import { router, usePage } from '@inertiajs/react';
import {
Card,
CardContent,
CardHeader,
CardTitle,
} from '@middag/components/reui/card';
import { Input } from '@middag/components/reui/input';
import { Button } from '@middag/components/reui/button';
import { Separator } from '@middag/components/reui/separator';
import { Badge } from '@middag/components/reui/badge';
import { toast } from 'sonner';
import DisciplinaApiService from '@/services/disciplinaApiService';
import type { VersionRow } from './rules';
interface WidgetFile {
id?: string | number;
fileid?: string | number;
status?: string;
displaystatus?: string;
unidadeProcessStatus?: string;
flashcardsStatus?: string;
flashcards?: string | number;
unidades?: string | number;
flashcardsProcessing?: boolean;
fullname?: string;
version?: string | number;
url?: string;
markdownurl: string;
}
interface WidgetData {
id?: string | number;
idnumber?: string;
status?: string;
isProcessing?: boolean;
flashcardsProcessing?: boolean;
fullname?: string;
categoryname?: string;
files?: WidgetFile[];
}
interface FormState {
id: string;
fullName: string;
categoryName: string;
identifier: string;
}
interface WidgetState {
id: string;
status: string;
isProcessing: boolean;
flashcardsProcessing: boolean;
}
export default function DisciplinaEditPage(): ReactElement {
const { props } = usePage<{ data: WidgetData; id: string | number }>();
const [form, setForm] = useState<FormState>({
id: '',
fullName: '',
categoryName: '',
identifier: '',
});
const [widgetState, setWidgetState] = useState<WidgetState>({
id: '',
status: '',
isProcessing: false,
flashcardsProcessing: false,
});
const [versions, setVersions] = useState<VersionRow[]>([]);
const [showValidation, setShowValidation] = useState(false);
const [saving, setSaving] = useState(false);
const applyData = (data: WidgetData | undefined) => {
if (!data) return;
setForm({
id: String(data.id ?? ''),
fullName: data.fullname ?? '',
categoryName: data.categoryname ?? '',
identifier: data.idnumber ?? '',
});
setWidgetState({
id: String(data.id ?? ''),
status: String(data.status ?? ''),
isProcessing: Boolean(data.isProcessing),
flashcardsProcessing: Boolean(data.flashcardsProcessing),
});
setVersions(
(data.files ?? []).map((file) => ({
id: file.id ?? '',
fileId: file.fileid ?? '',
status: file.status ?? '',
displaystatus: file.displaystatus ?? '',
flashcardsStatus: file.flashcardsStatus,
unidadeProcessStatus: file.unidadeProcessStatus,
flashcards: file.flashcards ?? '',
unidades: file.unidades ?? '',
flashcardsProcessing: Boolean(file.flashcardsProcessing),
name: file.fullname ?? '',
version: file.version ?? '',
url: file.url ?? '',
markdownurl: file.markdownurl ?? '',
})),
);
};
useEffect(() => {
applyData(props.data);
}, [props.data]);
const redirectToHome = () => {
router.visit('/local/helico/index.php/disciplinas');
};
const save = async () => {
setShowValidation(true);
if (!form.fullName.trim()) return;
setSaving(true);
try {
const response = await DisciplinaApiService.saveFilename(
Number(widgetState.id || props.id || 0),
form.fullName,
);
if (!response?.success) {
toast.error(String(response?.content ?? 'Erro ao salvar'));
return;
}
redirectToHome();
} catch {
toast.error('Falha ao salvar os dados.');
} finally {
setSaving(false);
}
};
return (
<div className="middag-root py-4">
<Card className="shadow-sm">
<CardHeader>
<div className="flex flex-wrap items-start justify-between gap-3">
<div>
<CardTitle className="mb-1 text-2xl font-bold">
Sincronização de arquivos
</CardTitle>
<p className="mb-0 text-muted-foreground">
Gerencie os dados da unidade e as versões dos arquivos sincronizados.
</p>
</div>
<Badge variant="outline">
{versions.length} {versions.length === 1 ? 'versão' : 'versões'}
</Badge>
</div>
</CardHeader>
<CardContent>
<div className="grid grid-cols-1 gap-4 lg:grid-cols-3">
<div>
<label htmlFor="fullName" className="mb-2 block font-semibold">
Nome completo
</label>
<Input
id="fullName"
value={form.fullName}
onChange={(e) => setForm({ ...form, fullName: e.target.value })}
placeholder="Informe o nome completo"
aria-invalid={showValidation && !form.fullName.trim()}
/>
{showValidation && !form.fullName.trim() && (
<small className="mt-2 block text-destructive">
Campo obrigatório.
</small>
)}
</div>
<div>
<label htmlFor="categoryName" className="mb-2 block font-semibold">
Nome da categoria
</label>
<Input
id="categoryName"
value={form.categoryName}
disabled
/>
</div>
<div>
<label htmlFor="identifier" className="mb-2 block font-semibold">
Número de identificação
</label>
<Input id="identifier" value={form.identifier} disabled />
</div>
</div>
<Separator className="my-4" />
<div className="mb-3">
<h3 className="mb-1 text-lg font-semibold">Alterações</h3>
<p className="text-sm text-muted-foreground">
Arquivos disponíveis para download e ações da sincronização.
</p>
</div>
{/* Tabela de versões — Task 4.3 */}
<div className="mt-4 flex justify-end gap-2">
<Button variant="outline" onClick={redirectToHome}>
Cancelar
</Button>
<Button onClick={() => void save()} disabled={saving}>
Salvar
</Button>
</div>
</CardContent>
</Card>
</div>
);
}- Step 2: Build + UAT inicial
cd ui && npm run build:reactBrowser: abrir /disciplinas/{id}/edit → Card renderiza, form com 3 campos, Save/Cancel funcionam. Não há tabela de versões ainda.
- Step 3: Commit
cd ../..
git add local/helico/ui/src/pages/admin/disciplina/Edit.tsx local/helico/amd/
git commit -m "feat(ui): Edit.tsx com Card + form + save/cancel"Task 4.3: Tabela de versões dentro do Edit
Files:
-
Modify:
ui/src/pages/admin/disciplina/Edit.tsx -
Step 1: Importar DataGrid e Button
Adicionar no topo:
import { DataGrid, DataGridTable, DataGridPagination } from '@middag/components/reui/data-grid';
import type { ColumnDef } from '@tanstack/react-table';
import { FileText, FileCode } from 'lucide-react';- Step 2: Definir as colunas dentro do componente
Antes do return:
const versionColumns: ColumnDef<VersionRow>[] = [
{ accessorKey: 'id', header: '#' },
{ accessorKey: 'name', header: 'Nome' },
{
accessorKey: 'displaystatus',
header: 'Status',
cell: ({ row }) => (
<div dangerouslySetInnerHTML={{ __html: row.original.displaystatus }} />
),
},
{ accessorKey: 'unidades', header: 'Unidades' },
{ accessorKey: 'flashcards', header: 'Flashcards' },
{ accessorKey: 'version', header: 'Versão' },
{
id: 'files',
header: 'Arquivos',
cell: ({ row }) => (
<div className="flex items-center justify-center gap-1">
{row.original.url && (
<a
href={row.original.url}
rel="noopener noreferrer"
aria-label="Baixar arquivo Word"
>
<Button variant="ghost" size="sm">
<FileText className="h-4 w-4" />
</Button>
</a>
)}
{row.original.markdownurl && (
<a
href={row.original.markdownurl}
rel="noopener noreferrer"
aria-label="Baixar markdown"
>
<Button variant="ghost" size="sm">
<FileCode className="h-4 w-4" />
</Button>
</a>
)}
</div>
),
},
{
id: 'actions',
header: 'Ações',
cell: () => null, // preenchido na Task 4.4
},
];- Step 3: Inserir
<DataGrid>no JSX (onde o comentário{/* Tabela de versões */}está)
<DataGrid columns={versionColumns} data={versions} rowCount={versions.length}>
<DataGridTable />
<DataGridPagination />
</DataGrid>- Step 4: Build + UAT
cd ui && npm run build:reactBrowser: tabela renderiza com 7 colunas (última vazia), downloads funcionam.
- Step 5: Commit
cd ../..
git add local/helico/ui/src/pages/admin/disciplina/Edit.tsx local/helico/amd/
git commit -m "feat(ui): Edit.tsx tabela de versões + downloads"Task 4.4: Botões de ação “Processar” e “Flashcards” + tooltips
Files:
-
Modify:
ui/src/pages/admin/disciplina/Edit.tsx -
Step 1: Importar ícones, Tooltip e rules
import { FileText, FileCode, RefreshCw, Zap } from 'lucide-react';
import {
Tooltip,
TooltipContent,
TooltipProvider,
TooltipTrigger,
} from '@middag/components/reui/tooltip';
import {
btnFlashcardsIsDisable,
btnProcessIsDisable,
canShowFlashcardsBtn,
getFlashcardsDisabledReason,
getProcessDisabledReason,
} from './rules';- Step 2: Adicionar estado dos dialogs de ação
Junto dos demais states:
const [processDialog, setProcessDialog] = useState<{
open: boolean;
loading: boolean;
file: VersionRow | null;
}>({ open: false, loading: false, file: null });
const [flashcardsDialog, setFlashcardsDialog] = useState<{
open: boolean;
loading: boolean;
file: VersionRow | null;
}>({ open: false, loading: false, file: null });- Step 3: Adicionar handlers (stubs — preenchidos nas Tasks 4.5 e 4.6)
const openProcessDialog = (file: VersionRow) => {
setProcessDialog({ open: true, loading: false, file });
};
const openFlashcardsDialog = (file: VersionRow) => {
setFlashcardsDialog({ open: true, loading: false, file });
};- Step 4: Substituir a célula de
actionsnas colunas
{
id: 'actions',
header: 'Ações',
cell: ({ row }) => {
const item = row.original;
const isLastVersion = Number(item.version) === versions.length;
const showProcess = isLastVersion && item.unidadeProcessStatus !== 'completed';
const showFlashcards = canShowFlashcardsBtn(item);
const processDisabled = btnProcessIsDisable(item, widgetState);
const flashcardsDisabled = btnFlashcardsIsDisable(item, versions, widgetState);
return (
<div className="flex flex-wrap items-center justify-center gap-2">
{showProcess && (
<Button
variant="outline"
size="sm"
disabled={processDisabled || widgetState.isProcessing}
onClick={() => openProcessDialog(item)}
>
<RefreshCw className={`mr-2 h-4 w-4 ${widgetState.isProcessing ? 'animate-spin' : ''}`} />
Processar
</Button>
)}
{showFlashcards && (
<TooltipProvider>
<Tooltip>
<TooltipTrigger asChild>
<span>
<Button
size="sm"
disabled={flashcardsDisabled || widgetState.flashcardsProcessing}
onClick={() => openFlashcardsDialog(item)}
>
<Zap className={`mr-2 h-4 w-4 ${widgetState.flashcardsProcessing ? 'animate-spin' : ''}`} />
Flashcards
</Button>
</span>
</TooltipTrigger>
{flashcardsDisabled && (
<TooltipContent>
{getFlashcardsDisabledReason(item, versions, widgetState)}
</TooltipContent>
)}
</Tooltip>
</TooltipProvider>
)}
</div>
);
},
},- Step 5: Build + UAT
cd ui && npm run build:reactBrowser: botões aparecem com regras de visibilidade; clicar abre dialogs (vazios por enquanto).
- Step 6: Commit
cd ../..
git add local/helico/ui/src/pages/admin/disciplina/Edit.tsx local/helico/amd/
git commit -m "feat(ui): Edit.tsx botões Processar e Flashcards com regras e tooltips"Task 4.5: Dialog de processamento + execução
Files:
-
Modify:
ui/src/pages/admin/disciplina/Edit.tsx -
Step 1: Importar
ConfirmDialog
import { ConfirmDialog } from '@/components/ConfirmDialog';- Step 2: Adicionar função
confirmProcess
const closeProcessDialog = () => {
setProcessDialog({ open: false, loading: false, file: null });
};
const confirmProcess = async () => {
if (!processDialog.file || processDialog.loading) return;
setProcessDialog((d) => ({ ...d, loading: true }));
setWidgetState((s) => ({ ...s, isProcessing: true }));
try {
const response = await DisciplinaApiService.startProcess(
Number(processDialog.file.id || 0),
);
if (!response?.success) {
setProcessDialog((d) => ({ ...d, loading: false }));
setWidgetState((s) => ({ ...s, isProcessing: false }));
toast.error(String(response?.content ?? 'Erro ao iniciar o processamento'));
return;
}
await reloadData();
} catch {
setProcessDialog((d) => ({ ...d, loading: false }));
setWidgetState((s) => ({ ...s, isProcessing: false }));
toast.error('Falha ao iniciar o processamento.');
}
closeProcessDialog();
};- Step 3: Adicionar função
reloadData
const reloadData = async () => {
try {
const response = await DisciplinaApiService.getEditData(
Number(widgetState.id || props.id || 0),
);
if (!response?.success || !response.content) return;
applyData(response.content as WidgetData);
} catch {
// polling silencioso
}
};- Step 4: Adicionar
<ConfirmDialog>no final do JSX
Antes do </div> de raiz:
<ConfirmDialog
open={processDialog.open}
title="Confirmar processamento"
loading={processDialog.loading}
onCancel={closeProcessDialog}
onConfirm={() => void confirmProcess()}
>
<div className="flex flex-col gap-3">
<p className="mb-0">
Deseja processar o arquivo <strong>{processDialog.file?.name}</strong>?
</p>
{processDialog.loading && (
<div className="flex items-center gap-2 text-muted-foreground">
<RefreshCw className="h-5 w-5 animate-spin" />
<span>Processando. Aguardando atualização...</span>
</div>
)}
</div>
</ConfirmDialog>- Step 5: Commit
git add local/helico/ui/src/pages/admin/disciplina/Edit.tsx
git commit -m "feat(ui): Edit.tsx dialog de processamento + confirmProcess"Task 4.6: Dialog de flashcards + execução
Files:
-
Modify:
ui/src/pages/admin/disciplina/Edit.tsx -
Step 1: Adicionar funções equivalentes
const closeFlashcardsDialog = () => {
setFlashcardsDialog({ open: false, loading: false, file: null });
};
const confirmFlashcards = async () => {
if (!flashcardsDialog.file || flashcardsDialog.loading) return;
setFlashcardsDialog((d) => ({ ...d, loading: true }));
setWidgetState((s) => ({ ...s, flashcardsProcessing: true }));
try {
const response = await DisciplinaApiService.startFlashcardProcess(
Number(widgetState.id || props.id || 0),
);
if (!response?.success) {
setFlashcardsDialog((d) => ({ ...d, loading: false }));
setWidgetState((s) => ({ ...s, flashcardsProcessing: false }));
closeFlashcardsDialog();
toast.error(String(response?.content ?? 'Erro ao gerar flashcards'));
return;
}
await reloadData();
} catch {
setFlashcardsDialog((d) => ({ ...d, loading: false }));
setWidgetState((s) => ({ ...s, flashcardsProcessing: false }));
closeFlashcardsDialog();
toast.error('Falha ao gerar flashcards.');
}
closeFlashcardsDialog();
};- Step 2: Adicionar
<ConfirmDialog>correspondente
<ConfirmDialog
open={flashcardsDialog.open}
title="Confirmar geração de flashcards"
loading={flashcardsDialog.loading}
onCancel={closeFlashcardsDialog}
onConfirm={() => void confirmFlashcards()}
>
<div className="flex flex-col gap-3">
<p className="mb-0">
Deseja gerar flashcards para o arquivo <strong>{flashcardsDialog.file?.name}</strong>?
</p>
{flashcardsDialog.loading && (
<div className="flex items-center gap-2 text-muted-foreground">
<Zap className="h-5 w-5 animate-pulse" />
<span>Gerando flashcards. Aguardando atualização...</span>
</div>
)}
</div>
</ConfirmDialog>- Step 3: Commit
git add local/helico/ui/src/pages/admin/disciplina/Edit.tsx
git commit -m "feat(ui): Edit.tsx dialog de flashcards + confirmFlashcards"Task 4.7: Polling + auto-close dos modais + toast de sucesso
Files:
-
Modify:
ui/src/pages/admin/disciplina/Edit.tsx -
Step 1: Importar o hook
import { useServerPolling } from '@/hooks/useServerPolling';- Step 2: Acompanhar transições de
isProcessing/flashcardsProcessing
Após os useState e antes do return:
// polling enquanto houver processamento em curso
useServerPolling({
active: widgetState.isProcessing || widgetState.flashcardsProcessing,
intervalMs: 4000,
onTick: () => reloadData(),
});
// auto-close + toast quando flags caem
useEffect(() => {
if (!widgetState.isProcessing && processDialog.loading) {
closeProcessDialog();
toast.success('Processamento concluído.');
}
if (!widgetState.flashcardsProcessing && flashcardsDialog.loading) {
closeFlashcardsDialog();
toast.success('Flashcards gerados com sucesso.');
}
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [widgetState.isProcessing, widgetState.flashcardsProcessing]);- Step 3: Build + UAT
cd ui && npm run build:reactBrowser: iniciar processamento → modal mostra spinner → backend sinaliza fim → modal fecha + toast “Processamento concluído.” Equivalente para flashcards.
- Step 4: Commit
cd ../..
git add local/helico/ui/src/pages/admin/disciplina/Edit.tsx local/helico/amd/
git commit -m "feat(ui): Edit.tsx polling + auto-close dos modais + toasts de sucesso"Task 4.8: UAT completo do Edit
- Abre
/disciplinas/{id}/edit— Card renderiza com 3 campos preenchidos - Salvar com nome vazio → mensagem “Campo obrigatório” aparece
- Salvar com nome válido → redireciona para Index
- Cancelar → redireciona para Index
- Tabela de versões renderiza com 7 colunas
- Download Word (FileText) → abre arquivo
- Download Markdown (FileCode) → abre arquivo
- Botão “Processar” aparece só na última versão com
unidadeProcessStatus !== 'completed' - Clicar “Processar” → modal → Confirmar → spinner → backend finaliza → modal fecha + toast
- Polling a cada 4s durante processamento
- Botão “Flashcards” respeita regras de disabled (tooltip mostra razão)
- Clicar “Flashcards” → modal → Confirmar → spinner → finaliza → toast
Phase 5 — Documentação e finalização
Task 5.1: README em ui/README.md
Files:
-
Create:
ui/README.md -
Step 1: Criar o README
# local/helico/ui
Pipeline duplo Vue + React durante a migração progressiva `.vue → .tsx`.
## Estrutura
- `src/` — código React (novo). Entry: `main.tsx`. Build output: `../amd/src/react-app.js`.
- `src-vue/` — código Vue (legado, em migração). Entry: `app.js`. Build output: `../amd/src/app.js`.
- `plugins/vite-plugin-moodle-amd.ts` — plugin Vite que reescreve AMD do Rollup para o formato do Moodle/RequireJS.
## Alias de import
No código React:
- `@/*` → `./src/*` (código deste plugin)
- `@middag/*` → `../../middag/ui/src/*` (design system + componentes do `local_middag`)
## Dedup de libs
React, ReactDOM, Radix, `@tanstack/react-table`, `@inertiajs/react` e outros são declarados como **externals** em `vite.config.ts`. Em runtime vêm dos chunks AMD de `local_middag` (`react-vendor-lazy`, `react-ui-lazy`, `react-table-lazy`).
Uma cópia de cada em memória. Portals/Contexts/hooks funcionam entre código do helico e componentes importados do middag.
## Como adicionar uma nova página React
1. Criar `src/pages/<caminho>/<Name>.tsx` exportando default.
2. Adicionar a rota PHP chamando `$this->use_react_inertia()` antes de `$this->inertia('<caminho>/<Name>', $props)`.
3. Rodar `npm run build:react`.
4. Navegar no Moodle para confirmar.
## Scripts
- `npm run build` — build completo (React + Vue)
- `npm run build:react` — só React
- `npm run build:vue` — só Vue
- `npm run watch:react` / `watch:vue` — modo watch
## Referência canônica
`docs/_archive/specs/2026-04-23-pilot-disciplina-react-migration-design.md`- Step 2: Commit
git add local/helico/ui/README.md
git commit -m "docs(ui): README do pipeline duplo Vue + React"Task 5.2: Nota no .vigim/BACKLOG.md
Files:
-
Modify:
.vigim/BACKLOG.md -
Step 1: Abrir
.vigim/BACKLOG.mde adicionar seção ao final
## Migração Vue → React (iniciada em 2026-04-23)
Piloto entregue: `admin/disciplina/Index` + `admin/disciplina/Edit`.
Spec: `docs/_archive/specs/2026-04-23-pilot-disciplina-react-migration-design.md`
Plano: `docs/_archive/plans/2026-04-23-pilot-disciplina-react-migration.md`
Padrão descoberto:
- Helico importa design system do middag via alias `@middag` (não importa o runtime `ContractPage`).
- AMD dedup via externals → chunks do `local_middag/react-*-lazy`.
- Controller marca rota como React via `inertia_manager::set_amd_module('local_helico/inertia_app_react')`.
- Polling: hook `useServerPolling` local.
- Confirmação: componente local `ConfirmDialog` (wrapper sobre `@middag/components/reui/dialog`).
Telas `.vue` pendentes de migração (29):
- `components/trlha/CreateOrUpdateForm/*` (13 arquivos)
- `components/DocumentUpload/*` (3 arquivos)
- `components/registrationPage/*` (7 arquivos)
- `components/core/Editor.vue`, `ConfirmDialogHost.vue`
- `pages/admin/learning-path/TrilhaForm.vue`
- `pages/admin/unidade/UnidadePreview.vue`, `UnidadeEdit.vue`
Cada tela migrada:
1. Adiciona-se em `MIGRATED_PAGES` (via `$this->use_react_inertia()` no controller correspondente)
2. `.vue` permanece em `src-vue/` até a versão React estar em produção
3. Após validação, remove o `.vue` e atualiza o backlog
Débitos acumulados (revisitar ao final da migração):
- Status/DisplayStatus: trocar HTML bruto por `{label, tone}` + `<StatusBadge>`
- Introduzir vitest se o volume crescer
- Tratamento 401/403 no axios
- Considerar promover `<Toaster />` para o middag se outros plugins também usarem- Step 2: Commit
git add local/helico/.vigim/BACKLOG.md
git commit -m "docs(vigim): registrar padrão da migração Vue→React + backlog das 29 telas"Task 5.3: Smoke test final cross-tela
Verificação final — todas as telas exercitadas em sequência.
- Purge all caches no Moodle Admin
- Abrir
/local/helico/index.php/disciplinas— Index React carrega - Filtrar, paginar, sincronizar, polling — tudo funciona
- Clicar em editar uma disciplina — navega para Edit React via Inertia
- Editar, processar, gerar flashcards — tudo funciona
- Salvar — volta para Index; lista atualizada
- Navegar para
/trilha/{id}— Vue carrega normalmente - Navegar de volta para
/disciplinas— React carrega normalmente - Console limpo nas duas telas — sem “multiple copies of React”
- Bundle
amd/src/react-app.jsenxuto (< 150 KB)
Se algum item falhar, abrir task adicional ao plano e NÃO fechar o piloto.
Task 5.4: Pull request / entrega
- Step 1: Revisar branch local
git log --oneline main..HEADExpected: sequência coerente de commits em português seguindo convenção (feat, chore, docs, fix).
- Step 2: Push e abrir PR
(Seguir o fluxo do repositório. Não executado por esta task — o plano termina aqui.)
Notas de execução
- CLAUDE.md do projeto proíbe operações git mutáveis sem solicitação explícita — os commits listados no plano precisam de autorização do usuário para serem executados.
- Backend permanece inalterado exceto por
admin_controller::index()/edit()que ganham ouse_react_inertia(). Nenhuma modificação emlocal_middag. - Rollback:
git revertdos commits que alteramadmin_controller.php(use_react_inertia()) volta ambas as rotas a carregar o Vue. O código React fica órfão mas inofensivo. - Dependências cruzadas: se
@middag/components/reui/*mudar a API (breaking change), os imports emConfirmDialog.tsx,Index.tsx,Edit.tsxprecisam ser atualizados junto com a nova versão do middag. - CSS namespace: todos os componentes de página têm
className="middag-root"no wrapper externo. Isso garante que os estilos Tailwind do middag apliquem sem poluição externa.