# Micro-SaaS - Especificação

## 1. Visão Geral

Sistema Micro-SaaS multi-tenant com gestão de assinaturas e billing integrado via Asaas.

### 1.1 Objetivos

- Permitir criação de tenants isolados
- Gerenciar assinaturas e pagamentos
- Fornecer dashboard administrativo por tenant
- Escalar de forma econômica (scale-to-zero)

### 1.2 Personas

| Persona | Descrição |
|---------|-----------|
| **Tenant Owner** | Cria e administra o tenant |
| **Tenant Admin** | Gerencia usuários e configurações |
| **Tenant Member** | Usuário regular do sistema |
| **Platform Admin** | Administrador da plataforma (super admin) |

## 2. Requisitos Funcionais

### 2.1 Autenticação & Autorização

| ID | Requisito |
|----|-----------|
| AUTH-001 | Login via Clerk (email, Google, Microsoft) |
| AUTH-002 | Criação automática de tenant no primeiro login |
| AUTH-003 | Convite de usuários para tenant existente |
| AUTH-004 | Roles: Owner, Admin, Member, Viewer |
| AUTH-005 | Permissões granulares por role |

### 2.2 Multi-Tenancy

| ID | Requisito |
|----|-----------|
| MT-001 | Isolamento completo de dados por tenant |
| MT-002 | Subdomínio customizado (acme.app.com) |
| MT-003 | Domínio customizado opcional |
| MT-004 | Configurações independentes por tenant |
| MT-005 | Branding básico (logo, cores) |

### 2.3 Subscription & Billing

| ID | Requisito |
|----|-----------|
| SUB-001 | Planos: Free, Starter, Pro, Enterprise |
| SUB-002 | Ciclos: Mensal e Anual |
| SUB-003 | Métodos: PIX, Boleto, Cartão de Crédito |
| SUB-004 | Trial period de 14 dias |
| SUB-005 | Upgrade/Downgrade de plano |
| SUB-006 | Cancelamento com período de carência |
| SUB-007 | Webhooks Asaas para status de pagamento |

### 2.4 Dashboard

| ID | Requisito |
|----|-----------|
| DASH-001 | Overview com métricas principais |
| DASH-002 | Gestão de usuários do tenant |
| DASH-003 | Histórico de pagamentos |
| DASH-004 | Configurações do tenant |
| DASH-005 | Upgrade de plano |

## 3. Requisitos Não-Funcionais

### 3.1 Performance

| ID | Requisito |
|----|-----------|
| PERF-001 | Tempo de resposta < 200ms (P95) |
| PERF-002 | Scale-to-zero quando inativo |
| PERF-003 | Auto-scaling até 10 instâncias |

### 3.2 Segurança

| ID | Requisito |
|----|-----------|
| SEC-001 | HTTPS obrigatório |
| SEC-002 | Validação de webhook signature |
| SEC-003 | Rate limiting por tenant |
| SEC-004 | Audit log de ações críticas |

### 3.3 Disponibilidade

| ID | Requisito |
|----|-----------|
| AVAIL-001 | SLA 99.5% |
| AVAIL-002 | Health checks ativos |
| AVAIL-003 | Retry automático em falhas |

## 4. Planos e Limites

| Feature | Free | Starter | Pro | Enterprise |
|---------|------|---------|-----|------------|
| Usuários | 2 | 5 | 20 | Ilimitado |
| Storage | 100MB | 1GB | 10GB | 100GB |
| API Requests/mês | 1K | 10K | 100K | Ilimitado |
| Suporte | Community | Email | Priority | Dedicated |
| Preço/mês | R$0 | R$49 | R$149 | R$499 |

## 5. Integrações

### 5.1 Asaas

- Customer management
- Subscription lifecycle
- Payment processing
- Webhook handling

### 5.2 Clerk

- User authentication
- Session management
- Organization (tenant) mapping

## 6. Arquitetura

### 6.1 Componentes

```
┌─────────────────────────────────────────────────────────────┐
│                        Blazor Server                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   Pages     │  │ Components  │  │    Services         │  │
│  │  /dashboard │  │ NavMenu     │  │ TenantContext       │  │
│  │  /settings  │  │ DataGrid    │  │ SubscriptionService │  │
│  │  /billing   │  │ Charts      │  │ UserService         │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     Application Layer                        │
│  ┌─────────────────────────────────────────────────────┐    │
│  │  Commands: CreateTenant, InviteUser, ChangePlan     │    │
│  │  Queries: GetDashboard, GetUsers, GetPayments       │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     Infrastructure                           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │  EF Core     │  │  Asaas       │  │  Clerk           │  │
│  │  Repository  │  │  Client      │  │  Integration     │  │
│  └──────────────┘  └──────────────┘  └──────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  SQL Database │  Azure Storage  │  Key Vault (secrets)     │
└─────────────────────────────────────────────────────────────┘
```

### 6.2 Tenant Resolution

1. Subdomínio: `{tenant}.app.com`
2. Header: `X-Tenant-ID`
3. Route: `/tenant/{slug}/...`
4. Claim: JWT tenant_id

## 7. Modelo de Dados

### 7.1 Entidades Principais

```
Tenant
├── Id (int)
├── Name (string)
├── Slug (string) [unique]
├── Status (Active, Suspended, Deleted)
├── AsaasCustomerId (string)
├── CurrentSubscription → Subscription
└── Users → TenantUser[]

TenantUser
├── Id (int)
├── TenantId → Tenant
├── ExternalUserId (string) [Clerk ID]
├── Email (string)
├── Role (Owner, Admin, Member, Viewer)
└── Status (Pending, Active, Inactive)

Plan
├── Id (int)
├── Name (string)
├── PriceMonthly (decimal)
├── PriceYearly (decimal)
├── Features (JSON)
└── Limits (JSON)

Subscription
├── Id (int)
├── TenantId → Tenant
├── PlanId → Plan
├── AsaasSubscriptionId (string)
├── Status (Trial, Active, PastDue, Canceled)
├── BillingCycle (Monthly, Yearly)
├── CurrentPeriodStart (DateTime)
└── CurrentPeriodEnd (DateTime)
```

## 8. APIs

### 8.1 Tenant Management

| Endpoint | Method | Descrição |
|----------|--------|-----------|
| `/api/tenants` | POST | Criar tenant |
| `/api/tenants/{id}` | GET | Obter tenant |
| `/api/tenants/{id}` | PUT | Atualizar tenant |
| `/api/tenants/{id}/users` | GET | Listar usuários |
| `/api/tenants/{id}/users` | POST | Convidar usuário |

### 8.2 Subscription

| Endpoint | Method | Descrição |
|----------|--------|-----------|
| `/api/subscriptions` | POST | Criar subscription |
| `/api/subscriptions/{id}` | GET | Obter subscription |
| `/api/subscriptions/{id}/upgrade` | POST | Upgrade de plano |
| `/api/subscriptions/{id}/cancel` | POST | Cancelar |

### 8.3 Webhooks

| Endpoint | Method | Descrição |
|----------|--------|-----------|
| `/webhooks/asaas` | POST | Eventos Asaas |
| `/webhooks/clerk` | POST | Eventos Clerk |

---

*MORPH-SPEC by Polymorphism Tech*
