@polymorphism-tech/morph-spec 4.3.3 → 4.3.5

package/framework/memory/patterns-learned.md

@@ -0,0 +1,766 @@
+# Pattern Library - Lessons Learned
+
+> **Auto-populated:** Pre-seeded patterns from MORPH-SPEC framework development
+> **Updated:** 2026-02-17
+
+Biblioteca de patterns bem-sucedidos, anti-patterns a evitar, e otimizações comprovadas.
+
+---
+
+## How to Use This Library
+
+**Before starting a feature:**
+```bash
+npx morph-spec search-patterns "blazor state"
+npx morph-spec search-patterns "background job"
+```
+
+**After completing a feature:**
+```bash
+npx morph-spec capture-pattern {feature} success "Pattern description"
+npx morph-spec capture-pattern {feature} avoid "Anti-pattern description"
+npx morph-spec capture-pattern {feature} optimization "Performance improvement"
+```
+
+---
+
+## Pattern Categories
+
+| Category | Use When | Examples |
+|----------|----------|----------|
+| `success` | Proven approaches to replicate | DI patterns, architecture choices |
+| `avoid` | Anti-patterns and mistakes made | Common pitfalls, bad practices |
+| `optimization` | Performance improvements | Query optimization, caching |
+| `security` | Security best practices | Auth, secrets management |
+| `convention` | Project conventions | Naming, file structure |
+| `best-practice` | General recommendations | Testing, error handling |
+
+---
+
+## 1. Blazor DbContext Lifecycle
+
+**Category:** `avoid` (Anti-Pattern)
+**Scope:** blazor-azure
+**Source:** Framework standard ([ef-core.md](../standards/backend/database/ef-core.md))
+
+### Problem
+
+Directly injecting `DbContext` in Blazor components causes concurrency errors:
+
+```csharp
+// ❌ WRONG - DbContext is scoped per circuit, not per request
+@inject AppDbContext DbContext
+
+protected override async Task OnInitializedAsync()
+{
+    // This breaks when multiple operations run
+    var users = await DbContext.Users.ToListAsync();
+}
+```
+
+**Error:**
+```
+InvalidOperationException: A second operation was started on this context
+instance before a previous operation completed.
+```
+
+### Correct Approach
+
+Use `IDbContextFactory<T>` for Blazor components:
+
+```csharp
+// ✅ CORRECT
+@inject IDbContextFactory<AppDbContext> DbFactory
+
+protected override async Task OnInitializedAsync()
+{
+    await using var db = await DbFactory.CreateDbContextAsync();
+    var users = await db.Users.ToListAsync();
+}
+```
+
+**Why it works:** Each operation gets its own DbContext instance, avoiding concurrency.
+
+### When to Apply
+
+- All Blazor components that access database
+- Background operations in Blazor (Task.Run, Timer)
+- Long-running circuits with multiple user interactions
+
+---
+
+## 2. Background Job Retry Strategy
+
+**Category:** `best-practice`
+**Scope:** blazor-azure
+**Source:** [hangfire-jobs.md](../standards/backend/integrations/hangfire/hangfire-jobs.md)
+
+### Pattern
+
+Implement exponential backoff with max retry limits:
+
+```csharp
+[AutomaticRetry(Attempts = 5, OnAttemptsExceeded = AttemptsExceededAction.Delete)]
+public async Task ProcessPaymentAsync(string orderId)
+{
+    await using var db = await _dbFactory.CreateDbContextAsync();
+
+    var order = await db.Orders.FindAsync(orderId);
+    if (order == null)
+    {
+        throw new InvalidOperationException($"Order {orderId} not found");
+    }
+
+    try
+    {
+        await _paymentService.ChargeAsync(order.Total);
+        order.Status = "Paid";
+        await db.SaveChangesAsync();
+    }
+    catch (PaymentProviderException ex)
+    {
+        // Hangfire will retry with exponential backoff
+        throw new Exception($"Payment failed: {ex.Message}", ex);
+    }
+}
+```
+
+### Configuration
+
+```csharp
+// Program.cs
+services.AddHangfire(config => config
+    .SetDataCompatibilityLevel(CompatibilityLevel.Version_180)
+    .UseSimpleAssemblyNameTypeSerializer()
+    .UseRecommendedSerializerSettings()
+    .UseInMemoryStorage());
+
+GlobalJobFilters.Filters.Add(new AutomaticRetryAttribute
+{
+    Attempts = 5,
+    DelaysInSeconds = new[] { 10, 30, 60, 300, 900 } // 10s, 30s, 1m, 5m, 15m
+});
+```
+
+### When to Apply
+
+- Payment processing
+- Email sending
+- External API calls
+- File uploads/downloads
+- Any operation that can fail transiently
+
+---
+
+## 3. Azure Bicep Resource Naming Convention
+
+**Category:** `convention`
+**Scope:** blazor-azure
+**Source:** [bicep-patterns.md](../standards/infrastructure/azure/bicep/bicep-patterns.md)
+
+### Pattern
+
+Use consistent naming with environment and region prefixes:
+
+```bicep
+param environment string = 'dev'
+param location string = 'eastus'
+param projectName string = 'myapp'
+
+var resourcePrefix = '${projectName}-${environment}'
+var locationShort = location == 'eastus' ? 'eus' : 'wus'
+
+resource containerApp 'Microsoft.App/containerApps@2024-03-01' = {
+  name: '${resourcePrefix}-app-${locationShort}'
+  location: location
+  // ...
+}
+
+resource sqlServer 'Microsoft.Sql/servers@2023-08-01-preview' = {
+  name: '${resourcePrefix}-sql-${locationShort}'
+  location: location
+  // ...
+}
+
+resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' = {
+  name: '${resourcePrefix}-kv-${locationShort}'
+  location: location
+  // ...
+}
+```
+
+### Naming Pattern
+
+```
+{project}-{env}-{resource}-{region}
+```
+
+Examples:
+- `myapp-prod-app-eus` (Container App in East US)
+- `myapp-dev-sql-wus` (SQL Server in West US)
+- `myapp-staging-kv-eus` (Key Vault in East US)
+
+### Resource Type Abbreviations
+
+| Resource | Abbreviation |
+|----------|--------------|
+| Container App | `app` |
+| SQL Server | `sql` |
+| SQL Database | `db` |
+| Key Vault | `kv` |
+| Storage Account | `st` |
+| App Service Plan | `plan` |
+| Service Bus | `sb` |
+| Container Registry | `acr` |
+
+---
+
+## 4. API Versioning Strategy
+
+**Category:** `best-practice`
+**Scope:** universal
+**Source:** [rest.md](../standards/backend/api/rest.md)
+
+### Pattern
+
+Use URL-based versioning with backward compatibility:
+
+```csharp
+// Controllers/V1/UsersController.cs
+[ApiController]
+[Route("api/v1/[controller]")]
+public class UsersController : ControllerBase
+{
+    [HttpGet]
+    public async Task<ActionResult<List<UserDto>>> GetUsers()
+    {
+        // V1 implementation
+    }
+}
+
+// Controllers/V2/UsersController.cs
+[ApiController]
+[Route("api/v2/[controller]")]
+public class UsersController : ControllerBase
+{
+    [HttpGet]
+    public async Task<ActionResult<List<UserV2Dto>>> GetUsers()
+    {
+        // V2 implementation with pagination
+    }
+}
+```
+
+### Breaking vs Non-Breaking Changes
+
+**Non-Breaking (same version):**
+- Adding new optional fields
+- Adding new endpoints
+- Adding new query parameters (optional)
+
+**Breaking (new version):**
+- Removing fields from response
+- Changing field types
+- Making optional parameters required
+- Changing response structure
+
+### Migration Strategy
+
+1. Deploy V2 alongside V1
+2. Update clients gradually
+3. Monitor V1 usage (add metrics)
+4. Deprecate V1 after 6-12 months
+5. Remove V1 code
+
+---
+
+## 5. EF Core Migration Naming Convention
+
+**Category:** `convention`
+**Scope:** blazor-azure, nextjs-supabase
+**Source:** [migrations.md](../standards/backend/database/migrations.md)
+
+### Pattern
+
+Use descriptive, action-based migration names:
+
+```bash
+# ✅ GOOD
+dotnet ef migrations add AddUserEmailVerification
+dotnet ef migrations add CreateOrdersTable
+dotnet ef migrations add UpdateProductPricingModel
+dotnet ef migrations add RemoveObsoleteUserFields
+
+# ❌ BAD
+dotnet ef migrations add Migration1
+dotnet ef migrations add Changes
+dotnet ef migrations add Update
+dotnet ef migrations add Fix
+```
+
+### Naming Convention
+
+```
+{Action}{EntityOrFeature}{OptionalDetail}
+```
+
+**Actions:**
+- `Add` - New columns/tables
+- `Create` - New tables/schemas
+- `Update` - Modify existing structure
+- `Remove` - Delete columns/tables
+- `Rename` - Rename entities
+- `Refactor` - Structural changes
+
+**Examples:**
+- `AddUserProfilePicture`
+- `CreateProductCategoriesTable`
+- `UpdateOrderStatusEnum`
+- `RemoveDeprecatedPaymentMethods`
+- `RenameCustomerToUser`
+- `RefactorOrderItemsRelationship`
+
+---
+
+## 6. Blazor DI Registration Order
+
+**Category:** `best-practice`
+**Scope:** blazor-azure
+**Source:** [program-cs-checklist.md](../standards/backend/dotnet/program-cs-checklist.md)
+
+### Pattern
+
+Register services in strict order to avoid dependency resolution errors:
+
+```csharp
+// Program.cs - CORRECT ORDER
+
+var builder = WebApplication.CreateBuilder(args);
+
+// 1. Configuration (first - others depend on this)
+builder.Configuration.AddJsonFile("appsettings.json");
+builder.Configuration.AddEnvironmentVariables();
+
+// 2. Infrastructure (database, storage, external APIs)
+builder.Services.AddDbContextFactory<AppDbContext>(options =>
+    options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection")));
+
+// 3. Application Services (depend on infrastructure)
+builder.Services.AddScoped<IUserService, UserService>();
+builder.Services.AddScoped<IOrderService, OrderService>();
+
+// 4. Framework Services (depend on application services)
+builder.Services.AddRazorComponents()
+    .AddInteractiveServerComponents();
+
+// 5. Third-Party Libraries (may have cross-dependencies)
+builder.Services.AddFluentUIComponents();
+
+var app = builder.Build();
+
+// Middleware order also matters!
+app.UseStaticFiles();
+app.UseRouting();
+app.UseAuthentication();
+app.UseAuthorization();
+app.MapRazorComponents<App>()
+   .AddInteractiveServerRenderMode();
+
+app.Run();
+```
+
+### Why Order Matters
+
+- Services registered later can depend on services registered earlier
+- Middleware executes in the order added (request pipeline)
+- Configuration must be loaded before services that read it
+
+### Common Errors
+
+```csharp
+// ❌ WRONG - Service depends on DbContextFactory not yet registered
+builder.Services.AddScoped<IUserService, UserService>();
+builder.Services.AddDbContextFactory<AppDbContext>(...); // TOO LATE!
+
+// ✅ CORRECT - DbContextFactory first
+builder.Services.AddDbContextFactory<AppDbContext>(...);
+builder.Services.AddScoped<IUserService, UserService>(); // Now UserService can inject it
+```
+
+---
+
+## 7. Component Parameter Validation
+
+**Category:** `best-practice`
+**Scope:** blazor-azure
+**Source:** [lifecycle.md](../standards/frontend/blazor/lifecycle.md)
+
+### Pattern
+
+Validate parameters in `OnParametersSet`:
+
+```csharp
+@code {
+    [Parameter, EditorRequired]
+    public string UserId { get; set; } = default!;
+
+    [Parameter]
+    public int PageSize { get; set; } = 10;
+
+    protected override void OnParametersSet()
+    {
+        if (string.IsNullOrWhiteSpace(UserId))
+        {
+            throw new ArgumentException("UserId is required", nameof(UserId));
+        }
+
+        if (PageSize <= 0 || PageSize > 100)
+        {
+            throw new ArgumentOutOfRangeException(nameof(PageSize),
+                "PageSize must be between 1 and 100");
+        }
+    }
+
+    protected override async Task OnInitializedAsync()
+    {
+        // Parameters are already validated here
+        await LoadUserDataAsync(UserId);
+    }
+}
+```
+
+### Why OnParametersSet?
+
+- Runs **before** `OnInitializedAsync`
+- Runs **every time** parameters change (not just once)
+- Catches invalid state early
+
+### When to Apply
+
+- Required parameters (validate not null/empty)
+- Numeric ranges (min/max validation)
+- Enum values (validate within allowed set)
+- Cross-parameter validation (e.g., StartDate < EndDate)
+
+---
+
+## 8. Async Method Naming Convention
+
+**Category:** `convention`
+**Scope:** universal
+**Source:** [async.md](../standards/backend/dotnet/async.md)
+
+### Pattern
+
+All async methods must end with `Async` suffix:
+
+```csharp
+// ✅ CORRECT
+public async Task<User> GetUserAsync(string userId) { }
+public async Task SaveChangesAsync() { }
+public async Task<bool> ValidateEmailAsync(string email) { }
+
+// ❌ WRONG
+public async Task<User> GetUser(string userId) { }  // Missing Async
+public async Task SaveChanges() { }                  // Missing Async
+public async Task<bool> ValidateEmail(string email) { } // Missing Async
+```
+
+### Exception: Event Handlers
+
+```csharp
+// ✅ OK - Event handlers don't need Async suffix
+private async Task HandleSubmit()
+{
+    await SaveFormAsync();
+}
+
+private async Task OnButtonClick()
+{
+    await ProcessDataAsync();
+}
+```
+
+### Benefits
+
+- Clear indication that method is asynchronous
+- Avoids confusion with synchronous counterparts
+- IDE tooling can detect missing awaits
+
+---
+
+## 9. Error Handling Strategy
+
+**Category:** `best-practice`
+**Scope:** universal
+**Source:** [coding.md](../standards/core/coding.md)
+
+### Pattern
+
+Use layered error handling with specific exception types:
+
+```csharp
+// Domain Layer - Business Exceptions
+public class InsufficientBalanceException : Exception
+{
+    public decimal RequiredAmount { get; }
+    public decimal AvailableBalance { get; }
+
+    public InsufficientBalanceException(decimal required, decimal available)
+        : base($"Insufficient balance. Required: {required}, Available: {available}")
+    {
+        RequiredAmount = required;
+        AvailableBalance = available;
+    }
+}
+
+// Service Layer - Catch and Transform
+public class PaymentService
+{
+    public async Task<PaymentResult> ProcessPaymentAsync(Order order)
+    {
+        try
+        {
+            await _paymentGateway.ChargeAsync(order.Total);
+            return PaymentResult.Success();
+        }
+        catch (InsufficientBalanceException ex)
+        {
+            return PaymentResult.Failed($"Insufficient funds: {ex.Message}");
+        }
+        catch (PaymentGatewayException ex)
+        {
+            _logger.LogError(ex, "Payment gateway error for order {OrderId}", order.Id);
+            return PaymentResult.Failed("Payment provider error. Please try again.");
+        }
+        catch (Exception ex)
+        {
+            _logger.LogCritical(ex, "Unexpected error processing payment for order {OrderId}", order.Id);
+            throw; // Re-throw unexpected errors
+        }
+    }
+}
+
+// Controller/Component Layer - Present to User
+try
+{
+    var result = await _paymentService.ProcessPaymentAsync(order);
+
+    if (!result.IsSuccess)
+    {
+        // Show user-friendly error
+        ErrorMessage = result.ErrorMessage;
+    }
+}
+catch (Exception ex)
+{
+    // Unexpected errors - show generic message
+    ErrorMessage = "An unexpected error occurred. Our team has been notified.";
+    _logger.LogError(ex, "Unhandled error in payment UI");
+}
+```
+
+### Layers of Error Handling
+
+1. **Domain:** Throw specific business exceptions
+2. **Service:** Catch, log, and transform to result objects
+3. **UI/API:** Present user-friendly messages
+4. **Global:** Catch-all for unhandled exceptions
+
+---
+
+## 10. Bicep Output Exports Convention
+
+**Category:** `convention`
+**Scope:** blazor-azure
+**Source:** [bicep-patterns.md](../standards/infrastructure/azure/bicep/bicep-patterns.md)
+
+### Pattern
+
+Export resource IDs and connection info for dependent resources:
+
+```bicep
+// modules/sql-database.bicep
+output sqlServerFqdn string = sqlServer.properties.fullyQualifiedDomainName
+output databaseName string = sqlDatabase.name
+output connectionString string = 'Server=${sqlServer.properties.fullyQualifiedDomainName};Database=${sqlDatabase.name};'
+
+// modules/container-app.bicep
+output containerAppUrl string = containerApp.properties.configuration.ingress.fqdn
+output containerAppId string = containerApp.id
+
+// main.bicep
+module sqlDatabase 'modules/sql-database.bicep' = {
+  name: 'sqlDatabaseDeployment'
+  params: {
+    location: location
+    serverName: sqlServerName
+  }
+}
+
+module containerApp 'modules/container-app.bicep' = {
+  name: 'containerAppDeployment'
+  params: {
+    location: location
+    databaseConnectionString: sqlDatabase.outputs.connectionString // USE OUTPUT
+  }
+}
+
+// Export to deployment output
+output appUrl string = containerApp.outputs.containerAppUrl
+output databaseServer string = sqlDatabase.outputs.sqlServerFqdn
+```
+
+### What to Export
+
+- Resource FQDNs (SQL Server, Key Vault, Storage)
+- Connection strings (with placeholders for secrets)
+- Resource IDs (for RBAC assignments)
+- URLs/Endpoints (App URLs, API endpoints)
+- Names (for reference in other modules)
+
+### What NOT to Export
+
+- Secrets/passwords (use Key Vault references)
+- Internal IPs (expose only public endpoints)
+- Temporary values (deployment-specific data)
+
+---
+
+## 11. Azure Key Vault Secrets Management
+
+**Category:** `security`
+**Scope:** blazor-azure
+**Source:** [azure.md](../standards/infrastructure/azure/azure.md)
+
+### Pattern
+
+Never hardcode secrets - use Key Vault with Managed Identity:
+
+```csharp
+// ❌ WRONG - Secrets in appsettings.json
+{
+  "ConnectionStrings": {
+    "DefaultConnection": "Server=myserver.database.windows.net;Database=mydb;User=admin;Password=MyPassword123!;"
+  },
+  "Stripe": {
+    "SecretKey": "sk_live_51ABC123..."
+  }
+}
+
+// ✅ CORRECT - Reference Key Vault secrets
+{
+  "KeyVaultUri": "https://myapp-prod-kv-eus.vault.azure.net/",
+  "ConnectionStrings": {
+    "DefaultConnection": "@Microsoft.KeyVault(SecretUri=https://myapp-prod-kv-eus.vault.azure.net/secrets/SqlConnectionString/)"
+  },
+  "Stripe": {
+    "SecretKey": "@Microsoft.KeyVault(SecretUri=https://myapp-prod-kv-eus.vault.azure.net/secrets/StripeSecretKey/)"
+  }
+}
+```
+
+### Program.cs Setup
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+
+// Load Key Vault secrets using Managed Identity
+var keyVaultUri = builder.Configuration["KeyVaultUri"];
+if (!string.IsNullOrEmpty(keyVaultUri))
+{
+    builder.Configuration.AddAzureKeyVault(
+        new Uri(keyVaultUri),
+        new DefaultAzureCredential());
+}
+
+// Services can now access secrets via IConfiguration
+builder.Services.AddScoped<IPaymentService>(sp =>
+{
+    var config = sp.GetRequiredService<IConfiguration>();
+    var stripeKey = config["Stripe:SecretKey"]; // Loaded from Key Vault
+    return new StripePaymentService(stripeKey);
+});
+```
+
+### Bicep - Grant Access
+
+```bicep
+resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' = {
+  name: keyVaultName
+  properties: {
+    tenantId: subscription().tenantId
+    sku: { family: 'A', name: 'standard' }
+    accessPolicies: []
+    enableRbacAuthorization: true // Use RBAC instead of access policies
+  }
+}
+
+// Grant Container App access to secrets
+resource keyVaultSecretUser 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
+  scope: keyVault
+  name: guid(keyVault.id, containerApp.id, 'Key Vault Secrets User')
+  properties: {
+    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4633458b-17de-408a-b874-0445c86b69e6')
+    principalId: containerApp.identity.principalId
+    principalType: 'ServicePrincipal'
+  }
+}
+```
+
+### Local Development
+
+```csharp
+// Use Azure CLI or Visual Studio authentication locally
+// No need for connection strings in local appsettings.json
+
+// Developers run: az login
+// DefaultAzureCredential will use their identity to access Key Vault
+```
+
+### When to Apply
+
+- **ALWAYS** for production secrets
+- Database connection strings
+- API keys (Stripe, SendGrid, etc.)
+- Encryption keys
+- OAuth client secrets
+- Storage account keys
+
+---
+
+## Pattern Statistics
+
+| Category | Count |
+|----------|-------|
+| success | 0 |
+| avoid | 1 |
+| optimization | 0 |
+| security | 1 |
+| convention | 4 |
+| best-practice | 5 |
+
+**Total Patterns:** 11
+
+---
+
+## How to Search
+
+```bash
+# By keyword
+npx morph-spec search-patterns "blazor"
+npx morph-spec search-patterns "async"
+npx morph-spec search-patterns "bicep"
+
+# By category
+npx morph-spec search-patterns --category=avoid
+npx morph-spec search-patterns --category=security
+
+# By scope
+npx morph-spec search-patterns --scope=blazor-azure
+npx morph-spec search-patterns --scope=universal
+```
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*