AUREA
Plataforma premium de experiências sonoras (relaxamento, meditação, concentração, sono e frequências de referência), com assinaturas pagas em kwanzas por Multicaixa Express e painel exclusivo do proprietário.
A AUREA é um serviço de bem-estar. Não faz alegações clínicas e não substitui aconselhamento médico.
Arquitetura
| Camada | Tecnologia | Onde |
|---|
| Web | Next.js 15 (App Router), React 19, TypeScript, Tailwind CSS 4 | src/app |
| Dados e autenticação | Supabase (PostgreSQL + RLS, Auth com MFA TOTP) | supabase/migrations |
| Reprodução | YouTube IFrame Player API (leitor oficial, com os controlos do YouTube) | src/components/player |
| Pagamentos | Multicaixa Express: modo provisório de verificação manual + interface para parceiro | src/lib/payments, funções SQL |
| E-mail | Resend (opcional) para e-mails da app; Supabase SMTP para e-mails de autenticação | src/lib/email.ts |
| Hosting | Vercel (+ Vercel Cron para expirações) | vercel.json |
Módulos:
src/app/(site) interface pública, autenticação, checkout, legal, suporte
src/app/app área do utilizador (biblioteca, conteúdo, favoritos, histórico, assinatura, pagamentos, conta)
src/app/admin painel super admin (dashboard, utilizadores, conteúdos, assinaturas, pagamentos, planos, configurações, auditoria)
src/app/api exportação de dados, CSV financeiro, cron de expiração, webhook do parceiro
src/components/player motor de reprodução (provider + mini-player persistente + player expandido)
src/lib serviços: auth, catálogo, assinaturas, pagamentos, validação, rate limiting, auditoria, e-mail
supabase/migrations esquema, máquinas de estado, RLS e funções privilegiadas
tests/db testes das regras de negócio e segurança contra o SQL real (PGlite)
tests/unit testes de validação, YouTube, preços, webhooks
Princípios de segurança
- Tudo o que dá acesso é decidido na base de dados. O vídeo de um conteúdo premium (
content_media) só é devolvido pela RLS a quem tem assinatura ativa (has_premium_access). Nenhum cookie, campo de formulário ou pedido manual o desbloqueia.
- O cliente nunca escreve campos privilegiados. Papéis, estado/expiração de assinaturas e pagamentos não têm permissões de escrita para
anon/authenticated; só funções SECURITY DEFINER executáveis pelo service_role os alteram.
- Pagamentos atómicos e idempotentes (
confirm_payment): valor e plano vêm da BD, referência única, bloqueio de linha, recusa de valor errado, transação reutilizada, notificação duplicada e confirmações repetidas. Todas as tentativas ficam em payment_events.
- Histórico financeiro e auditoria são append-only (triggers impedem
DELETE/UPDATE). Correções fazem-se por reversão auditada.
- Máquinas de estado na BD para assinaturas e pagamentos (transições impossíveis são rejeitadas).
- Admin: papel
super_admin numa tabela própria, verificado no servidor em cada página e ação, MFA TOTP obrigatório (ADMIN_REQUIRE_MFA), utilizadores comuns recebem 404 em /admin.
- Rate limiting persistente em login, registo, recuperação, pedidos de pagamento, suporte e exportações.
- Cabeçalhos de segurança (HSTS,
X-Frame-Options, nosniff, Referrer-Policy, Permissions-Policy), proteção contra open redirect, CSV com neutralização de fórmulas, Server Actions com proteção CSRF nativa do Next.js.
Desenvolvimento local
Requisitos: Node 20+, um projeto Supabase (ou supabase start com a CLI e Docker).
npm install
cp .env.example .env.local # preencher as variáveis
# aplicar migrações e seed (CLI Supabase):
supabase link --project-ref <ref>
supabase db push
psql "$DATABASE_URL" -f supabase/seed.sql # ou cole o ficheiro no SQL Editor
npm run dev
Testes e verificações:
npm test # 83 testes: regras de pagamento, RLS, privilégios, YouTube, preços, webhooks
npm run typecheck
npm run build
Os testes de base de dados executam as migrações reais num PostgreSQL em memória (PGlite) com uma réplica mínima dos papéis do Supabase — não precisam de rede nem de credenciais.
Configuração do Supabase
- Auth → Providers → Email: ativo, com "Confirm email" ligado.
- Auth → URL Configuration: Site URL =
NEXT_PUBLIC_SITE_URL; Redirect URLs: https://<domínio>/auth/confirm.
- Auth → Email Templates (fluxo SSR):
- Confirm signup:
{{ .SiteURL }}/auth/confirm?token_hash={{ .TokenHash }}&type=email&next=/app
- Reset password:
{{ .SiteURL }}/auth/confirm?token_hash={{ .TokenHash }}&type=recovery
- Traduza os textos para português.
- Auth → SMTP: configure um SMTP próprio (por exemplo o do Resend) para não ficar limitado ao envio de teste do Supabase.
- Auth → Multi-Factor: TOTP ativo.
- Auth → Rate limits / Attack protection: mantenha os limites ativos e, se possível, CAPTCHA.
- Backups: ative backups diários (e PITR no plano Pro). Ver
docs/OPERACOES.md.
Primeiro super admin
- Registe a conta do proprietário em
/registar e confirme o e-mail.
- Localmente, com as variáveis do servidor:
[email protected] NEXT_PUBLIC_SUPABASE_URL=... SUPABASE_SERVICE_ROLE_KEY=... npm run admin:bootstrap
- Entre em
/admin: é pedida a ativação do autenticador (TOTP).
Não existe nenhum caminho na interface para atribuir super_admin.
Deploy na Vercel
Ver docs/DEPLOY.md.
Pagamentos Multicaixa Express
Ver docs/PAGAMENTOS.md. Resumo: a app arranca em modo provisório (pedido pendente → cliente paga por Multicaixa Express → admin confirma com evidência verificável). A integração automática com um parceiro só deve ser ligada depois de implementar o adaptador com a especificação oficial e testar o fluxo real.
E-mails e notificações
Ver docs/NOTIFICACOES.md. E-mails automáticos via Google Workspace (Gmail API, OAuth 2.0), fila persistente com novas tentativas, avisos de expiração a 10, 5, 3 e 1 dia (cron diário, Africa/Luanda), sino de notificações na conta e painel /admin/notificacoes (estado, configurações, modelos, histórico). Nada é enviado nem simulado até as credenciais estarem configuradas e um envio de teste ser validado.
Variáveis de ambiente
| Variável | Onde | Obrigatória | Descrição |
|---|
NEXT_PUBLIC_SITE_URL | cliente+servidor | sim | URL pública, sem barra final |
NEXT_PUBLIC_SUPABASE_URL | cliente+servidor | sim | URL do projeto Supabase |
NEXT_PUBLIC_SUPABASE_ANON_KEY | cliente+servidor | sim | chave pública (anon) |
SUPABASE_SERVICE_ROLE_KEY | só servidor | sim | chave service role |
ADMIN_REQUIRE_MFA | servidor | recomendado | true (por omissão) exige TOTP no /admin |
CRON_SECRET | servidor | sim | protege /api/cron/expire (Vercel envia-o automaticamente) |
EMAIL_PROVIDER, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REFRESH_TOKEN | servidor | não | e-mails automáticos via Google Workspace (Gmail API). Ver docs/NOTIFICACOES.md |
PAYMENT_MODE | servidor | sim | manual_review até existir parceiro integrado |
PAYMENT_WEBHOOK_SECRET | servidor | só com parceiro | segredo de verificação dos callbacks |
SUPER_ADMIN_EMAIL | local | só no bootstrap | e-mail do primeiro admin |
Limitações conhecidas (honestas)
- YouTube: o leitor oficial exige o vídeo visível durante a reprodução, por isso não há reprodução em segundo plano nem com o ecrã bloqueado; ao recolher o mini-player para a barra compacta, a reprodução pausa. Anúncios e marcas do YouTube podem aparecer. A visualização de ondas é decorativa (o YouTube não expõe o sinal de áudio).
- Pagamentos: sem parceiro integrado, a confirmação é manual. Nenhuma ativação acontece por o cliente indicar que pagou.
- Textos legais: são modelos base para revisão jurídica (Lei n.º 22/11 de Proteção de Dados Pessoais e restante legislação angolana).
