Portal do Associado — Crohn & Colite Portugal

📋 Visão Geral

Dois anos após a implementação do sistema de gestão de associados em SharePoint Online, a Associação Crohn/Colite Portugal atingiu os limites naturais da plataforma. O crescimento do número de sócios, a necessidade de processar pagamentos online em tempo real e a exigência de uma experiência mobile-first para os associados tornaram evidente a necessidade de evoluir.

A AvantIT desenvolveu uma plataforma web totalmente nova — composta por três componentes interligados — que substitui a Web Part SPFx por aplicações SPA dedicadas, alojadas em servidor próprio da associação, sem dependências de licenças Microsoft ou plataformas de terceiros.

---

🎯 O Desafio

Contexto de Evolução

A solução de 2024 cumpriu com sucesso o seu objetivo inicial: digitalizar e centralizar a gestão de associados, eliminando 300€/mês em licenças externas. No entanto, com o crescimento da associação e a maturidade dos processos internos, emergiram novos requisitos que a arquitetura SharePoint/SPFx não conseguia satisfazer de forma nativa:

• Pagamentos online no momento: Os sócios precisavam de pagar quotas diretamente no portal, sem sair para plataformas externas ou acessos manuais a terceiros.
• Portal self-service para o associado: A Web Part anterior era visível apenas para utilizadores autenticados no tenant Microsoft, limitando o alcance a sócios com conta Microsoft ativa.
• Cartão de Associado Digital: Necessidade de emitir um cartão digital com QR Code para validação presencial e partilha digital.
• Independência de plataforma: Reduzir a dependência do ecossistema Microsoft 365 e ter controlo total sobre a infraestrutura e os dados.
• Backoffice administrativo dedicado: A gestão avançada de quotas (geração em massa, emails de renovação, validação de comprovativos) exigia uma interface administrativa independente.

Requisitos Técnicos

• Pagamentos integrados: Suporte a Multibanco (referências geradas dinamicamente) e MBWay (notificação push) via IfthenPay.
• Autenticação própria: Sistema de login com JWT e refresh tokens, sem dependência de contas Microsoft.
• Cartão digital com QR Code: Gerado dinamicamente com dados do sócio e foto de perfil.
• Gestão anual de quotas: Geração em massa de quotas por ano, envio de emails de renovação e controlo de comprovativos submetidos pelos sócios.
• API REST segura: Backend centralizado que serve ambos os portais com controlo de permissões por camada (associado vs. administrador).

---

💡 A Solução

Abordagem Arquitetural

Optou-se por uma arquitetura de três camadas independentes, cada uma com responsabilidades bem definidas:

┌──────────────────────┐   ┌──────────────────────────┐
│  Portal do Associado │   │  Portal de Administração │
│  (React + Vite SPA)  │   │  (React + Vite SPA)      │
└──────────┬───────────┘   └───────────┬──────────────┘
           │                           │
           └──────────┬────────────────┘
                      ▼
          ┌────────────────────────┐
          │     API REST           │
          │  (Node.js + Express)   │
          │  MySQL · IfthenPay     │
          │  JWT · Nodemailer      │
          └────────────────────────┘

Esta separação permite que cada portal evolua independentemente, com deployments cirúrgicos sem downtime para os utilizadores de outros módulos.

Portal do Associado

Interface self-service para os membros da associação, acessível com credenciais próprias (sem necessidade de conta Microsoft):

• Dashboard personalizado com estado de conta, quotas em atraso e acesso rápido a recursos.
• Cartão de Associado Digital com foto de perfil, número de sócio, QR Code único e validade calculada automaticamente. Partilhável e apresentável em ecrã.
• Área de Quotas com histórico completo, estado de cada pagamento (Pago, Pendente, Atrasado) e ações inline:
  • Pagamento via Multibanco (referência gerada via IfthenPay, válida por prazo configurável)
  • Pagamento via MBWay (pedido de cobrança push para o telemóvel do sócio)
  • Upload de comprovativo de pagamento (PDF ou imagem), com estado de validação visível
• Vantagens de Associado: listagem de benefícios disponíveis para os membros.
• Perfil editável: atualização de dados pessoais, morada, contactos e foto.

Portal de Administração

Backoffice dedicado para a equipa da associação, com autenticação separada e permissões por nível (admin / superadmin):

• Dashboard com KPIs: número de associados ativos, novas adesões do mês, quotas regularizadas, aniversários da semana.
• Gestão de Associados: CRUD completo com filtros avançados (estado, tipo, devedores), envio de email individual e importação CSV.
• Gestão de Quotas por Associado: criação, edição, marcação como pago com um clique e upload de comprovativo pelo admin.
• Comprovativos Pendentes: página dedicada que agrega todos os comprovativos submetidos pelos sócios que aguardam validação — o admin valida (marca quota como paga, recalcula dívida) ou rejeita (permite nova submissão).
• Gestão Anual de Quotas: geração em massa de quotas para um ano inteiro (respeitando valores históricos), com preview dos associados elegíveis e envio em massa de emails de renovação parametrizados por template.
• Email Templates: editor de templates HTML reutilizáveis para renovações, boas-vindas e outros cenários.
• Associados Temporários: gestão do ciclo de candidatura a sócio, com promoção a associado definitivo.
• Importação CSV: migração de dados históricos de associações, quotas e temporários.

