Artes da Fafa

Aplicacao web para catalogo e contato da Artes da Fafa. O repositorio implementa um backend em Flask responsavel pela entrega da shell HTML, exposicao das rotas HTTP e integracao opcional com SMTP, enquanto a experiencia principal do cliente e entregue por uma SPA em Vue 3 compilada com Vite.

Visao geral

• Backend HTTP em Flask com rotas HTML e JSON.
• Frontend SPA em Vue 3 com Vue Router.
• Fallback server-rendered em templates/app.html quando o bundle do frontend nao esta disponivel.
• Catalogo de produtos mantido no backend como fonte primaria dos dados.
• Fluxo de contato com validacao de entrada e tentativa opcional de envio de e-mail de confirmacao.

Arquitetura

Backend

O backend esta centralizado em app.py. As responsabilidades principais sao:

• configurar a aplicacao Flask;
• manter a lista PRODUCTS, usada como source of truth do catalogo;
• serializar produtos para o contrato da API;
• validar e processar requisicoes de contato;
• detectar se a interface deve ser entregue pelo Vite em desenvolvimento, pelo build estatico do frontend ou pelo fallback em template.

Frontend

O frontend fica em frontend/ e usa:

• Vue 3 para composicao da interface;
• Vue Router para as rotas / e /galeria;
• Vite para servidor de desenvolvimento e build de producao.

Pontos principais:

• frontend/src/main.js inicializa a aplicacao e registra o router.
• frontend/src/router/index.js define as rotas da SPA.
• frontend/src/components/ImageGallery.vue consome a API de produtos, aplica filtro por categoria e busca textual, e controla o modal de imagens.
• frontend/src/components/ContactForm.vue envia o formulario para a API de contato sem recarregar a pagina.
• frontend/src/services/api.js encapsula as chamadas HTTP do cliente.

Estrategia de renderizacao

O template templates/app.html funciona como shell de entrega. Em runtime, a rota principal segue esta ordem:

1. Se VITE_DEV_SERVER estiver definido, carrega os modulos do servidor Vite.
2. Se existir build em static/frontend/assets/, carrega os assets compilados.
3. Caso contrario, usa o markup HTML com JavaScript embutido como fallback funcional.

Essa estrategia permite desenvolver a SPA de forma desacoplada sem perder a capacidade de servir uma versao funcional diretamente pelo Flask.

Requisitos

• Python 3.11+
• Node.js 18+ recomendado
• npm

Setup

Backend

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

Frontend

cd frontend
npm install
cd ..

Execucao

Desenvolvimento com Vite + Flask

Terminal 1:

cd frontend
npm run dev

Terminal 2:

$env:VITE_DEV_SERVER="http://127.0.0.1:5173"
python app.py

Execucao apenas com Flask

Esse modo usa o fallback em template quando nenhum bundle do frontend estiver disponivel:

python app.py

Build do frontend para servir pelo Flask

cd frontend
npm run build
cd ..
python app.py

Aplicacao local:

http://127.0.0.1:5000

Configuracao por ambiente

Variaveis reconhecidas pela aplicacao:

• SECRET_KEY: chave de sessao do Flask.
• LOG_LEVEL: nivel de log usado em logging.basicConfig.
• VITE_DEV_SERVER: origem do servidor Vite em desenvolvimento.
• SMTP_HOST: host SMTP.
• SMTP_PORT: porta SMTP.
• SMTP_USERNAME: usuario SMTP.
• SMTP_PASSWORD: senha SMTP.
• SMTP_FROM: remetente usado na confirmacao por e-mail.

Quando a configuracao SMTP esta incompleta, a API de contato continua respondendo com sucesso, mas retorna emailConfirmationSent: false e inclui uma mensagem informativa no payload.

Contrato HTTP

GET /

Entrega a shell principal da aplicacao. Dependendo do ambiente, pode carregar:

• a SPA via Vite;
• a SPA compilada;
• o fallback HTML server-rendered.

GET /galeria

Entrega a mesma shell da aplicacao para a rota de galeria. No modo SPA, o roteamento final e resolvido no cliente por Vue Router.

GET /api/products

Retorna a lista completa de produtos serializados.

Query params suportados:

• product: filtra por nome exato da categoria, com comparacao case-insensitive.

Exemplo:

GET /api/products?product=Amigurumi

Resposta:

{
  "items": [
    {
      "id": "amigurumi",
      "name": "Amigurumi",
      "description": "Personagens fofos e personalizados para colecao, decoracao ou presente.",
      "category": "Amigurumi",
      "images": [
        {
          "src": "/static/images/amigurumi-1.jpg",
          "alt": "Amigurumi - foto 1"
        }
      ]
    }
  ],
  "categories": ["Croche fino", "Barbantes", "Bordados variados", "Amigurumi"],
  "selectedCategory": "Amigurumi"
}

POST /api/contact

Aceita application/json e tambem dados de formulario tradicionais. Campos esperados:

• name
• email
• message

Regras de validacao:

• name e obrigatorio;
• email deve obedecer ao regex definido em is_valid_email.

Resposta de sucesso:

{
  "message": "Obrigada! Seu pedido foi recebido e entraremos em contato em breve.",
  "emailConfirmationSent": false,
  "info": "Nao foi possivel enviar a confirmacao por e-mail neste momento."
}

Codigos retornados:

• 201 para envio aceito;
• 400 para erro de validacao.

Estrutura do repositorio

app.py
requirements.txt
README.md
frontend/
  package.json
  vite.config.js
  src/
    App.vue
    main.js
    router/
    services/
    views/
    components/
    assets/styles/
templates/
  app.html
  index.html
static/
  styles.css
  images/
tests/
  test_app.py

Desenvolvimento

Locais mais relevantes para manutencao:

• app.py: rotas, serializacao, validacoes e SMTP.
• frontend/src/views/: composicao das paginas.
• frontend/src/components/: galeria, modal, feedback visual e formulario.
• frontend/src/services/api.js: camada de acesso HTTP no cliente.
• templates/app.html: shell de integracao entre Flask e frontend.
• static/images/: acervo de imagens.

Testes

A suite atual cobre disponibilidade da home, filtro da API, validacao de e-mail e comportamento sem SMTP.

Execucao:

python -m unittest discover -s tests -v

Resultado validado em 2026-08-06:

Ran 6 tests in 0.050s
OK

Limitacoes atuais

• O catalogo de produtos ainda esta hardcoded no backend.
• requirements.txt lista apenas Flask; dependencias de desenvolvimento e frontend sao gerenciadas separadamente.
• O fallback HTML embutido em templates/app.html duplica parte do comportamento da SPA, o que aumenta o custo de manutencao caso as duas experiencias evoluam em paralelo.