claude-plugins/negocio/skills/saas/SKILL.md

---
name: saas
description: Skill especializada em arquitectura e desenvolvimento de produtos SaaS
  (Software as a Service), cobrindo multi-tenancy, billing, onboarding e métricas.
author: Descomplicar® Crescimento Digital
version: 2.0.0
quality_score: 55
user_invocable: true
desk_task: null
allowed-tools: Task
---

# Skill /saas - SaaS Architecture & Strategy

Skill especializada em arquitectura e desenvolvimento de produtos SaaS (Software as a Service), cobrindo multi-tenancy, billing, onboarding e métricas.

## Sintaxe

```
/saas [operacao] [contexto]
```

**Operações:**
- `arquitectura` - Design multi-tenant, isolamento dados, escalabilidade
- `pricing` - Modelos de preços e packaging de features
- `onboarding` - Flow de activação e time-to-value
- `billing` - Integração Stripe, trial, upgrades/downgrades
- `metricas` - Dashboard MRR, churn, LTV, CAC

## Quando Usar

- Planear novo produto SaaS
- Migrar aplicação tradicional para SaaS
- Optimizar onboarding ou reduzir churn
- Implementar billing e subscriptions
- Arquitectura multi-tenant

---

## Protocolo de Execução

### 1. Discovery de Produto

**Questões chave:**
```
Modelo de negócio:
- [ ] B2B, B2C ou B2B2C?
- [ ] Self-service ou sales-led?
- [ ] PLG (product-led growth)?

Utilizadores:
- [ ] Quantos users por tenant?
- [ ] Diferentes roles/permissões?
- [ ] Colaboração entre users?

Dados:
- [ ] Volume de dados por tenant?
- [ ] Regulamentações (GDPR, HIPAA)?
- [ ] Backup e disaster recovery?

Integrações:
- [ ] APIs third-party necessárias?
- [ ] SSO/SAML enterprise?
- [ ] Webhooks para partners?
```

### 2. Arquitectura Multi-tenant

**Estratégias de Isolamento:**

```
┌─────────────────────────────────────────────────┐
│ 1. DATABASE PER TENANT (Isolamento Máximo)     │
├─────────────────────────────────────────────────┤
│ Prós: Segurança total, restore independente     │
│ Contras: Custo, complexidade gestão             │
│ Usar quando: Enterprise, regulamentações        │
│ Exemplo: AWS RDS + Aurora Serverless            │
└─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│ 2. SCHEMA PER TENANT (Equilíbrio)              │
├─────────────────────────────────────────────────┤
│ Prós: Bom isolamento, gestão simplificada       │
│ Contras: Limites BD (PostgreSQL ~10k schemas)   │
│ Usar quando: B2B médio porte                    │
│ Exemplo: PostgreSQL schemas dinâmicos           │
└─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│ 3. SHARED DB + ROW-LEVEL SECURITY (Económico)  │
├─────────────────────────────────────────────────┤
│ Prós: Mais barato, fácil escalar                │
│ Contras: tenant_id em tudo, RLS obrigatório     │
│ Usar quando: B2C, SMB self-service              │
│ Exemplo: PostgreSQL RLS policies                │
└─────────────────────────────────────────────────┘
```

**Implementação Row-Level Security (PostgreSQL):**

```sql
-- 1. Adicionar tenant_id a todas as tabelas
ALTER TABLE users ADD COLUMN tenant_id UUID NOT NULL;
ALTER TABLE projects ADD COLUMN tenant_id UUID NOT NULL;
ALTER TABLE documents ADD COLUMN tenant_id UUID NOT NULL;

-- 2. Activar RLS
ALTER TABLE users ENABLE ROW LEVEL SECURITY;
ALTER TABLE projects ENABLE ROW LEVEL SECURITY;
ALTER TABLE documents ENABLE ROW LEVEL SECURITY;

-- 3. Criar policy de isolamento
CREATE POLICY tenant_isolation ON users
    USING (tenant_id = current_setting('app.tenant_id')::uuid);

CREATE POLICY tenant_isolation ON projects
    USING (tenant_id = current_setting('app.tenant_id')::uuid);

-- 4. No início de cada request (backend)
-- SET app.tenant_id = 'uuid-do-tenant-autenticado';
```

