@polymorphism-tech/morph-spec 2.4.0 → 3.0.0

package/content/.azure/README.md

@@ -1,293 +1,293 @@
-# MORPH-SPEC - Azure DevOps Pipelines
-
-> **CI/CD para One-Person Business com Workload Identity Federation (sem secrets)**
-
----
-
-## 🚀 Quick Start
-
-### 1. Configurar Workload Identity (10 min)
-
-```bash
-# Ver guia completo em: docs/azure-devops-setup.md
-
-# Criar App Registrations
-az ad app create --display-name "myapp-staging-pipeline"
-az ad app create --display-name "myapp-prod-pipeline"
-
-# Configurar federated credentials
-# (Ver guia detalhado)
-```
-
-### 2. Importar Pipelines no Azure DevOps
-
-1. **Pipelines** → **New pipeline**
-2. **Azure Repos Git** → Selecione repo
-3. **Existing Azure Pipelines YAML file**
-4. Selecione:
-   - `.azure/pipelines/staging-pipeline.yml`
-   - `.azure/pipelines/prod-pipeline.yml`
-
-### 3. Configurar Variáveis
-
-Para cada pipeline, adicione:
-```
-ACR_NAME: <seu-acr-name>
-APP_NAME: <seu-app-name>
-SUBSCRIPTION_ID: <subscription-id>
-```
-
-### 4. Criar Environments
-
-1. **Pipelines** → **Environments** → **New environment**
-2. Criar:
-   - `staging` (sem aprovação - deploy rápido)
-   - `production` (aprovação obrigatória)
-
-### 5. Testar!
-
-```bash
-# Trigger staging pipeline
-git checkout staging
-git commit -m "test" --allow-empty
-git push origin staging
-
-# Trigger prod pipeline
-git checkout main
-git commit -m "test" --allow-empty
-git push origin main
-# ⏸️ Aprovar manualmente no Azure DevOps
-```
-
----
-
-## 📁 Estrutura
-
-```
-.azure/
-├── README.md                           # Este arquivo
-├── docs/
-│   ├── azure-devops-setup.md          # Guia completo de setup
-│   ├── local-development.md           # Como rodar projeto local
-│   └── branch-strategy.md             # Estratégia de branches
-└── pipelines/
-    ├── staging-pipeline.yml           # Pipeline staging (branch: staging)
-    ├── prod-pipeline.yml              # Pipeline prod (branch: main/master)
-    ├── pipeline-variables.yml         # Variáveis compartilhadas
-    └── templates/
-        ├── build-dotnet.yml           # Template: Build .NET
-        ├── deploy-app-service.yml     # Template: Deploy App Service
-        ├── deploy-container-app.yml   # Template: Deploy Container Apps
-        └── infra-deploy.yml           # Template: Deploy Bicep
-```
-
----
-
-## 🔄 Pipelines
-
-### Staging Pipeline (`staging-pipeline.yml`)
-
-**Hosting:** Container Apps com scale-to-zero (~$5-10/mês)
-
-**Trigger:** Push em `staging` branch
-
-**Stages:**
-1. ✅ Build & Test
-2. ✅ Deploy Infrastructure (Bicep)
-3. ✅ Build Container Image
-4. ✅ Push to ACR
-5. ✅ Deploy Container App
-6. ✅ Integration Tests
-
-**Aprovação:** Nenhuma (deploy automático)
-
-**Uso:** QA, testes de integração
-
----
-
-### Prod Pipeline (`prod-pipeline.yml`)
-
-**Hosting:** Container Apps always-on (~$10-20/mês)
-
-**Trigger:** Push em `main` ou `master` branch
-
-**Stages:**
-1. ✅ Build & Test
-2. ✅ Security Scan
-3. ✅ Deploy Infrastructure (Bicep)  ← **Approval Required**
-4. ✅ Build Container Image
-5. ✅ Security Scan (Image)
-6. ✅ Deploy to Production  ← **Approval Required**
-7. ✅ Smoke Tests (Critical)
-8. ✅ Monitor & Report
-
-**Aprovação:** OBRIGATÓRIA (manual approval gate)
-
-**Uso:** Produção, ambiente crítico
-
----
-
-## 🌐 Desenvolvimento Local
-
-**Developers NÃO têm ambiente próprio.** Ao invés disso:
-
-- ✅ Rodam projeto **LOCAL** (Visual Studio/Rider/VS Code)
-- ✅ Acessam recursos **REMOTOS** staging (SQL, Storage, Key Vault)
-- ✅ Testam localmente antes de commitar
-
-**Ver guia completo:** [`docs/local-development.md`](docs/local-development.md)
-
----
-
-## 🎯 Fluxo Completo
-
-### Desenvolvimento Diário
-
-```bash
-# 1. Criar feature branch
-git checkout staging
-git pull origin staging
-git checkout -b feature/nova-funcionalidade
-
-# 2. Desenvolver LOCAL
-dotnet run  # Conecta em recursos staging
-
-# 3. Commitar
-git add .
-git commit -m "feat: adiciona nova funcionalidade"
-git push origin feature/nova-funcionalidade
-
-# 4. Criar PR para staging
-# Azure DevOps → Repos → Pull Requests → New
-# Source: feature/nova-funcionalidade → Target: staging
-# Self-approve e merge
-
-# 5. Staging pipeline triggado automaticamente
-# ✅ Deploy para staging
-```
-
-### Release para Produção
-
-```bash
-# 1. Criar PR staging → main
-# Azure DevOps → Repos → Pull Requests → New
-# Source: staging → Target: main
-
-# 2. Self-review e merge
-
-# 3. Prod pipeline triggado
-# ⏸️ Approval gate aparece
-# Revisar deployment summary
-# Aprovar manualmente
-
-# 4. Deploy para produção
-# ✅ Aplicação em produção
-```
-
----
-
-## 📊 Comparativo de Ambientes
-
-| Aspecto | Staging | Prod |
-|---------|---------|------|
-| **Hosting** | Container Apps | Container Apps |
-| **Custo** | $5-10/mês | $10-20/mês |
-| **Disponibilidade** | Scale-to-zero | Always-on (min 1) |
-| **SSL** | Custom domain OK | Custom domain OK |
-| **Auto-scaling** | ✅ Sim | ✅ Sim |
-| **Trigger** | Push to `staging` | Push to `main` |
-| **Aprovação** | Nenhuma | **Obrigatória** |
-| **Tests** | Unit + Integration | Unit + Integration + Security |
-
----
-
-## 🔐 Workload Identity Federation
-
-### O que é?
-
-Autenticação moderna do Azure DevOps para Azure **sem usar secrets/passwords**.
-
-### Vantagens
-
-| Tradicional (Service Principal) | Workload Identity |
-|--------------------------------|-------------------|
-| ❌ Secrets expiram (1-2 anos) | ✅ Token auto-renova |
-| ❌ Secrets vazam facilmente | ✅ Sem secrets armazenados |
-| ❌ Rotação manual | ✅ Rotação automática |
-| ❌ Dificil auditar | ✅ Audit trail completo |
-
-### Setup
-
-Ver guia completo: [`docs/azure-devops-setup.md`](docs/azure-devops-setup.md)
-
----
-
-## 🆘 Troubleshooting
-
-### Pipeline falha com "Failed to get federated token"
-
-**Causa:** Federated credential não configurado corretamente.
-
-**Solução:**
-1. Verificar subject do federated credential
-2. Deve ser: `sc://<ORG>/<PROJECT>/<SERVICE_CONNECTION_NAME>`
-3. Recriar se necessário (ver `docs/azure-devops-setup.md`)
-
-### Pipeline falha com "Insufficient permissions"
-
-**Causa:** Service Principal não tem permissões.
-
-**Solução:**
-```bash
-# Adicionar Contributor role
-az role assignment create \
-  --assignee <SP_ID> \
-  --role Contributor \
-  --scope "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>"
-```
-
-### Container não sobe após deploy
-
-**Causa:** Possíveis: imagem incorreta, health check falhando, ACR permissions.
-
-**Solução:**
-```bash
-# Ver logs do Container App
-az containerapp logs show \
-  -n ca-myapp-staging \
-  -g rg-myapp-staging \
-  --follow
-```
-
----
-
-## 📚 Documentação Completa
-
-| Documento | Descrição |
-|-----------|-----------|
-| [Azure DevOps Setup](docs/azure-devops-setup.md) | Setup completo (Workload Identity, Service Connections, Environments) |
-| [Local Development](docs/local-development.md) | Como rodar projeto local e acessar recursos staging |
-| [Branch Strategy](docs/branch-strategy.md) | Estratégia de branches (staging/main, feature branches) |
-| [Migration Guide](../content/.morph/standards/migration-guide.md) | App Service → Container Apps + CI/CD |
-| [Azure Standards](../content/.morph/standards/azure.md) | Padrões Azure e IaC |
-
----
-
-## ✅ Checklist de Produção
-
-Antes de ir para produção:
-
-- [ ] Workload Identity configurada (staging/prod)
-- [ ] Service connections criadas e testadas
-- [ ] Variáveis configuradas (ACR_NAME, APP_NAME, SUBSCRIPTION_ID)
-- [ ] Environments criados (staging sem aprovação, prod com aprovação)
-- [ ] Staging pipeline testado com sucesso
-- [ ] Prod pipeline testado com aprovação
-- [ ] Health checks implementados e funcionando
-- [ ] Application Insights configurado
-- [ ] Alerts configurados (CPU, Memory, Availability)
-- [ ] Runbook de rollback documentado
-
----
-
-*MORPH-SPEC by Polymorphism Tech*
+# MORPH-SPEC - Azure DevOps Pipelines
+
+> **CI/CD para One-Person Business com Workload Identity Federation (sem secrets)**
+
+---
+
+## 🚀 Quick Start
+
+### 1. Configurar Workload Identity (10 min)
+
+```bash
+# Ver guia completo em: docs/azure-devops-setup.md
+
+# Criar App Registrations
+az ad app create --display-name "myapp-staging-pipeline"
+az ad app create --display-name "myapp-prod-pipeline"
+
+# Configurar federated credentials
+# (Ver guia detalhado)
+```
+
+### 2. Importar Pipelines no Azure DevOps
+
+1. **Pipelines** → **New pipeline**
+2. **Azure Repos Git** → Selecione repo
+3. **Existing Azure Pipelines YAML file**
+4. Selecione:
+   - `.azure/pipelines/staging-pipeline.yml`
+   - `.azure/pipelines/prod-pipeline.yml`
+
+### 3. Configurar Variáveis
+
+Para cada pipeline, adicione:
+```
+ACR_NAME: <seu-acr-name>
+APP_NAME: <seu-app-name>
+SUBSCRIPTION_ID: <subscription-id>
+```
+
+### 4. Criar Environments
+
+1. **Pipelines** → **Environments** → **New environment**
+2. Criar:
+   - `staging` (sem aprovação - deploy rápido)
+   - `production` (aprovação obrigatória)
+
+### 5. Testar!
+
+```bash
+# Trigger staging pipeline
+git checkout staging
+git commit -m "test" --allow-empty
+git push origin staging
+
+# Trigger prod pipeline
+git checkout main
+git commit -m "test" --allow-empty
+git push origin main
+# ⏸️ Aprovar manualmente no Azure DevOps
+```
+
+---
+
+## 📁 Estrutura
+
+```
+.azure/
+├── README.md                           # Este arquivo
+├── docs/
+│   ├── azure-devops-setup.md          # Guia completo de setup
+│   ├── local-development.md           # Como rodar projeto local
+│   └── branch-strategy.md             # Estratégia de branches
+└── pipelines/
+    ├── staging-pipeline.yml           # Pipeline staging (branch: staging)
+    ├── prod-pipeline.yml              # Pipeline prod (branch: main/master)
+    ├── pipeline-variables.yml         # Variáveis compartilhadas
+    └── templates/
+        ├── build-dotnet.yml           # Template: Build .NET
+        ├── deploy-app-service.yml     # Template: Deploy App Service
+        ├── deploy-container-app.yml   # Template: Deploy Container Apps
+        └── infra-deploy.yml           # Template: Deploy Bicep
+```
+
+---
+
+## 🔄 Pipelines
+
+### Staging Pipeline (`staging-pipeline.yml`)
+
+**Hosting:** Container Apps com scale-to-zero (~$5-10/mês)
+
+**Trigger:** Push em `staging` branch
+
+**Stages:**
+1. ✅ Build & Test
+2. ✅ Deploy Infrastructure (Bicep)
+3. ✅ Build Container Image
+4. ✅ Push to ACR
+5. ✅ Deploy Container App
+6. ✅ Integration Tests
+
+**Aprovação:** Nenhuma (deploy automático)
+
+**Uso:** QA, testes de integração
+
+---
+
+### Prod Pipeline (`prod-pipeline.yml`)
+
+**Hosting:** Container Apps always-on (~$10-20/mês)
+
+**Trigger:** Push em `main` ou `master` branch
+
+**Stages:**
+1. ✅ Build & Test
+2. ✅ Security Scan
+3. ✅ Deploy Infrastructure (Bicep)  ← **Approval Required**
+4. ✅ Build Container Image
+5. ✅ Security Scan (Image)
+6. ✅ Deploy to Production  ← **Approval Required**
+7. ✅ Smoke Tests (Critical)
+8. ✅ Monitor & Report
+
+**Aprovação:** OBRIGATÓRIA (manual approval gate)
+
+**Uso:** Produção, ambiente crítico
+
+---
+
+## 🌐 Desenvolvimento Local
+
+**Developers NÃO têm ambiente próprio.** Ao invés disso:
+
+- ✅ Rodam projeto **LOCAL** (Visual Studio/Rider/VS Code)
+- ✅ Acessam recursos **REMOTOS** staging (SQL, Storage, Key Vault)
+- ✅ Testam localmente antes de commitar
+
+**Ver guia completo:** [`docs/local-development.md`](docs/local-development.md)
+
+---
+
+## 🎯 Fluxo Completo
+
+### Desenvolvimento Diário
+
+```bash
+# 1. Criar feature branch
+git checkout staging
+git pull origin staging
+git checkout -b feature/nova-funcionalidade
+
+# 2. Desenvolver LOCAL
+dotnet run  # Conecta em recursos staging
+
+# 3. Commitar
+git add .
+git commit -m "feat: adiciona nova funcionalidade"
+git push origin feature/nova-funcionalidade
+
+# 4. Criar PR para staging
+# Azure DevOps → Repos → Pull Requests → New
+# Source: feature/nova-funcionalidade → Target: staging
+# Self-approve e merge
+
+# 5. Staging pipeline triggado automaticamente
+# ✅ Deploy para staging
+```
+
+### Release para Produção
+
+```bash
+# 1. Criar PR staging → main
+# Azure DevOps → Repos → Pull Requests → New
+# Source: staging → Target: main
+
+# 2. Self-review e merge
+
+# 3. Prod pipeline triggado
+# ⏸️ Approval gate aparece
+# Revisar deployment summary
+# Aprovar manualmente
+
+# 4. Deploy para produção
+# ✅ Aplicação em produção
+```
+
+---
+
+## 📊 Comparativo de Ambientes
+
+| Aspecto | Staging | Prod |
+|---------|---------|------|
+| **Hosting** | Container Apps | Container Apps |
+| **Custo** | $5-10/mês | $10-20/mês |
+| **Disponibilidade** | Scale-to-zero | Always-on (min 1) |
+| **SSL** | Custom domain OK | Custom domain OK |
+| **Auto-scaling** | ✅ Sim | ✅ Sim |
+| **Trigger** | Push to `staging` | Push to `main` |
+| **Aprovação** | Nenhuma | **Obrigatória** |
+| **Tests** | Unit + Integration | Unit + Integration + Security |
+
+---
+
+## 🔐 Workload Identity Federation
+
+### O que é?
+
+Autenticação moderna do Azure DevOps para Azure **sem usar secrets/passwords**.
+
+### Vantagens
+
+| Tradicional (Service Principal) | Workload Identity |
+|--------------------------------|-------------------|
+| ❌ Secrets expiram (1-2 anos) | ✅ Token auto-renova |
+| ❌ Secrets vazam facilmente | ✅ Sem secrets armazenados |
+| ❌ Rotação manual | ✅ Rotação automática |
+| ❌ Dificil auditar | ✅ Audit trail completo |
+
+### Setup
+
+Ver guia completo: [`docs/azure-devops-setup.md`](docs/azure-devops-setup.md)
+
+---
+
+## 🆘 Troubleshooting
+
+### Pipeline falha com "Failed to get federated token"
+
+**Causa:** Federated credential não configurado corretamente.
+
+**Solução:**
+1. Verificar subject do federated credential
+2. Deve ser: `sc://<ORG>/<PROJECT>/<SERVICE_CONNECTION_NAME>`
+3. Recriar se necessário (ver `docs/azure-devops-setup.md`)
+
+### Pipeline falha com "Insufficient permissions"
+
+**Causa:** Service Principal não tem permissões.
+
+**Solução:**
+```bash
+# Adicionar Contributor role
+az role assignment create \
+  --assignee <SP_ID> \
+  --role Contributor \
+  --scope "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>"
+```
+
+### Container não sobe após deploy
+
+**Causa:** Possíveis: imagem incorreta, health check falhando, ACR permissions.
+
+**Solução:**
+```bash
+# Ver logs do Container App
+az containerapp logs show \
+  -n ca-myapp-staging \
+  -g rg-myapp-staging \
+  --follow
+```
+
+---
+
+## 📚 Documentação Completa
+
+| Documento | Descrição |
+|-----------|-----------|
+| [Azure DevOps Setup](docs/azure-devops-setup.md) | Setup completo (Workload Identity, Service Connections, Environments) |
+| [Local Development](docs/local-development.md) | Como rodar projeto local e acessar recursos staging |
+| [Branch Strategy](docs/branch-strategy.md) | Estratégia de branches (staging/main, feature branches) |
+| [Migration Guide](../content/.morph/standards/migration-guide.md) | App Service → Container Apps + CI/CD |
+| [Azure Standards](../content/.morph/standards/azure.md) | Padrões Azure e IaC |
+
+---
+
+## ✅ Checklist de Produção
+
+Antes de ir para produção:
+
+- [ ] Workload Identity configurada (staging/prod)
+- [ ] Service connections criadas e testadas
+- [ ] Variáveis configuradas (ACR_NAME, APP_NAME, SUBSCRIPTION_ID)
+- [ ] Environments criados (staging sem aprovação, prod com aprovação)
+- [ ] Staging pipeline testado com sucesso
+- [ ] Prod pipeline testado com aprovação
+- [ ] Health checks implementados e funcionando
+- [ ] Application Insights configurado
+- [ ] Alerts configurados (CPU, Memory, Availability)
+- [ ] Runbook de rollback documentado
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*