Pular para conteúdo

Guia de Integração, Build e Deploy

Este documento descreve os procedimentos operacionais para compilar a aplicação, publicar os artefatos na CDN (Cloudflare R2) e integrar o recurso dentro do ambiente Moodle.

1. Pipelines de Build e Deploy

O projeto possui dois fluxos de distribuição distintos configurados no package.json.

graph TD
    A[Código Fonte /src] --> B{Qual Destino?}
    B -- " Produção (CDN) " --> C[npm run build]
    C --> D["Gera /dist (Minified JS + Assets)"]
    D --> E[npm run deploy]
    E --> F["Cloudflare R2 (S3)"]
    F --> G["Moodle Consome (Script Tag)"]
    B -- Documentação/Preview --> H[npm run build:pages]
    H --> I[Gera /pages-dist]
    I --> J[npm run pages:deploy]
    J --> K[Cloudflare Pages]
    K --> L["Devs Visualizam (Docs + Demos)"]

1.1 Deploy de Produção (CDN)

Utilizado para atualizar o script que o Moodle carrega e os assets (imagens/JSONs).

  1. Prepare os Assets: Coloque novas imagens e JSONs na pasta assets/.
  2. Versioning: A versão é lida automaticamente do package.json.
  3. Execute: 
    # Limpa, Builda, Minifica e Copia Assets
npm run build

# Envia para o R2 (Bucket configurado no .env)
npm run deploy
    Isso atualizará a pasta /latest/ e criará uma pasta de versão (ex: /v0.2.0/).

1.2 Deploy de Documentação (Pages)

Utilizado para atualizar este site de documentação e as páginas de teste (HTML simulado).

  1. Execute: 
    npm run pages:deploy

2. Configuração de Infraestrutura (Cloudflare R2)

Para que o Moodle consiga baixar os JSONs e Imagens hospedados em outro domínio (a CDN), o CORS (Cross-Origin Resource Sharing) deve estar configurado no bucket R2.

2.1 Regra CORS Necessária

No painel do Cloudflare R2 > Settings > CORS Policy, adicione:

[
  {
    "AllowedOrigins": [
      "https://licosc.unb.br",
      "https://*.unb.br",
      "http://localhost:5173",
      "https://*.middag.dev",
      "https://*.pages.dev"
    ],
    "AllowedMethods": [
      "GET",
      "HEAD"
    ],
    "AllowedHeaders": [
      "*"
    ],
    "ExposeHeaders": [],
    "MaxAgeSeconds": 3000
  }
]

Atenção: Sem isso, o navegador bloqueará o download do JSON com erro de "Network Error" ou "CORS Policy".

3. Integração no Moodle (Administrador)

A integração é feita adicionando uma única linha de código ao Moodle. Isso pode ser feito globalmente (todo o site) ou localmente (por curso/atividade).

Método A: Global (Recomendado)

Para garantir cache eficiente e carregamento em qualquer lugar:

  1. Acesse Administração do Site > Aparência > HTML Adicional.
  2. No campo Dentro do HEAD ou Antes de fechar o BODY, adicione:
<script type="module" src="https://s3-middag-public.middag.com.br/app-unb-ecos/imunizamaisbrasil/latest/app.min.js"></script>

Método B: Local (Por Atividade)

Se você não tem acesso de admin, insira a tag <script> diretamente no editor HTML da atividade mod_page ou mod_label, logo antes da div do cenário.

4. Guia do Conteudista: Criação de Cenários

Fluxo para criar um novo cenário interativo no curso.

Passo 1: Mapeamento de Coordenadas

Como o sistema usa porcentagem (%) e polígonos, recomenda-se usar ferramentas de Web Design ou Image Map Generators.

Dica para Polígonos (Portas/Perspectiva):

  1. Abra a imagem em uma ferramenta como Image Map Generator ou Figma.
  2. Desenhe a forma (Poly) sobre a porta.
  3. Copie as coordenadas em pixels.
  4. No JSON, insira em points. O sistema converterá para % automaticamente, ou você pode converter manualmente: \(x_{\%} = (x_{px} / \text{largura total}) * 100\).

Passo 2: Configuração JSON e Upload (Publicação)

  1. Crie o arquivo JSON em assets/configs/ seguindo a Especificação da API.
  2. Solicite o deploy (npm run deploy).

Passo 3: Inserção na Atividade

  1. No Moodle, crie uma Página ou Rótulo.
  2. No editor HTML, cole o gatilho:
