Arquitetura e Visão Geral¶

O Módulo de Cenários Interativos é uma solução de frontend projetada para enriquecer a experiência de aprendizagem no Moodle (LMS). Ele permite a criação de interfaces visuais exploratórias — onde o aluno aprende clicando e interagindo com ambientes gráficos — sem a rigidez das atividades padrão do Moodle e sem a complexidade de manutenção de plugins PHP instalados no servidor.

Esta seção detalha a arquitetura técnica da solução EAD ECOS - ImunizaMais Brasil. O projeto adota uma abordagem de Widget Desacoplado (também conhecido como Micro-frontend Estático), onde a lógica de apresentação interativa é separada do núcleo do LMS, comunicando-se através de contratos de dados e APIs nativas.

Embora o Moodle não seja nativamente headless, tratamos o LMS apenas como o "palco" e gerenciador de autenticação. O Módulo de Cenários Interativos atua como um componente autônomo que é injetado na página, consumindo recursos de forma distribuída.

Principais Benefícios:¶

Imutabilidade do Core: Não instalamos plugins PHP no servidor do Moodle. Isso elimina riscos de segurança e quebras em atualizações do LMS.
Performance: O carregamento de ativos pesados (imagens de alta resolução, scripts) é transferido para a CDN (Cloudflare R2), aliviando a carga do servidor institucional.
Independência de Conteúdo: A definição visual (hotspots, textos, links, imagens) fica em arquivos JSON estáticos, permitindo versionamento via Git.

2. Diagrama de Fluxo de Dados¶

O fluxo abaixo ilustra como o componente opera em um modelo híbrido: ele busca a aparência na CDN e as permissões no Moodle simultaneamente.

sequenceDiagram
    participant Aluno as Navegador do Aluno
    participant Moodle as Moodle (LMS)
    participant CDN as Cloudflare R2
    Note over Aluno, Moodle: Fase 1: Carregamento do Container
    Aluno ->> Moodle: Acessa Atividade (mod_page)
    Moodle -->> Aluno: Retorna HTML + Script Loader + 
    Note over Aluno, CDN: Fase 2: Hidratação e Permissões
    Aluno ->> Aluno: Script detecta `data-cenario-map`

    par Busca Paralela
        Aluno ->> CDN: GET /assets/config.json (Visual)
        Aluno ->> Moodle: POST /lib/ajax/service.php (Permissões)
    end

    CDN -->> Aluno: Retorna Coordenadas e Textos
    Moodle -->> Aluno: Retorna Status (Disponível/Bloqueado)
    Note over Aluno: Fase 3: Renderização
    Aluno ->> Aluno: Merge de Dados (Visual + Permissão)
    Aluno ->> Aluno: Renderiza DOM Interativo

3. Componentes da Arquitetura¶

O sistema é dividido em três camadas lógicas distintas, organizadas conforme a tabela abaixo:

Camada	Localização	Responsabilidade e Características
Apresentação (UI Engine)	`src/ui/`	Motor de Renderização: Responsável por detectar gatilhos no DOM, calcular geometria relativa e gerenciar eventos de interação. É agnóstico de dados.
Dados Híbridos (Stateless)	JSON + API	Fonte da Verdade: Combina o Layout (vindo do JSON estático na CDN) com o Estado (vindo da API do Moodle). O Frontend não persiste dados, apenas consulta.
Infraestrutura (DevOps)	`scripts/`	Build & Deploy: Pipeline automatizado via Node.js/Vite que compila o TypeScript, minifica os ativos e os publica no Object Storage (R2).

4. Responsividade e Geometria Avançada¶

Um dos desafios centrais de Image Maps modernos é manter a precisão dos cliques em diferentes tamanhos de tela e suportar objetos em perspectiva (não apenas retângulos planos).

4.1 Coordenadas Relativas (Base)¶

Utilizamos um cálculo percentual para posicionamento. Se um hotspot está em x=500 numa imagem de width=1000, o sistema calcula:

\[ Left = \frac{500}{1000} \times 100 = 50\% \]

4.2 Geometria Poligonal (Perspectiva)¶

Para objetos como portas laterais ou corredores, utilizamos a propriedade CSS clip-path baseada em polígonos. Isso permite definir áreas de clique irregulares (trapézios, losangos) que se adaptam à distorção da perspectiva da imagem de fundo.

4.3 Sistema de Camadas (Modais)¶

O componente gerencia um contexto de empilhamento (stacking context) para permitir interações complexas sem sair da página:

Camada 1 (Base): Cenário principal e hotspots de navegação.
Camada 2 (Overlay): Backdrop escuro para foco.
Camada 3 (Expandida): Elementos como a "Televisão Expandida" que abrem sobre o cenário atual.

4.4 Fallback Mobile¶

Para telas muito pequenas (\< 480px), o CSS injetado garante que as áreas de clique tenham tamanho mínimo de toque (44x44px), prevenindo o problema de "Fat Finger".

O projeto foi desenvolvido com foco estrito nas diretrizes WCAG 2.1 AA. A tabela abaixo resume as estratégias técnicas adotadas para garantir a inclusão de usuários de tecnologias assistivas.

Pilar de Acessibilidade	Implementação Técnica
Semântica e Estrutura	Substituição de mapas de imagem antigos (`<map>`) por árvore DOM semântica com tags nativas (`<button>`, `<a>`). Estados de bloqueio usam `aria-disabled="true"` em vez de apenas cores.
Navegação por Teclado	Ordem de tabulação lógica definida pela sequência do JSON. Implementação de `:focus-visible` com alto contraste para indicar a posição do cursor.
Leitores de Tela	Injeção obrigatória de `aria-label` nos hotspots (ex: "Acessar Questionário (Bloqueado)"). Tratamento da imagem de fundo como decorativa (`aria-hidden="true"`).
Redução de Movimento	Detecção automática da preferência do sistema operacional (`prefers-reduced-motion`) para desativar animações de hover e pulse via CSS.

Próximo passo na leitura: Entenda o contrato de dados na Especificação da API.