@polymorphism-tech/morph-spec 3.1.0 → 4.2.0

package/stacks/blazor-azure/.morph/standards/azure.md

@@ -1,605 +0,0 @@
-# Padrões Azure - MORPH Framework
-
-## 💰 Filosofia de Custos
-
-> **Free tier primeiro. Aprovação explícita para upgrade.**
-
-| Nível | Limite | Requer |
-|-------|--------|--------|
-| Sem aprovação | Free tier apenas | Nada |
-| Com aprovação | Até $10/mês | Confirmação |
-| Acima de $10 | Justificativa detalhada | ADR |
-
----
-
-## 🌐 Hosting: App Service vs Container Apps
-
-### Matriz de Decisão
-
-| Critério | App Service (Free F1) | Container Apps (Consumption) |
-|----------|----------------------|------------------------------|
-| **Custo** | ✅ $0/mês | ⚠️ ~$5/mês |
-| **RAM** | 1GB | Configurável (0.5Gi min) |
-| **Storage** | 1GB | Ephemeral |
-| **CPU** | ⚠️ 60 min/dia | ✅ Ilimitado |
-| **Disponibilidade** | ⚠️ Sleep após 20min | ✅ Scale-to-zero sem sleep |
-| **SSL Customizado** | ❌ Não (apenas *.azurewebsites.net) | ✅ Sim, gratuito |
-| **Scale Out** | ❌ Não | ✅ Auto-scaling |
-| **Blazor Server** | ✅ Suporte nativo | ✅ Via Docker |
-| **Deploy** | ✅ Direto (ZIP, Git) | ⚠️ Requer container |
-
-### Quando Usar App Service Free
-
-**✅ Cenários Ideais:**
-- Protótipos e MVPs de baixo tráfego
-- Aplicações de uso interno (horário comercial)
-- Demos e POCs
-- Apps que toleram cold start (20 min sleep)
-- Orçamento zero absoluto
-
-**❌ Não Usar Quando:**
-- Necessita estar sempre disponível (24/7)
-- Tráfego imprevisível ou spikes
-- Mais de 60 min de CPU/dia
-- Precisa de SSL customizado
-- Requer auto-scaling
-
-### Quando Usar Container Apps
-
-**✅ Cenários Ideais:**
-- Produção com disponibilidade 24/7
-- Auto-scaling baseado em demanda
-- SSL customizado necessário
-- Arquitetura microserviços
-- Background jobs com Hangfire (minReplicas: 1)
-- Apps que precisam estar sempre "quentes"
-
-**❌ Não Usar Quando:**
-- Orçamento zero obrigatório
-- Tráfego extremamente baixo (< 100 req/dia)
-- MVP simples sem requisitos de SLA
-
-### Estratégia Híbrida
-
-```
-Dev/Staging:    App Service Free F1
-Production:     Container Apps Consumption
-```
-
-**Benefícios:**
-- 💰 Economia em ambientes não críticos
-- 🚀 Performance garantida em produção
-- 🔄 Fácil migração (mesma stack .NET)
-
----
-
-## 📋 Stack Padrão Aprovado
-
-| Recurso | Tier | Custo | Quando Usar |
-|---------|------|-------|-------------|
-| **App Service** | Free F1 | $0 | MVP, protótipos, dev/staging |
-| **Container Apps** | Consumption | ~$0-5/mês | Produção, auto-scaling |
-| **Azure SQL** | Free 32GB | $0 | Database |
-| **ACR** | Basic | ~$5/mês | Container registry (apenas com CA) |
-| **App Insights** | Free 5GB | $0 | Logs e métricas |
-| **Azure OpenAI** | gpt-4o-mini | ~$2-10/mês | Análises AI |
-
-**Custo total típico:**
-- **App Service Stack:** $0-2/mês (sem ACR)
-- **Container Apps Stack:** $7-20/mês (com ACR)
-
-### ⚠️ Requer Aprovação
-
-| Recurso | Custo | Alternativa Free |
-|---------|-------|------------------|
-| Azure Functions | ~$0-5/mês | Hangfire |
-| Service Bus | ~$10/mês | Queue em SQL |
-| Cosmos DB | ~$25/mês | Azure SQL JSON |
-| Redis Cache | ~$15/mês | In-memory |
-
----
-
-## 🌐 App Service Free Tier
-
-### Configuração Obrigatória
-```bicep
-resource appService 'Microsoft.Web/sites@2022-03-01' = {
-  name: 'app-${projectName}-${environment}'
-  location: location
-  properties: {
-    serverFarmId: appServicePlan.id
-    httpsOnly: true
-    siteConfig: {
-      netFrameworkVersion: 'v8.0'
-      alwaysOn: false        # ⚠️ OBRIGATÓRIO no Free tier
-      minTlsVersion: '1.2'
-    }
-  }
-}
-
-resource appServicePlan 'Microsoft.Web/serverfarms@2022-03-01' = {
-  name: 'plan-${projectName}-${environment}'
-  location: location
-  sku: {
-    name: 'F1'               # Free tier
-    tier: 'Free'
-  }
-}
-```
-
-### Limitações Importantes
-- ⚠️ **CPU**: Apenas 60 minutos/dia (não contínuos)
-- ⚠️ **Sleep**: App dorme após 20 minutos de inatividade
-- ⚠️ **SSL**: Apenas `*.azurewebsites.net` (sem domínio customizado)
-- ⚠️ **Escala**: Sem scale-out (apenas 1 instância)
-- ✅ **Memória**: 1GB RAM
-- ✅ **Storage**: 1GB disco
-
-### Deploy
-```bash
-# Via Azure CLI
-az webapp up --name app-myproject-dev --runtime "DOTNET:8.0"
-
-# Via GitHub Actions
-- task: AzureWebApp@1
-  inputs:
-    azureSubscription: 'Azure-Connection'
-    appName: 'app-myproject-dev'
-    package: '$(Build.ArtifactStagingDirectory)/**/*.zip'
-```
-
-### Quando Migrar para Container Apps
-Se você observar:
-- 🔴 CPU quota esgotada frequentemente
-- 🔴 Cold starts afetando UX
-- 🔴 Necessidade de SSL customizado
-- 🔴 Tráfego crescendo (>1000 req/dia)
-
-**→ Considere migrar para Container Apps Consumption**
-
----
-
-## 🐳 Container Apps
-
-### Configuração Obrigatória
-```yaml
-properties:
-  template:
-    scale:
-      minReplicas: 0      # ⚠️ OBRIGATÓRIO: scale-to-zero
-      maxReplicas: 2
-    containers:
-      - name: app
-        resources:
-          cpu: 0.25       # Mínimo
-          memory: 0.5Gi   # Mínimo
-```
-
-### Scale-to-Zero
-- ✅ **OBRIGATÓRIO** para dev/staging
-- ⚠️ Em prod com Hangfire: `minReplicas: 1`
-- 💰 Economia: ~80% vs always-on
-
----
-
-## 🗄️ Azure SQL Free Tier
-
-```
-- 32 GB storage
-- 100,000 vCore seconds/month
-- Serverless compute
-- Auto-pause after 1 hour idle
-```
-
-### Práticas
-- ✅ Usar Managed Identity
-- ✅ TDE habilitado (default)
-- ❌ Não criar índices em excesso
-
----
-
-## 🤖 Azure OpenAI
-
-### Modelo Padrão: gpt-4o-mini
-
-| Modelo | Custo Input | Custo Output | Usar |
-|--------|-------------|--------------|------|
-| **gpt-4o-mini** | $0.15/1M | $0.60/1M | ✅ PADRÃO |
-| gpt-4o | $2.50/1M | $10/1M | Com aprovação |
-| gpt-4 | $30/1M | $60/1M | ❌ NUNCA |
-
-### Otimização
-```csharp
-var settings = new OpenAIPromptExecutionSettings
-{
-    MaxTokens = 500,  // Limitar resposta
-    Temperature = 0.3 // Mais determinístico
-};
-```
-
----
-
-## 🔐 Segurança
-
-### Managed Identity (Preferido)
-```csharp
-// Para Azure SQL
-"Authentication=Active Directory Managed Identity;"
-
-// Para Azure OpenAI
-var credential = new DefaultAzureCredential();
-```
-
-### Key Vault
-Usar apenas para:
-- Secrets de serviços externos
-- API keys de terceiros
-
----
-
-## 📛 Naming Conventions
-
-```
-{tipo}-{projeto}-{ambiente}
-
-Exemplos:
-- rg-myproject-dev          # Resource Group
-- app-myproject-dev         # App Service
-- plan-myproject-dev        # App Service Plan
-- ca-myproject-dev          # Container App
-- sql-myproject-dev         # SQL Server
-- sqldb-myproject-dev       # SQL Database
-- acr-myproject             # Container Registry
-- appi-myproject-dev        # App Insights
-- kv-myproject-dev          # Key Vault
-```
-
-| Ambiente | Sufixo | Características |
-|----------|--------|-----------------|
-| Development | -dev | Scale-to-zero, free tier |
-| Staging | -stg | Scale-to-zero, free tier |
-| Production | -prod | Min 1 replica |
-
----
-
-## 🚀 Azure DevOps Pipelines
-
-### Estratégia de Ambientes
-
-**2 ambientes:**
-- **Staging**: Desenvolvimento + QA (branch: `staging`)
-  - Developers rodam projeto LOCAL
-  - Acessam recursos REMOTOS staging
-  - Deploy automático via pipeline
-
-- **Produção**: Ambiente crítico (branch: `main`/`master`)
-  - Deploy via pipeline com aprovação manual
-  - Always-on, monitoramento 24/7
-
-### Estrutura de Pipelines
-
-```
-.azure/pipelines/
-├── staging-pipeline.yml      # Branch: staging
-├── prod-pipeline.yml         # Branch: main/master
-├── pipeline-variables.yml    # Variáveis compartilhadas
-└── templates/
-    ├── build-dotnet.yml
-    ├── deploy-container-app.yml
-    └── infra-deploy.yml
-```
-
-### Pipeline Staging
-
-```yaml
-# staging-pipeline.yml
-trigger:
-  branches:
-    include: [staging]
-
-variables:
-  - template: pipeline-variables.yml
-  - name: environment
-    value: 'staging'
-  - name: hostingType
-    value: 'containerapp'
-
-stages:
-  - stage: Build
-  - stage: DeployInfra
-  - stage: BuildContainer
-  - stage: DeployApp
-    jobs:
-      - deployment: DeployAppJob
-        environment: 'staging'  # No approval
-```
-
-### Pipeline Production
-
-```yaml
-# prod-pipeline.yml
-trigger:
-  branches:
-    include: [main, master]
-
-variables:
-  - template: pipeline-variables.yml
-  - name: environment
-    value: 'prod'
-  - name: hostingType
-    value: 'containerapp'
-
-stages:
-  - stage: Build
-  - stage: SecurityScan
-  - stage: DeployInfra
-  - stage: BuildContainer
-  - stage: DeployApp
-    jobs:
-      - deployment: DeployAppJob
-        environment: 'production'  # Approval required
-```
-
-### Workload Identity (Sem Secrets)
-
-Ao invés de Service Principals com secrets, use Workload Identity Federation:
-
-```bash
-# Criar App Registration com Federated Credential
-az ad app create --display-name "myapp-prod-pipeline"
-
-# Configurar federated credential
-az ad app federated-credential create \
-  --id <APP_ID> \
-  --parameters @federated-credential.json
-```
-
-**Vantagens:**
-- ✅ Sem secrets para gerenciar
-- ✅ Rotação automática de tokens
-- ✅ Mais seguro
-- ✅ Auditoria melhorada
-
-**Documentação completa:** `.azure/docs/azure-devops-setup.md`
-
----
-
-## ✅ Checklist de Deploy
-
-### Antes
-- [ ] Testes passando
-- [ ] Migrations aplicadas
-- [ ] Secrets no Key Vault
-- [ ] Managed Identity configurada
-
-### Após
-- [ ] Health check OK
-- [ ] Logs no App Insights
-- [ ] Funcionalidade testada
-- [ ] Custos verificados
-
----
-
-## ⚠️ Package Version Conflicts
-
-### Azure.Identity Downgrade Error
-
-**Error:**
-```
-NU1605: Detected package downgrade: Azure.Identity from 1.14.2 to 1.13.2
-```
-
-**Cause:** `Microsoft.Data.SqlClient` or other packages require a newer version.
-
-**Solution:** Always specify `Azure.Identity` explicitly in your `.csproj`:
-
-```xml
-<!-- Prevent version conflicts -->
-<PackageReference Include="Azure.Identity" Version="1.14.2" />
-```
-
-**Why this happens:**
-- Transitive dependencies pull different versions
-- NuGet picks the lowest common version
-- This causes runtime failures with newer APIs
-
----
-
-## 🔑 Key Vault Configuration
-
-### Critical Rule
-
-**NEVER condition Key Vault loading on environment. Load whenever URI is configured.**
-
-**❌ WRONG:**
-```csharp
-// This breaks DI in development!
-if (!string.IsNullOrEmpty(keyVaultUri) && !builder.Environment.IsDevelopment())
-{
-    builder.Configuration.AddAzureKeyVault(...);
-}
-```
-
-**✅ CORRECT:**
-```csharp
-// Load Key Vault in ALL environments where URI exists
-if (!string.IsNullOrEmpty(keyVaultUri))
-{
-    builder.Configuration.AddAzureKeyVault(
-        new Uri(keyVaultUri),
-        new DefaultAzureCredential());
-}
-```
-
-**Why:**
-- Services registered via DI may depend on Key Vault secrets
-- `IBlobStorageService`, `IPaymentService`, etc. fail if secrets not loaded
-- Development can use Azure Key Vault with developer credentials
-- Or use `appsettings.Development.json` to override secrets locally
-
----
-
-## 🚀 DefaultAzureCredential Optimization
-
-### Problem
-
-`DefaultAzureCredential` is **slow in containers** because it tries multiple authentication methods sequentially (environment, workload identity, managed identity, Visual Studio, CLI, etc.).
-
-**Symptom:** Startup takes 30+ seconds, or times out.
-
-### Solution: Disable Unused Credential Types
-
-```csharp
-// For Container Apps / AKS with Managed Identity ONLY
-var credential = new DefaultAzureCredential(new DefaultAzureCredentialOptions
-{
-    // Disable all except Managed Identity
-    ExcludeEnvironmentCredential = true,
-    ExcludeWorkloadIdentityCredential = true,
-    ExcludeSharedTokenCacheCredential = true,
-    ExcludeVisualStudioCredential = true,
-    ExcludeVisualStudioCodeCredential = true,
-    ExcludeAzureCliCredential = true,
-    ExcludeAzurePowerShellCredential = true,
-    ExcludeAzureDeveloperCliCredential = true,
-    ExcludeInteractiveBrowserCredential = true,
-    ExcludeManagedIdentityCredential = false  // Keep this one!
-});
-```
-
-### Environment-Specific Configuration
-
-```csharp
-// Program.cs - Smart credential selection
-DefaultAzureCredential CreateCredential(IHostEnvironment env)
-{
-    if (env.IsDevelopment())
-    {
-        // Development: Allow CLI, VS, VS Code
-        return new DefaultAzureCredential();
-    }
-
-    // Production: Only Managed Identity (fast!)
-    return new DefaultAzureCredential(new DefaultAzureCredentialOptions
-    {
-        ExcludeEnvironmentCredential = true,
-        ExcludeWorkloadIdentityCredential = true,
-        ExcludeSharedTokenCacheCredential = true,
-        ExcludeVisualStudioCredential = true,
-        ExcludeVisualStudioCodeCredential = true,
-        ExcludeAzureCliCredential = true,
-        ExcludeAzurePowerShellCredential = true,
-        ExcludeAzureDeveloperCliCredential = true,
-        ExcludeInteractiveBrowserCredential = true,
-        ExcludeManagedIdentityCredential = false
-    });
-}
-```
-
----
-
-## 🐳 Container App Deployment Issues
-
-### Problem: Container App Not Updating
-
-After pushing a new image, Container App continues running the old version.
-
-**Cause:** Same image digest doesn't trigger a new revision.
-
-**Solution:** Force a new revision with a timestamp:
-
-```bash
-# Force new revision with environment variable
-az containerapp update \
-  --name ca-myapp-prod \
-  --resource-group rg-myapp-prod \
-  --set-env-vars "DEPLOY_TIMESTAMP=$(date +%s)"
-```
-
-### Complete Deploy Script
-
-```bash
-#!/bin/bash
-# deploy-container-app.sh
-
-APP_NAME="ca-myapp-prod"
-RG_NAME="rg-myapp-prod"
-ACR_NAME="acrmyapp"
-IMAGE_TAG="latest"
-
-# 1. Build and push
-docker build --no-cache -t $ACR_NAME.azurecr.io/myapp:$IMAGE_TAG .
-docker push $ACR_NAME.azurecr.io/myapp:$IMAGE_TAG
-
-# 2. Update with timestamp (forces new revision)
-az containerapp update \
-  --name $APP_NAME \
-  --resource-group $RG_NAME \
-  --set-env-vars "DEPLOY_TIMESTAMP=$(date +%s)"
-
-# 3. Verify
-az containerapp show \
-  --name $APP_NAME \
-  --resource-group $RG_NAME \
-  --query "properties.runningStatus"
-
-# 4. Check logs
-az containerapp logs show \
-  --name $APP_NAME \
-  --resource-group $RG_NAME \
-  --follow
-```
-
----
-
-## 🔧 Troubleshooting Azure
-
-Quick reference for common Azure issues:
-
-### Key Vault access denied
-→ Verify RBAC role assignment (Key Vault Secrets User)
-→ Check Managed Identity is enabled on the resource
-→ Verify Key Vault firewall allows the resource's IP/VNet
-
-### Container App 404
-→ Check ingress configuration (external/internal)
-→ Verify health probe endpoint exists and returns 200
-→ Check container is actually running (logs)
-
-### Managed Identity not working
-→ Verify identity is assigned to the resource
-→ Check RBAC scope (subscription vs resource group vs resource)
-→ Allow 5-10 minutes for propagation after assignment
-
-### blazor.web.js 404 (.NET 10)
-→ Add to `.csproj`:
-```xml
-<RequiresAspNetWebAssets>true</RequiresAspNetWebAssets>
-```
-
-### DefaultAzureCredential slow/timeout
-→ Disable unused credential types (see section above)
-→ Check network connectivity to Azure AD
-
-### Container App not updating
-→ Use `DEPLOY_TIMESTAMP` to force new revision (see section above)
-→ Verify image was actually pushed to ACR
-→ Check ACR webhook/event subscription
-
-### EF Core migrations not applied
-→ Add auto-migration to startup (dev/staging only)
-→ Or run migration in pipeline before deploy
-
----
-
-## 📚 Lessons Learned - Deploy
-
-Key insights from production deployments:
-
-1. **`docker build --no-cache`** is essential when debugging image issues
-2. **`DEPLOY_TIMESTAMP`** forces new revision in Container Apps
-3. **.NET 10 Preview** has undocumented breaking changes - check GitHub Issues
-4. **GitHub Issues** are more effective than official docs for edge cases
-5. **Auto-migration** simplifies deploy but has risks in production
-6. **Key Vault in dev** needs developer credentials, not just prod Managed Identity
-7. **Document while solving** - saves time later (hence this document!)