<div
        class="cenario-wrapper"
        data-cenario-map="nome-do-arquivo-json-sem-extensao"
        style="min-height: 600px; position: relative; background: #f5f5f5;"
>
    <div style="display: flex; justify-content: center; align-items: center; height: 100%; color: #666;">
        <p>Carregando cenário interativo...</p>
    </div>
</div>

Substitua nome-do-arquivo-json-sem-extensao pelo ID definido no seu arquivo JSON (ex: cenario-home).

5. Resolução de Problemas (Troubleshooting)

Use a tabela abaixo para identificar e corrigir erros comuns.

Sintoma / Erro Causa Provável Solução Sugerida Nível de Suporte
Tela branca ou "Loading infinito" 1. Erro de CORS na CDN.
2. Arquivo JSON não encontrado (404).
3. JS principal (app.min.js) não carregou.		 1. Verifique o Console (F12) e a aba "Network".
2. Confirme se o nome no data-cenario-map bate com o arquivo na CDN.
3. Teste se o JS carregou (status 200).		 Dev (Crítico) se CORS.
Conteudista p/ 404.
Erro "SyntaxError: JSON" JSON mal formatado: vírgula sobrando, aspas fora do lugar, colchete fechado errado. Valide o JSON em https://jsonlint.com. Conteudista
Hotspot desalinhado na tela width e height no JSON não correspondem ao tamanho original da imagem usada para medir coordenadas. Refaça as medições usando a imagem na resolução real (ex: 1920x1080). Use npm run dev para verificar as bordas de debug. Conteudista
Hotspots desalinhados no Mobile A imagem usada para medir coordenadas não era a original ou o JSON usa dimensões incorretas. Verifique se o JSON usa os valores exatos da imagem original. Mesmo sem versão mobile, mantenha proporções consistentes. Conteudista
Hotspot aparece como “Bloqueado” indevidamente 1. activityId do JSON não bate com ID real do Moodle.
2. Usuário não está logado.
3. API do Moodle falhou ao carregar contexto.		 1. Confirme IDs no Moodle (URL da atividade).
2. Verifique se o Moodle detectou a sessão (M.cfg.sesskey).
3. Teste no console: M.cfg.wwwroot.		 Conteudista, podendo escalar p/ Dev
Hotspot invisível (mas existe no DOM) O hotspot está sendo renderizado fora da imagem (coordenadas inválidas). Ative o modo debug (npm run dev) — marcadores piscam em vermelho. Verifique se x, y, width, height estão dentro da área útil da imagem. Conteudista
Modal da TV não abre 1. Hotspot não possui action: "modal".
2. modalData ausente ou incompleto.
3. Imagem não encontrada na CDN.		 1. Certifique-se de que o hotspot possui action: "modal".
2. Preencha corretamente modalData.image.
3. Verifique CORS e paths na CDN.		 Conteudista
Modal abre atrás do menu do Moodle Conflito de CSS: tema do Moodle usa z-index mais alto que o modal. Ajustar o componente para usar z-index mais alto (ex: 99999) ou encapsular com Shadow DOM. Dev (Crítico)
Erro "Mixed Content" Algum link ou imagem usa http:// e o Moodle roda em https://. Atualize todas as URLs para https://. Conteudista
Link "Home" não funciona O script não conseguiu detectar o ID do curso (tema do Moodle removeu a classe course-id-XYZ do <body>). Ajustar fallback de detecção: tentar capturar o courseid pela URL (?id=XX). Dev (Crítico)
Alteração no JSON não aparece Cache do navegador ou cache da CDN Cloudflare ainda servindo versão antiga. 1. Forçar refresh (Ctrl+F5).
2. Invalidate cache na Cloudflare.
3. Usar versionamento na URL (ex: cenario01.json?v=2).		 Conteudista
Hotspots aparecem mas não carregam ações O JSON foi carregado, mas a inicialização do JS falhou (erro silencioso). Verificar no console erros em app.min.js e validar se a <div data-cenario-map=""> existe. Dev
Cenário carrega mas a imagem não aparece Caminho incorreto na CDN ou CORS bloqueando imagens. Verificar via DevTools > Network se a imagem retorna 200. Caso CORS: ajustar bucket. Dev (Crítico)
Cenário muda mas hotspots permanecem antigos O script reaproveitou estado antes da reinicialização. Forçar reset() no container ou recarregar o módulo (SPA fix). Dev

Próximo passo na leitura: Acompanhe as mudanças do projeto no Changelog.