@polymorphism-tech/morph-spec 1.0.0

package/content/.morph/examples/micro-saas/contracts.cs

@@ -0,0 +1,358 @@
+// ==============================================================================
+// Micro-SaaS - Contracts
+// Interfaces, DTOs e Enums do exemplo Micro-SaaS
+// ==============================================================================
+
+namespace MicroSaaS.Contracts;
+
+// ==============================================================================
+// ENUMS
+// ==============================================================================
+
+public enum TenantStatus
+{
+    Active,
+    Suspended,
+    Deleted
+}
+
+public enum TenantUserRole
+{
+    Owner,
+    Admin,
+    Member,
+    Viewer
+}
+
+public enum TenantUserStatus
+{
+    Pending,
+    Active,
+    Inactive
+}
+
+public enum SubscriptionStatus
+{
+    Trial,
+    Active,
+    PastDue,
+    Canceled,
+    Expired
+}
+
+public enum BillingCycle
+{
+    Monthly,
+    Yearly
+}
+
+public enum PaymentStatus
+{
+    Pending,
+    Confirmed,
+    Received,
+    Overdue,
+    Refunded,
+    Chargeback
+}
+
+public enum PaymentMethod
+{
+    Pix,
+    Boleto,
+    CreditCard
+}
+
+// ==============================================================================
+// DTOs - TENANT
+// ==============================================================================
+
+public record CreateTenantRequest(
+    string Name,
+    string Slug,
+    string OwnerEmail,
+    string OwnerExternalId
+);
+
+public record UpdateTenantRequest(
+    string Name,
+    string? Description,
+    string? LogoUrl
+);
+
+public record TenantResponse(
+    int Id,
+    string Name,
+    string Slug,
+    string? Description,
+    string? LogoUrl,
+    TenantStatus Status,
+    string? CustomDomain,
+    SubscriptionSummaryResponse? Subscription,
+    DateTime CreatedAt
+);
+
+public record TenantSummaryResponse(
+    int Id,
+    string Name,
+    string Slug,
+    TenantStatus Status
+);
+
+// ==============================================================================
+// DTOs - TENANT USER
+// ==============================================================================
+
+public record InviteUserRequest(
+    string Email,
+    TenantUserRole Role = TenantUserRole.Member
+);
+
+public record UpdateUserRoleRequest(
+    TenantUserRole Role
+);
+
+public record TenantUserResponse(
+    int Id,
+    string Email,
+    string? Name,
+    TenantUserRole Role,
+    TenantUserStatus Status,
+    DateTime? LastLoginAt,
+    DateTime CreatedAt
+);
+
+// ==============================================================================
+// DTOs - PLAN
+// ==============================================================================
+
+public record PlanResponse(
+    int Id,
+    string Name,
+    string? Description,
+    decimal PriceMonthly,
+    decimal PriceYearly,
+    PlanLimits Limits,
+    PlanFeatures Features,
+    bool IsActive
+);
+
+public record PlanLimits(
+    int MaxUsers,
+    long MaxStorageBytes,
+    int MaxApiRequestsPerMonth
+);
+
+public record PlanFeatures(
+    bool CustomDomain,
+    bool ApiAccess,
+    bool PrioritySupport,
+    bool AdvancedAnalytics
+);
+
+// ==============================================================================
+// DTOs - SUBSCRIPTION
+// ==============================================================================
+
+public record CreateSubscriptionRequest(
+    int PlanId,
+    BillingCycle BillingCycle,
+    PaymentMethod PaymentMethod
+);
+
+public record UpgradeSubscriptionRequest(
+    int NewPlanId,
+    bool ImmediateUpgrade = true
+);
+
+public record SubscriptionResponse(
+    int Id,
+    int TenantId,
+    PlanResponse Plan,
+    SubscriptionStatus Status,
+    BillingCycle BillingCycle,
+    DateTime CurrentPeriodStart,
+    DateTime CurrentPeriodEnd,
+    DateTime? TrialEndsAt,
+    DateTime? CanceledAt,
+    string? AsaasSubscriptionId,
+    DateTime CreatedAt
+);
+
+public record SubscriptionSummaryResponse(
+    int Id,
+    string PlanName,
+    SubscriptionStatus Status,
+    DateTime CurrentPeriodEnd,
+    int DaysRemaining
+);
+
+// ==============================================================================
+// DTOs - PAYMENT
+// ==============================================================================
+
+public record PaymentResponse(
+    int Id,
+    decimal Amount,
+    PaymentStatus Status,
+    PaymentMethod Method,
+    DateTime? PaidAt,
+    DateTime DueDate,
+    string? AsaasPaymentId,
+    string? InvoiceUrl,
+    string? PixQrCode,
+    string? BoletoBarcode
+);
+
+// ==============================================================================
+// DTOs - DASHBOARD
+// ==============================================================================
+
+public record DashboardResponse(
+    TenantSummaryResponse Tenant,
+    SubscriptionSummaryResponse? Subscription,
+    DashboardMetrics Metrics,
+    IReadOnlyList<RecentActivityItem> RecentActivity
+);
+
+public record DashboardMetrics(
+    int TotalUsers,
+    int ActiveUsers,
+    long StorageUsedBytes,
+    long StorageLimitBytes,
+    int ApiRequestsThisMonth,
+    int ApiRequestsLimit
+);
+
+public record RecentActivityItem(
+    string Description,
+    string? UserId,
+    string? UserName,
+    DateTime Timestamp
+);
+
+// ==============================================================================
+// DTOs - WEBHOOKS
+// ==============================================================================
+
+public record AsaasWebhookPayload(
+    string Event,
+    AsaasPaymentData? Payment
+);
+
+public record AsaasPaymentData(
+    string Id,
+    string Customer,
+    string? Subscription,
+    decimal Value,
+    decimal NetValue,
+    string Status,
+    string BillingType,
+    DateTime? PaymentDate,
+    DateTime DueDate
+);
+
+// ==============================================================================
+// INTERFACES - SERVICES
+// ==============================================================================
+
+public interface ITenantService
+{
+    Task<TenantResponse> CreateAsync(CreateTenantRequest request, CancellationToken ct = default);
+    Task<TenantResponse?> GetByIdAsync(int id, CancellationToken ct = default);
+    Task<TenantResponse?> GetBySlugAsync(string slug, CancellationToken ct = default);
+    Task<TenantResponse> UpdateAsync(int id, UpdateTenantRequest request, CancellationToken ct = default);
+    Task SuspendAsync(int id, CancellationToken ct = default);
+    Task ActivateAsync(int id, CancellationToken ct = default);
+}
+
+public interface ITenantUserService
+{
+    Task<IReadOnlyList<TenantUserResponse>> GetByTenantAsync(int tenantId, CancellationToken ct = default);
+    Task<TenantUserResponse> InviteAsync(int tenantId, InviteUserRequest request, CancellationToken ct = default);
+    Task<TenantUserResponse> UpdateRoleAsync(int tenantId, int userId, UpdateUserRoleRequest request, CancellationToken ct = default);
+    Task RemoveAsync(int tenantId, int userId, CancellationToken ct = default);
+    Task RecordLoginAsync(string externalUserId, CancellationToken ct = default);
+}
+
+public interface ISubscriptionService
+{
+    Task<SubscriptionResponse> CreateAsync(int tenantId, CreateSubscriptionRequest request, CancellationToken ct = default);
+    Task<SubscriptionResponse?> GetCurrentAsync(int tenantId, CancellationToken ct = default);
+    Task<SubscriptionResponse> UpgradeAsync(int tenantId, UpgradeSubscriptionRequest request, CancellationToken ct = default);
+    Task CancelAsync(int tenantId, CancellationToken ct = default);
+    Task<IReadOnlyList<PaymentResponse>> GetPaymentsAsync(int tenantId, CancellationToken ct = default);
+}
+
+public interface IPlanService
+{
+    Task<IReadOnlyList<PlanResponse>> GetAllAsync(CancellationToken ct = default);
+    Task<PlanResponse?> GetByIdAsync(int id, CancellationToken ct = default);
+}
+
+public interface IDashboardService
+{
+    Task<DashboardResponse> GetDashboardAsync(int tenantId, CancellationToken ct = default);
+}
+
+public interface IWebhookService
+{
+    Task HandleAsaasWebhookAsync(AsaasWebhookPayload payload, CancellationToken ct = default);
+}
+
+// ==============================================================================
+// INTERFACES - REPOSITORIES
+// ==============================================================================
+
+public interface ITenantRepository
+{
+    Task<Tenant?> GetByIdAsync(int id, CancellationToken ct = default);
+    Task<Tenant?> GetBySlugAsync(string slug, CancellationToken ct = default);
+    Task<bool> SlugExistsAsync(string slug, CancellationToken ct = default);
+    Task AddAsync(Tenant tenant, CancellationToken ct = default);
+    void Update(Tenant tenant);
+}
+
+public interface ITenantUserRepository
+{
+    Task<IReadOnlyList<TenantUser>> GetByTenantAsync(int tenantId, CancellationToken ct = default);
+    Task<TenantUser?> GetByIdAsync(int id, CancellationToken ct = default);
+    Task<TenantUser?> GetByExternalIdAsync(string externalUserId, CancellationToken ct = default);
+    Task AddAsync(TenantUser user, CancellationToken ct = default);
+    void Update(TenantUser user);
+    void Remove(TenantUser user);
+}
+
+public interface ISubscriptionRepository
+{
+    Task<Subscription?> GetByIdAsync(int id, CancellationToken ct = default);
+    Task<Subscription?> GetCurrentByTenantAsync(int tenantId, CancellationToken ct = default);
+    Task<Subscription?> GetByAsaasIdAsync(string asaasSubscriptionId, CancellationToken ct = default);
+    Task AddAsync(Subscription subscription, CancellationToken ct = default);
+    void Update(Subscription subscription);
+}
+
+public interface IPlanRepository
+{
+    Task<IReadOnlyList<Plan>> GetAllActiveAsync(CancellationToken ct = default);
+    Task<Plan?> GetByIdAsync(int id, CancellationToken ct = default);
+}
+
+public interface IPaymentRepository
+{
+    Task<IReadOnlyList<SubscriptionPayment>> GetBySubscriptionAsync(int subscriptionId, CancellationToken ct = default);
+    Task<SubscriptionPayment?> GetByAsaasIdAsync(string asaasPaymentId, CancellationToken ct = default);
+    Task AddAsync(SubscriptionPayment payment, CancellationToken ct = default);
+    void Update(SubscriptionPayment payment);
+}
+
+// ==============================================================================
+// PLACEHOLDER ENTITY REFERENCES (implementados em Domain)
+// ==============================================================================
+
+// Estas classes são placeholders - a implementação real está em Domain/Entities
+public class Tenant { public int Id { get; set; } }
+public class TenantUser { public int Id { get; set; } }
+public class Subscription { public int Id { get; set; } }
+public class Plan { public int Id { get; set; } }
+public class SubscriptionPayment { public int Id { get; set; } }

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

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