**Checklist Segurança Multi-tenant:**
```
[ ] tenant_id em TODAS as tabelas
[ ] RLS policies activas
[ ] Indexes em tenant_id (performance)
[ ] Validação tenant_id no auth middleware
[ ] Logs de acesso cross-tenant
[ ] Testes de isolamento (tenant A não vê tenant B)
```

### 3. Modelos de Pricing

| Modelo | Descrição | Exemplo | Quando Usar |
|--------|-----------|---------|-------------|
| **Flat Rate** | Preço fixo mensal | 29€/mês | Simplicidade, previsibilidade |
| **Per Seat** | Por utilizador | 10€/user/mês | B2B, equipas |
| **Usage Based** | Pay-as-you-go | 0.01€/API call | Variação alta de uso |
| **Tiered** | Planos com limites | Free/Pro/Enterprise | Upsell natural |
| **Hybrid** | Base + usage | 20€ + 0.001€/email | Receita previsível + escala |

**Recomendação Descomplicar:**
```
B2B (equipas 5-50 users): PER SEAT
B2C (individual): TIERED
API/Infra (desenvolvedores): USAGE BASED
SaaS tradicional: HYBRID (base + usage caps)
```

**Exemplo de Tiers:**

```
┌─────────────────────────────────────────────────┐
│ FREE                                    0€/mês  │
├─────────────────────────────────────────────────┤
│ ✓ 1 user                                        │
│ ✓ 100 records/mês                               │
│ ✓ 1 GB storage                                  │
│ ✗ Integrações                                   │
│ ✗ API access                                    │
│ ✗ Suporte prioritário                           │
└─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│ PRO                                    29€/mês  │
├─────────────────────────────────────────────────┤
│ ✓ 5 users                                       │
│ ✓ 10.000 records/mês                            │
│ ✓ 50 GB storage                                 │
│ ✓ Integrações básicas                           │
│ ✓ API access (10k calls/mês)                    │
│ ✓ Email support (24h)                           │
└─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│ ENTERPRISE                           Custom     │
├─────────────────────────────────────────────────┤
│ ✓ Users ilimitados                              │
│ ✓ Records ilimitados                            │
│ ✓ Storage dedicado                              │
│ ✓ Todas as integrações                          │
│ ✓ API ilimitado                                 │
│ ✓ Suporte 24/7 + Account Manager                │
│ ✓ SSO/SAML                                      │
│ ✓ SLA 99.9%                                     │
└─────────────────────────────────────────────────┘
```

### 4. Stack Técnica Recomendada

**Frontend:**
```
Framework: Next.js 14+ (App Router)
Styling: Tailwind CSS + shadcn/ui
State: Zustand / Jotai
Forms: React Hook Form + Zod
```

**Backend:**
```
API: Next.js API Routes / tRPC
Database: PostgreSQL (Supabase / Railway)
ORM: Prisma
Queue: BullMQ / Inngest (background jobs)
Cache: Redis (Upstash)
```

**Auth & Billing:**
```
Auth: Clerk / Auth0 / NextAuth.js
Billing: Stripe Billing (subscriptions)
Email: Resend / SendGrid
Analytics: PostHog / Mixpanel
```

**Hosting:**
```
Frontend: Vercel
Backend: Railway / Fly.io
Database: Supabase / Neon
CDN: Cloudflare
```

### 5. Onboarding Flow (Time-to-Value)

**Objectivo:** Levar user de signup a "aha moment" em < 5 minutos.

