@polymorphism-tech/morph-spec 3.2.0 → 4.2.0

package/stacks/blazor-azure/.morph/examples/micro-saas/decisions.md

@@ -1,246 +0,0 @@
-# Micro-SaaS - Architectural Decision Records
-
-## ADR-001: Blazor Server vs Blazor WebAssembly
-
-**Status**: Accepted
-
-**Context**: Escolher entre Blazor Server e Blazor WebAssembly para o frontend.
-
-**Decision**: Blazor Server
-
-**Rationale**:
-- Melhor para dashboards com dados em tempo real
-- Menor payload inicial
-- Acesso direto ao backend (sem API intermediária)
-- Melhor SEO com pre-rendering
-- Scale-to-zero funciona bem com Container Apps
-
-**Consequences**:
-- Requer conexão SignalR persistente
-- Latência perceptível em conexões lentas
-- Não funciona offline
-
----
-
-## ADR-002: Asaas vs Stripe para Billing
-
-**Status**: Accepted
-
-**Context**: Escolher gateway de pagamento para mercado brasileiro.
-
-**Decision**: Asaas
-
-**Rationale**:
-- Suporte nativo a PIX e Boleto
-- Taxas competitivas para Brasil
-- API bem documentada
-- Webhooks confiáveis
-- Gestão de assinaturas built-in
-
-**Consequences**:
-- Limitado ao mercado brasileiro
-- Menos features que Stripe
-- Se expandir internacionalmente, precisará adicionar outro gateway
-
----
-
-## ADR-003: Clerk vs Azure AD B2C para Auth
-
-**Status**: Accepted
-
-**Context**: Escolher provider de autenticação.
-
-**Decision**: Clerk (com Azure AD como alternativa)
-
-**Rationale**:
-- Setup mais simples
-- UI pré-construída
-- Boa integração com .NET
-- Free tier generoso (10k MAU)
-- Organization support para multi-tenancy
-
-**Alternatives Considered**:
-- Azure AD B2C: Mais complexo, mas melhor para enterprise
-- Auth0: Boa opção, mas mais caro
-
-**Consequences**:
-- Dependência de serviço terceiro
-- Custo em escala (após 10k MAU)
-
----
-
-## ADR-004: Multi-Tenancy Strategy
-
-**Status**: Accepted
-
-**Context**: Definir estratégia de isolamento de dados.
-
-**Decision**: Database-per-tenant com query filter
-
-**Rationale**:
-- Single database com `TenantId` em cada tabela
-- EF Core Global Query Filters para isolamento
-- Mais econômico que database separado
-- Escala bem para milhares de tenants
-
-**Implementation**:
-```csharp
-modelBuilder.Entity<Order>()
-    .HasQueryFilter(o => o.TenantId == _tenantContext.TenantId);
-```
-
-**Consequences**:
-- Cuidado extra com queries que bypassam filtros
-- Backup/restore é do banco inteiro
-- Migração de tenant individual é mais complexa
-
----
-
-## ADR-005: Tenant Resolution Strategy
-
-**Status**: Accepted
-
-**Context**: Como identificar o tenant em cada request.
-
-**Decision**: Multiple strategies (subdomain > header > route > claim)
-
-**Rationale**:
-1. **Subdomain** (`acme.app.com`): Mais limpo para usuários
-2. **Header** (`X-Tenant-ID`): Para APIs
-3. **Route** (`/tenant/{slug}`): Fallback
-4. **Claim**: Para JWT tokens
-
-**Consequences**:
-- DNS wildcard necessário
-- Configuração de CORS mais complexa
-- Custom domains requerem SSL wildcard ou certificados individuais
-
----
-
-## ADR-006: Azure Container Apps vs App Service
-
-**Status**: Accepted
-
-**Context**: Escolher serviço de hosting.
-
-**Decision**: Azure Container Apps
-
-**Rationale**:
-- Scale-to-zero (custo zero quando inativo)
-- Auto-scaling baseado em HTTP requests
-- Built-in ingress controller
-- Managed identity integration
-- Mais barato para cargas variáveis
-
-**Consequences**:
-- Cold start de ~2-5 segundos
-- Menos features que App Service
-- Debugging mais complexo
-
----
-
-## ADR-007: SQL Server Free Tier
-
-**Status**: Accepted
-
-**Context**: Escolher tier de database.
-
-**Decision**: SQL Server Free Tier (32GB)
-
-**Rationale**:
-- Custo zero para desenvolvimento e MVPs
-- 32GB suficiente para milhares de tenants pequenos
-- Upgrade fácil quando necessário
-- Compatível com EF Core
-
-**Consequences**:
-- Limites de DTU/vCore
-- Sem geo-replication
-- Upgrade necessário para produção de alta escala
-
----
-
-## ADR-008: Subscription Lifecycle
-
-**Status**: Accepted
-
-**Context**: Definir estados e transições de subscription.
-
-**Decision**: Estado máquina com 5 estados
-
-```
-Trial → Active → PastDue → Canceled
-                    ↓
-                 Expired
-```
-
-**States**:
-- **Trial**: 14 dias sem cobrança
-- **Active**: Pagamento em dia
-- **PastDue**: Pagamento atrasado (grace period 7 dias)
-- **Canceled**: Cancelado pelo usuário
-- **Expired**: Trial ou grace period expirado
-
-**Consequences**:
-- Lógica de transição precisa ser robusta
-- Webhooks Asaas controlam transições de pagamento
-- Jobs agendados para expiração de trial
-
----
-
-## ADR-009: Caching Strategy
-
-**Status**: Accepted
-
-**Context**: Definir estratégia de cache.
-
-**Decision**: In-memory cache com invalidation
-
-**Rationale**:
-- Tenant data raramente muda
-- Plans são estáticos
-- In-memory suficiente para Container Apps com poucas instâncias
-
-**Implementation**:
-- `IMemoryCache` para dados de leitura frequente
-- Cache invalidation em updates
-
-**Consequences**:
-- Cache não compartilhado entre instâncias
-- Inconsistência temporária possível (aceitável)
-
----
-
-## ADR-010: Error Handling Strategy
-
-**Status**: Accepted
-
-**Context**: Padronizar tratamento de erros.
-
-**Decision**: Problem Details (RFC 7807) + Global Exception Handler
-
-**Implementation**:
-```csharp
-app.UseExceptionHandler(options =>
-{
-    options.Run(async context =>
-    {
-        var problemDetails = new ProblemDetails
-        {
-            Status = StatusCodes.Status500InternalServerError,
-            Title = "An error occurred",
-            Instance = context.Request.Path
-        };
-        await context.Response.WriteAsJsonAsync(problemDetails);
-    });
-});
-```
-
-**Consequences**:
-- Respostas de erro consistentes
-- Fácil integração com frontends
-- Logging estruturado
-
----
-
-*MORPH-SPEC by Polymorphism Tech*