API REST

Backend Node.js/Express como camada central de negócio e acesso a dados:

• Autenticação com JWT (access token de curta duração + refresh token HttpOnly cookie).
• IfthenPay SDK integrado para geração de referências MB e pedidos MBWay, com callback de confirmação automática de pagamento.
• Nodemailer para envio de emails transacionais e de marketing com templates HTML dinâmicos.
• Upload de ficheiros (fotos, comprovativos) com compressão automática de imagens via Sharp.
• Recálculo automático de dívida por associado após cada alteração de quota.

Timeline

• Fase 1 — Análise & Arquitetura: 1 semana
• Fase 2 — API REST + Base de Dados: 2 semanas
• Fase 3 — Portal do Associado: 3 semanas
• Fase 4 — Portal de Administração: 3 semanas
• Fase 5 — Integração de Pagamentos IfthenPay: 1 semana
• Fase 6 — Migração de Dados & Deploy: 1 semana
• Total: 11 semanas

---

📈 Os Resultados

Métricas de Sucesso

• 💳 Pagamentos online ativos: Os associados pagam quotas diretamente no portal, sem fricção nem passos manuais da equipa.
• ⚡ Validação de comprovativos automatizada: A equipa administrativa valida comprovativos com um clique, eliminando email de ida e volta.
• 📨 Emails de renovação em massa: Geração e envio de notificações anuais para todos os sócios num único processo, com tracking de envio por quota.
• 🗃️ Migração completa de histórico: Todos os registos de associados e quotas históricas foram migrados da solução anterior sem perda de dados.
• 📱 Cartão digital de associado: Cada sócio tem acesso imediato ao seu cartão digital com QR Code, substituindo o processo manual anterior.
• 🔒 Dados 100% sob controlo da associação: Infraestrutura própria, sem dados em plataformas SaaS de terceiros.

Impacto no Negócio

A evolução para uma plataforma própria libertou a associação de constrangimentos de plataforma e abriu caminho para funcionalidades que simplesmente não existiam antes — nomeadamente a possibilidade de um associado entrar no portal às 23h, verificar a sua quota em atraso, gerar uma referência Multibanco e pagar de imediato, sem qualquer intervenção humana. Este nível de self-service reduz a carga sobre a equipa e melhora significativamente a experiência do associado.

---

🛠️ Stack Tecnológico

• React 18 + TypeScript: Base dos dois portais SPA, com tipagem forte em toda a cadeia.
• Vite: Bundler moderno para builds rápidos e hot-reload em desenvolvimento.
• Fluent UI v9: Sistema de design Microsoft, garantindo consistência visual e acessibilidade.
• TanStack Query: Gestão de estado servidor-side com cache, invalidação automática e loading states.
• Node.js + Express: API REST leve e performativa, com middleware de autenticação JWT.
• MySQL / MariaDB: Base de dados relacional robusta, alojada em servidor da associação.
• IfthenPay: Gateway de pagamentos português, com suporte nativo a Multibanco e MBWay.
• Nodemailer: Envio de emails com suporte a templates HTML parametrizados.
• Sharp: Processamento e compressão de imagens no servidor (fotos de perfil, comprovativos).

---

💬 Testemunho do Cliente

“A nova plataforma mudou completamente a forma como gerimos os nossos associados. Antes, para regularizar uma quota havia sempre um email, uma transferência e depois tinha de se confirmar manualmente. Agora o associado entra no portal, paga com MBWay e está feito. A equipa administrativa tem mais tempo para o que realmente importa: apoiar os nossos sócios.”

Direção — Associação Crohn/Colite Portugal

---

🎓 Lições Aprendidas

• A evolução natural da solução anterior foi uma vantagem: Conhecer profundamente o cliente, o seu modelo de operação e os seus dados (fruto do projeto de 2024) permitiu uma entrega mais rápida e com menos revisões. A migração de dados foi tranquila porque a estrutura de dados estava bem conhecida.
• Pagamentos online mudam comportamentos: A simples disponibilização de referências MB e MBWay no portal aumentou imediatamente o ritmo de regularização de quotas, sem qualquer campanha adicional.
• Self-service bem desenhado reduz suporte: Um portal claro, com estados de pagamento visíveis e ações inline intuitivas, traduziu-se em menos emails e chamadas de sócios à associação.
• Separação de portais foi a decisão certa: Ter um portal dedicado ao associado e outro à administração, em vez de um único com controlo por roles, simplificou o UX de ambos e facilitou o deployment independente de cada componente.