```
┌────────────────────────────────────────────────┐
│ 1. SIGNUP                                      │
│    Email + Password (ou OAuth Google)          │
│    ↓ < 30 segundos                              │
├────────────────────────────────────────────────┤
│ 2. WELCOME                                     │
│    Vídeo 30s: "O que vais conseguir"           │
│    ↓ Skip disponível                            │
├────────────────────────────────────────────────┤
│ 3. QUICK SETUP                                 │
│    3-5 campos essenciais (restantes opcional)   │
│    Progress bar: "2/3 completo"                 │
│    ↓ < 2 minutos                                │
├────────────────────────────────────────────────┤
│ 4. FIRST ACTION                                │
│    Criar primeiro [projecto/documento/etc]      │
│    Usar template pré-preenchido                 │
│    ↓ < 2 minutos                                │
├────────────────────────────────────────────────┤
│ 5. AHA MOMENT                                  │
│    Ver resultado imediato (export, share, etc)  │
│    Celebrar: "Parabéns! Criaste o teu 1º X"    │
│    ↓                                            │
├────────────────────────────────────────────────┤
│ 6. NEXT STEPS                                  │
│    Checklist guiada: "3 passos para dominar"   │
│    Invite team, integração, etc                 │
└────────────────────────────────────────────────┘
```

**Métricas de Onboarding:**
```
- Signup → Email verified: > 80%
- Email verified → Setup complete: > 60%
- Setup → First action: > 70%
- First action → Aha moment: > 90%
- Activation rate (signup → aha): > 40%
```

### 6. Billing com Stripe

**Setup Básico:**

```typescript
// 1. Criar produtos e preços no Stripe Dashboard
// Free: price_free (0€)
// Pro: price_pro (29€/mês)
// Enterprise: price_enterprise (custom)

// 2. Criar subscription no signup
import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

const subscription = await stripe.subscriptions.create({
  customer: customerId,
  items: [{ price: 'price_free' }],
  trial_period_days: 14, // Trial 14 dias
  payment_behavior: 'default_incomplete',
  expand: ['latest_invoice.payment_intent']
});

// 3. Webhooks para sincronizar estado
// - customer.subscription.created
// - customer.subscription.updated
// - customer.subscription.deleted
// - invoice.payment_succeeded
// - invoice.payment_failed

// 4. Verificar feature access
const canUseFeature = (user: User, feature: string) => {
  if (user.subscription.status !== 'active') return false;
  return PLAN_FEATURES[user.subscription.plan].includes(feature);
};
```

**Trial → Paid Conversion:**
```
Trial 14 dias (sem cartão)
  │
  ├─ Dia 7: Email "Metade do trial"
  ├─ Dia 12: Email "2 dias restantes + valor criado"
  ├─ Dia 14: Soft paywall (pedir cartão)
  │
  ▼
Converteu? → Pro (29€/mês)
Não converteu? → Free (downgrade features)
```

---

## Métricas SaaS (KPIs)

### Receita

| Métrica | Fórmula | Target |
|---------|---------|--------|
| **MRR** | Monthly Recurring Revenue | Crescimento mês/mês |
| **ARR** | MRR × 12 | > 100k€ para sustainable |
| **ARPU** | MRR / Total customers | Sector-dependent |
| **NRR** | (MRR início + expansion - churn - contraction) / MRR início | > 100% |

### Crescimento

| Métrica | Fórmula | Target |
|---------|---------|--------|
| **New MRR** | Novos clientes × preço médio | +20%/mês (early) |
| **Expansion MRR** | Upsells + Add-ons | > 10% do MRR |
| **Churn MRR** | Cancelamentos valor | < 5%/mês |

### Aquisição

| Métrica | Fórmula | Target |
|---------|---------|--------|
| **CAC** | Custo marketing+sales / Novos clientes | < 1/3 LTV |
| **LTV** | ARPU × (1 / Churn Rate) - CAC | > 3× CAC |
| **Payback Period** | CAC / ARPU | < 12 meses |

### Produto

| Métrica | Target |
|---------|--------|
| **Activation Rate** | > 40% (signup → aha moment) |
| **DAU/MAU** | > 20% (stickiness) |
| **Time to Value** | < 10 minutos |
| **Feature Adoption** | > 30% users usam feature nova (30 dias) |

### Retenção

| Métrica | Fórmula | Target |
|---------|---------|--------|
| **Logo Churn** | Clientes cancelaram / Total | < 5%/mês |
| **Revenue Churn** | MRR perdido / MRR total | < 5%/mês |
| **Cohort Retention** | Clientes mês X activos em X+6 | > 50% |

---

## Feature Flags por Plano