package/stacks/blazor-azure/.morph/examples/micro-saas/spec.md

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

package/stacks/blazor-azure/.morph/examples/micro-saas/tasks.md

@@ -1,150 +0,0 @@
-# Micro-SaaS - Tasks
-
-## Fase 1: Setup do Projeto
-
-| ID | Task | Dependências | Estimativa |
-|----|------|--------------|------------|
-| T001 | Criar solution e projetos | - | S |
-| T002 | Configurar packages NuGet | T001 | S |
-| T003 | Criar estrutura de pastas | T001 | S |
-| T004 | Configurar appsettings.json | T001 | S |
-
-## Fase 2: Domain Layer
-
-| ID | Task | Dependências | Estimativa |
-|----|------|--------------|------------|
-| T005 | Criar BaseEntity | T001 | S |
-| T006 | Criar Tenant entity | T005 | M |
-| T007 | Criar TenantUser entity | T005 | M |
-| T008 | Criar Plan entity | T005 | S |
-| T009 | Criar Subscription entity | T005 | M |
-| T010 | Criar SubscriptionPayment entity | T005 | M |
-| T011 | Definir enums | T005 | S |
-
-## Fase 3: Infrastructure Layer
-
-| ID | Task | Dependências | Estimativa |
-|----|------|--------------|------------|
-| T012 | Criar AppDbContext | T006-T011 | M |
-| T013 | Configurar EF Core mappings | T012 | M |
-| T014 | Criar TenantRepository | T012 | M |
-| T015 | Criar TenantUserRepository | T012 | M |
-| T016 | Criar SubscriptionRepository | T012 | M |
-| T017 | Criar PlanRepository | T012 | S |
-| T018 | Criar PaymentRepository | T012 | M |
-| T019 | Implementar AsaasClient | T002 | L |
-| T020 | Implementar AsaasWebhookHandler | T019 | M |
-
-## Fase 4: Application Layer
-
-| ID | Task | Dependências | Estimativa |
-|----|------|--------------|------------|
-| T021 | Criar TenantService | T014, T015 | M |
-| T022 | Criar TenantUserService | T015 | M |
-| T023 | Criar SubscriptionService | T016, T019 | L |
-| T024 | Criar PlanService | T017 | S |
-| T025 | Criar DashboardService | T014-T018 | M |
-| T026 | Criar WebhookService | T020, T016, T018 | M |
-
-## Fase 5: Web Layer - Auth
-
-| ID | Task | Dependências | Estimativa |
-|----|------|--------------|------------|
-| T027 | Configurar Clerk authentication | T002 | M |
-| T028 | Implementar TenantContext | T014 | M |
-| T029 | Criar middleware de tenant resolution | T028 | M |
-| T030 | Configurar policies de autorização | T027 | S |
-
-## Fase 6: Web Layer - Components
-
-| ID | Task | Dependências | Estimativa |
-|----|------|--------------|------------|
-| T031 | Criar MainLayout | T027 | M |
-| T032 | Criar NavMenu | T031 | S |
-| T033 | Criar componentes shared (DataGrid, Card, etc) | T031 | M |
-
-## Fase 7: Web Layer - Pages
-
-| ID | Task | Dependências | Estimativa |
-|----|------|--------------|------------|
-| T034 | Criar página Dashboard | T025, T031 | M |
-| T035 | Criar página Users | T022, T033 | M |
-| T036 | Criar página Settings | T021, T033 | M |
-| T037 | Criar página Billing | T023, T033 | L |
-| T038 | Criar página Plans | T024, T033 | M |
-
-## Fase 8: Web Layer - APIs
-
-| ID | Task | Dependências | Estimativa |
-|----|------|--------------|------------|
-| T039 | Criar endpoints Tenant | T021 | M |
-| T040 | Criar endpoints Users | T022 | M |
-| T041 | Criar endpoints Subscription | T023 | M |
-| T042 | Criar endpoint Webhook | T026 | M |
-
-## Fase 9: Infrastructure (IaC)
-
-| ID | Task | Dependências | Estimativa |
-|----|------|--------------|------------|
-| T043 | Criar main.bicep | - | M |
-| T044 | Configurar Container App | T043 | M |
-| T045 | Configurar SQL Database | T043 | M |
-| T046 | Configurar Key Vault | T043 | S |
-| T047 | Configurar App Insights | T043 | S |
-
-## Fase 10: Testes e Documentação
-
-| ID | Task | Dependências | Estimativa |
-|----|------|--------------|------------|
-| T048 | Criar testes unitários Domain | T006-T011 | M |
-| T049 | Criar testes integração Services | T021-T026 | L |
-| T050 | Criar testes E2E | T034-T042 | L |
-| T051 | Documentar APIs (OpenAPI) | T039-T042 | M |
-
-## Checkpoints
-
-| Checkpoint | Após Tasks | Validação |
-|------------|------------|-----------|
-| CP1 | T004 | Projeto compila |
-| CP2 | T011 | Domain layer completo |
-| CP3 | T020 | Infrastructure layer completo |
-| CP4 | T026 | Application layer completo |
-| CP5 | T033 | Layout e componentes prontos |
-| CP6 | T038 | Todas as páginas funcionando |
-| CP7 | T042 | APIs funcionando |
-| CP8 | T047 | IaC pronto para deploy |
-| CP9 | T051 | Projeto completo |
-
-## Legenda
-
-- **S** = Small (< 1h)
-- **M** = Medium (1-3h)
-- **L** = Large (3-8h)
-
-## Ordem de Execução Recomendada
-
-```
-T001 → T002 → T003 → T004 (CP1)
-  ↓
-T005 → T006-T011 (CP2)
-  ↓
-T012 → T013 → T014-T020 (CP3)
-  ↓
-T021-T026 (CP4)
-  ↓
-T027 → T028 → T029 → T030
-  ↓
-T031 → T032 → T033 (CP5)
-  ↓
-T034-T038 (CP6)
-  ↓
-T039-T042 (CP7)
-  ↓
-T043-T047 (CP8)
-  ↓
-T048-T051 (CP9)
-```
-
----
-
-*MORPH-SPEC by Polymorphism Tech*