Configuração Inicial e Ambiente¶

Bem-vindo à documentação técnica do projeto EAD ECOS - ImunizaMais Brasil. Esta página cobre os pré-requisitos, a instalação do ambiente de desenvolvimento e a configuração das variáveis de ambiente necessárias para build e deploy, além dos comandos disponíveis no package.json.

1. Pré-requisitos¶

Para desenvolver, compilar ou testar este projeto, certifique-se de ter:

Node.js: Versão 18 (LTS) ou superior.
Gerenciador de Pacotes: NPM (v9+) ou Yarn.
Acesso à Internet: Para baixar dependências e conectar aos serviços AWS S3/Cloudflare R2.
Editor de Texto: Recomendamos VS Code com as extensões ESLint e Prettier.

2. Instalação¶

Clone o repositório e instale as dependências:

# 1. Clonar
git clone https://bitbucket.org/middagtec/app-unb-ecos-imunizamaisbrasil
cd nome-do-projeto

# 2. Instalar dependências
npm install

3. Variáveis de Ambiente¶

O projeto depende de um arquivo .env na raiz para configurar URLs, credenciais de deploy e metadados do projeto. Duplique o arquivo .env.example para .env e preencha conforme a tabela abaixo:

cp .env.example .env

3.1 Configurações da Aplicação (App)¶

Estas variáveis definem constantes usadas durante o processo de build (Vite) e URLs base para publicação.

Variável	Descrição	Exemplo
`CDN_URL`	URL pública final onde os assets serão hospedados.	`https://s3-middag-public...`
`DIST_FILENAME`	Nome base do arquivo JavaScript gerado.	`app`
`PROJECT_NAME`	Nome legível do projeto para logs e cabeçalhos.	`"EAD ECOS - ImunizaMais Brasil"`

3.2 Configurações de Deploy (S3 / Cloudflare R2)¶

Variáveis utilizadas pelo script de deploy (scripts/deploy-r2.mjs) para enviar os artefatos para o Object Storage.

Variável	Descrição
`AWS_ACCESS_KEY_ID`	Chave de acesso da API S3/R2.
`AWS_SECRET_ACCESS_KEY`	Chave secreta da API S3/R2.
`AWS_DEFAULT_REGION`	Região do bucket (geralmente `auto` ou `us-east-1` para R2).
`AWS_ENDPOINT_URL`	Endpoint S3 API do Cloudflare (ex: `https://<accountid>.r2.cloudflarestorage.com`).
`R2_BUCKET`	Nome do Bucket de destino.
`R2_PREFIX`	Crítico: Caminho/pasta dentro do bucket onde os arquivos serão salvos (ex: `app-unb-ecos/imunizamaisbrasil`).

3.3 Configurações Cloudflare Pages¶

Utilizadas caso o projeto utilize o Cloudflare Pages para hospedar a documentação ou páginas de preview.

Variável	Descrição
`CLOUDFLARE_ACCOUNT_ID`	ID da conta Cloudflare.
`CLOUDFLARE_PROJECT_NAME`	Nome do projeto no painel Cloudflare Pages.
`CLOUDFLARE_API_TOKEN`	Token com permissão de escrita no Pages.

Certifique-se de preencher as variáveis conforme detalhado no arquivo de exemplo, especialmente as credenciais AWS_* (para deploy no R2) e CLOUDFLARE_* (para deploy no Pages).

4. Estrutura do Projeto¶

O projeto segue uma arquitetura modular como um framework, separando a lógica de negócio (Core) da camada de apresentação (UI). A estrutura do projeto destaca a separação entre código fonte (src), scripts de automação (scripts) e configuração.

.
├── assets/                 # Imagens estáticas (cenários, ícones) para upload na CDN
├── dist/                   # Saída do build de produção (CDN) - Artefatos gerados pelo build (não versionados)
├── pages-dist/             # Saída do build para Cloudflare Pages
├── docs/                   # Documentação técnica (MkDocs)
├── scripts/                # Automação Node.js
│   ├── copy-assets.mjs     # Sincroniza assets para a pasta de distribuição
│   ├── deploy-r2.mjs       # Upload para S3/R2 usando aws-sdk
│   ├── minify.mjs          # Minificação pós-build (esbuild)
│   └── prepare-pages.mjs   # Ajustes para o ambiente Pages
│
├── src/
│   ├── core/               # Lógica de negócio pura
│   │   ├── api.ts          # Fetch e tratamento de dados externos
│   │   ├── state.ts        # Gerenciamento de estado (se necessário)
│   │   └── validator.ts    # Validação de schema JSON
│   │
│   ├── ui/                 # Manipulação do DOM e renderização
│   │   ├── cenario.ts      # Classe principal do Image Map
│   │   └── templates.ts    # Literais de template HTML
│   │
│   ├── utils/              # Funções utilitárias
│   └── index.ts            # Ponto de entrada (Entrypoint)
│
├── .env                    # Variáveis de ambiente (Segredos - Ignorado no Git)
├── package.json            # Definição de scripts e dependências
├── tsconfig.json           # Configuração TypeScript
├── vite.config.ts          # Configuração do Bundler
└── wrangler.jsonc          # Configuração do Cloudflare

5. Scripts e Comandos¶

O projeto utiliza npm para orquestrar o Vite, scripts de manutenção e deploys via Wrangler/AWS SDK. Abaixo, a explicação detalhada de cada comando definido no package.json.

5.1 Desenvolvimento Local¶

Comando	Descrição
`npm run dev`	Inicia o servidor local do Vite. Útil para testar alterações em tempo real com Hot Module Replacement (HMR).
`npm run lint`	Executa o ESLint para encontrar problemas no código (JavaScript/TypeScript).
`npm run lint:fix`	Tenta corrigir automaticamente problemas de linting.
`npm run format`	Formata todo o código do projeto usando Prettier.

5.2 Build e Deploy de Produção (CDN / R2)¶

Este fluxo gera o bundle otimizado (app.min.js) e o envia para o Cloudflare R2 para ser consumido pelo Moodle.

Comando	Descrição
`npm run clean`	Remove a pasta `dist/` para garantir um build limpo.
`npm run build`	Pipeline de Produção: 1. `vite build`: Transpila TS para JS. 2. `minify.mjs`: Remove comentários e comprime o código. 3. `copy-assets.mjs`: Copia imagens de `assets/` para `dist/`.
`npm run preview`	Serve a pasta `dist/` localmente para validar o build antes do upload.
`npm run deploy`	Executa `scripts/deploy-r2.mjs`. Envia o conteúdo de `dist/` para o bucket R2 configurado no `.env`.

5.3 Build e Deploy de Documentação (Cloudflare Pages)¶

Este fluxo é usado para gerar a documentação estática ou páginas de preview do projeto.

Comando	Descrição
`npm run build:pages`	Pipeline de Pages: Define `OUT_DIR=pages-dist`. Executa o build, minificação e cópia de assets direcionados para a pasta de páginas. Roda `prepare-pages.mjs` para ajustes finais de roteamento/HTML.
`npm run pages:preview`	Gera o build de pages e faz deploy para uma URL de preview (branch preview) no Cloudflare Pages.
`npm run pages:deploy`	Gera o build de pages e faz deploy para a produção do Cloudflare Pages.

Próximo passo na leitura: Entenda a Visão Geral da arquitetura e o fluxo de dados.