```typescript
// config/features.ts
export const PLAN_FEATURES = {
  free: [
    'basic_dashboard',
    'limited_records',
    'email_support'
  ],
  pro: [
    'basic_dashboard',
    'unlimited_records',
    'api_access',
    'integrations_basic',
    'priority_support',
    'export_csv'
  ],
  enterprise: [
    '*', // todas as features
    'sso_saml',
    'audit_logs',
    'custom_domain',
    'dedicated_support',
    'sla_guarantee'
  ]
};

// middleware verificação
export function requireFeature(feature: string) {
  return async (req, res, next) => {
    const user = req.user;
    const plan = user.subscription.plan;

    if (!PLAN_FEATURES[plan].includes(feature) &&
        !PLAN_FEATURES[plan].includes('*')) {
      return res.status(403).json({
        error: 'Upgrade required',
        feature: feature,
        current_plan: plan,
        upgrade_to: 'pro'
      });
    }

    next();
  };
}

// Uso no route
app.get('/api/export',
  requireAuth,
  requireFeature('export_csv'),
  async (req, res) => {
    // ...
  }
);
```

---

## Consultar Datasets Dify

**SEMPRE antes de arquitectar solução:**

| Dataset | ID | Query Exemplo |
|---------|----|--------------:|
| **Estratégia** | `7d1d1d21-bc05-43d8-ab8f-6b7b90dafc28` | "saas pricing modelo subscription" |
| **Gestão** | `22799925-8dc5-4a1f-92b9-233468a5048b` | "metricas saas mrr churn ltv" |
| **Desenvolvimento Software** | `52c29c6b-7f76-42fe-ad4b-0bf8ff05cc73` | "arquitectura multitenancy postgresql" |

### Como Consultar

```javascript
// Modelos de pricing
mcp__notebooklm__notebook_query, mcp__dify-kb__dify_kb_retrieve_segments({
  dataset_id: "7d1d1d21-bc05-43d8-ab8f-6b7b90dafc28",
  query: "saas pricing tiers feature packaging",
  retrieval_mode: "hybrid_search",
  top_k: 5
});

// Métricas e KPIs
mcp__dify-kb__dify_kb_retrieve_segments({
  dataset_id: "22799925-8dc5-4a1f-92b9-233468a5048b",
  query: "metricas saas cohort retention churn",
  retrieval_mode: "hybrid_search",
  top_k: 5
});
```

---

## MCPs Utilizados

```
mcp__desk-crm-v3__*                  # Gestão projectos SaaS
mcp__dify-kb__dify_kb_retrieve_segments  # Conhecimento estratégico
```

---

## Exemplos de Uso

### 1. Planeamento Novo SaaS
```
/saas arquitectura
→ Discovery interactivo
→ Consulta Dify KB (best practices)
→ Recomendação multi-tenancy
→ Stack técnica
→ Roadmap MVP
```

### 2. Optimização Pricing
```
/saas pricing
→ Análise competidores
→ Modelação LTV/CAC
→ Proposta tiers
→ Feature packaging
```

### 3. Dashboard Métricas
```
/saas metricas
→ Definir KPIs prioritários
→ Queries SQL para MRR/Churn
→ Setup PostHog/Mixpanel
→ Dashboards Grafana
```

---

## Agentes Recomendados

```javascript
// Arquitectura técnica
Task({
  subagent_type: "software-architect",
  model: "sonnet",
  prompt: "Design multi-tenant SaaS architecture. PostgreSQL RLS + Next.js."
});

// Estratégia produto
Task({
  subagent_type: "software-project-planner",
  model: "sonnet",
  prompt: "SaaS onboarding flow. Time-to-value < 5min. B2B productivity tool."
});
```

---

## Instrumentação Automática

### Query para Gravar (executar no final)

```sql
INSERT INTO tblskill_agent_metrics (
  type, name, duration_ms, status, staff_id,
  kb_consulted, kb_cache_hit, tool_calls, project_id
) VALUES (
  'skill', '/saas', {DURACAO_MS}, '{STATUS}', 25,
  {KB_CONSULTADO}, {CACHE_HIT}, {TOOL_CALLS}, {PROJECT_ID}
);
```

---

**Versão**: 2.0.0 | **Data**: 2026-02-03 | **Autor**: Descomplicar®
**Instrumentação**: Activa