230406/petlink_final
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
230406
2026-05-04 09:43:36 +01:00
commit dfae1b5335
37 changed files with 10343 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

117
docs/06-stack-tecnologica.md Normal file
View File

@@ -0,0 +1,117 @@
# 6. Stack Tecnológica
## 6.1 Frontend
| Tecnologia | Versão | Função | Justificação |
|---|---|---|---|
| **Next.js** | 14+ | Framework React principal | SSR/SSG integrado, App Router, optimizações automáticas de imagem e font, middleware nativo |
| **TypeScript** | 5+ | Linguagem de programação | Tipagem estática reduz bugs, melhora DX e facilita manutenção a longo prazo |
| **Tailwind CSS** | 3+ | Framework de estilos | Produtividade elevada, classes utilitárias, sistema de design consistente e responsivo por defeito |
| **shadcn/ui** | latest | Componentes base | Acessíveis por defeito (ARIA), totalmente personalizáveis, sem overhead de bundle desnecessário |
| **TanStack Query** | 5+ | Gestão de dados do servidor | Cache automático, invalidação, loading/error states, optimistic updates sem boilerplate |
| **Zustand** | 4+ | Estado global cliente | Minimalista, sem boilerplate, ideal para preferências UI e dados de sessão no cliente |
| **React Hook Form** | 7+ | Gestão de formulários | Performance superior (sem re-renders a cada tecla), integração nativa com Zod |
| **Zod** | 3+ | Validação de esquemas | Type-safe, partilhado entre frontend e backend, mensagens de erro em português |
| **react-email** | latest | Templates de email | Componentes React para emails transaccionais com preview em browser |
| **next/image** | built-in | Optimização de imagens | WebP automático, lazy loading, placeholder blur, responsive sizes |
---
## 6.2 Backend
| Tecnologia | Versão | Função | Justificação |
|---|---|---|---|
| **Next.js API Routes** | 14+ | Endpoints da API | Co-localizados com o frontend, serverless por defeito, sem configuração de servidor separado |
| **Prisma ORM** | 5+ | Acesso à base de dados | Type-safe, migrações declarativas, excelente DX, Prisma Studio para explorar dados |
| **NextAuth.js** | 4+ | Autenticação | Suporte a múltiplos providers, sessões seguras (JWT/database), middleware de protecção de rotas |
| **bcryptjs** | 2+ | Hash de palavras-passe | Standard seguro para hashing de credenciais, factor de custo configurável |
| **Resend** | 2+ | Envio de emails | API moderna com alta taxa de entrega, integração directa com react-email, webhook de eventos |
| **Stripe SDK** | 14+ | Pagamentos | PCI DSS Level 1, suporte MBWay/SEPA/MB, webhooks robustos, excelente documentação |
---
## 6.3 Infra-estrutura e Serviços
| Serviço | Plano Inicial | Função | Custo Estimado |
|---|---|---|---|
| **Supabase** | Free → Pro | PostgreSQL + Storage + Auth | Gratuito até 500MB DB; $25/mês no Pro |
| **Vercel** | Hobby → Pro | Hosting + CDN + CI/CD automático | Gratuito na fase inicial; $20/mês no Pro |
| **Upstash Redis** | Free | Cache e rate limiting | Gratuito até 10.000 comandos/dia |
| **Resend** | Free | Email transaccional | Gratuito até 3.000 emails/mês |
| **Stripe** | Pay-as-you-go | Pagamentos online | 1,4% + 0,25€ por transacção (cartões UE) |
| **Cloudflare** | Free | CDN e protecção DDoS | Gratuito para sites |
| **Sentry** | Free | Monitorização de erros | Gratuito até 5.000 eventos/mês |
| **Anthropic Claude API** | Pay-as-you-go | IA — match e chatbot | ~$3/1M tokens input (Sonnet 4) |
**Custo total estimado na fase MVP: ~0–25€/mês**
---
## 6.4 Ferramentas de Desenvolvimento
| Ferramenta | Função |
|---|---|
| **pnpm** | Gestor de pacotes (mais rápido e eficiente que npm) |
| **ESLint + Prettier** | Linting e formatação automática de código |
| **Husky + lint-staged** | Git hooks para validar código antes de cada commit |
| **Vitest** | Framework de testes unitários e de integração |
| **Playwright** | Testes end-to-end e de acessibilidade |
| **Prisma Studio** | Interface visual para explorar e editar a base de dados |
| **@next/bundle-analyzer** | Análise do tamanho do bundle JavaScript |
| **Storybook** | Documentação e desenvolvimento isolado de componentes UI |
---
## 6.5 Variáveis de Ambiente
```bash
# .env.local (nunca commitar — usar .env.example como template)
# Base de Dados
DATABASE_URL="postgresql://user:password@host:5432/pawlink"
# Autenticação
NEXTAUTH_SECRET="gerar com: openssl rand -hex 32"
NEXTAUTH_URL="http://localhost:3000"
# Stripe
STRIPE_SECRET_KEY="sk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."
# Email
RESEND_API_KEY="re_..."
RESEND_FROM_EMAIL="noreply@pawlink.pt"
# Supabase Storage
NEXT_PUBLIC_SUPABASE_URL="https://xxx.supabase.co"
NEXT_PUBLIC_SUPABASE_ANON_KEY="..."
SUPABASE_SERVICE_ROLE_KEY="..."
# Anthropic (IA)
ANTHROPIC_API_KEY="sk-ant-..."
# Redis (Rate Limiting)
UPSTASH_REDIS_REST_URL="https://..."
UPSTASH_REDIS_REST_TOKEN="..."
```
---
## 6.6 Justificação das Escolhas Tecnológicas
### Porque Next.js em vez de Remix ou Astro?
Next.js tem o ecossistema mais maduro para aplicações React complexas com SSR. O App Router (Next.js 14) oferece Server Components que permitem buscar dados directamente no servidor sem APIs intermediárias para o conteúdo estático. A integração com Vercel é nativa e o deploy é trivial.
### Porque PostgreSQL em vez de MongoDB?
Os dados da PawLink são fortemente relacionais (utilizador → reserva → animal → canil). Uma base de dados relacional como PostgreSQL garante integridade referencial por defeito, suporta transacções ACID (críticas para reservas e pagamentos) e tem melhor suporte a queries complexas com joins.
### Porque Tailwind CSS em vez de CSS Modules ou Styled Components?
Tailwind elimina a necessidade de alternar entre ficheiros CSS e JSX. As classes utilitárias são co-localizadas com o markup, tornando o código mais fácil de ler e manter. O modo JIT garante que apenas as classes usadas chegam ao bundle final.
### Porque Stripe em vez de SIBS/Multibanco directo?
O Stripe suporta MBWay, MB Multibanco e SEPA através da sua abstracção unificada (Payment Element), é PCI DSS Level 1 (o mais alto), tem webhooks fiáveis para confirmações assíncronas, e tem documentação e SDK TypeScript excelentes. A integração directa com SIBS requer certificações e processos burocráticos inadequados para a fase inicial.