@polymorphism-tech/morph-spec 2.4.0 → 3.0.0

package/content/.morph/examples/micro-saas/spec.md

@@ -1,236 +1,236 @@
-# 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*
+# 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*