Skip to content

Piloto Vue→React disciplina — Plano de Implementação

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 build

Expected: 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.json e adicionar em dependencies

"@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 install

Expected: 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:vue

Expected: ../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.json atual 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:

  1. 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.

  2. Fallback temporário (B.1): substituir a função external por 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;
    },
  3. Abrir ticket no middag para expor os símbolos faltantes no chunk react-ui-lazy (ex.: adicionar barrel import em register-defaults.ts).

  4. 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:react

Expected:

  • dist/react-app.js gerado

  • ../amd/src/react-app.js copiado pelo plugin

  • ../amd/build/react-app.min.js gerado

  • 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.js

Expected: 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.php e 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/disciplinas

Expected:

  • 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-app carregam 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ão react-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.ts para ui/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:react

Expected: 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 /disciplinas no browser
cd ui && npm run build:react

Expected: 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.tsx e 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 rowActions inline

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.tsx para 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:react

Expected: 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:react

No 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 RefreshCw de lucide e SyncApiService

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:react

Browser: 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 Input e Search

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 useEffect para também recarregar quando fullnameFilter mudar (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:react

Browser: 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:react

Browser: 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:react

Browser: 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:react

Browser: 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 actions nas 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:react

Browser: 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:react

Browser: 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.md e 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.js enxuto (< 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..HEAD

Expected: 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 o use_react_inertia(). Nenhuma modificação em local_middag.
  • Rollback: git revert dos commits que alteram admin_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 em ConfirmDialog.tsx, Index.tsx, Edit.tsx precisam 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.
Navigation

Type to search…

↑↓ navigate↵ selectEsc close