@polymorphism-tech/morph-spec 2.3.0 → 3.0.0

package/content/.morph/docs/workflows/full-morph.md

@@ -0,0 +1,76 @@
+# Workflow: FULL MORPH (Alta Complexidade)
+
+> **Layer:** 1 | **Load:** on-keyword | **Keywords:** sistema, autenticação, integração, pattern, cqrs, subsistema
+
+## Critérios
+
+- > 10 arquivos, > 500 linhas, múltiplos componentes novos
+- Infraestrutura Azure (Bicep), decisões arquiteturais estratégicas
+
+## Fases (TODAS obrigatórias)
+
+### FASE 0.5: CONTEXT (automática)
+1. Detectar framework MORPH (`@polymorphism-tech/morph-spec`)
+2. Detectar/criar estrutura `.morph/project/`
+3. Análise automática: stack (glob patterns), arquitetura (pastas), configs, UI library
+4. Analisar histórico: decisions.md passados, preferências do usuário
+5. Gerar/atualizar `.morph/project/standards/inferred.md`
+6. Ativar agentes baseado em stack + keywords
+
+### FASE 0: PROPOSAL
+1. `npx morph-spec detect "{user-request}"`
+2. Analisar solicitação, identificar stack, estimar complexidade
+3. Gerar proposal.md, registrar agentes no state.json
+- **⛔ PAUSA:** 3 itens (1 ação + 1 pergunta + 1 sugestão)
+
+### FASE 1: SETUP
+1. Ler `.morph/config.json`
+2. Confirmar stack, ativar agentes, criar pasta outputs
+3. Carregar padrões (framework/standards/ > project/standards/)
+
+### FASE 1.5: UI/UX (condicional - se keywords UI detectadas)
+1. **Perguntar ao usuário:** layout, referências visuais, fluxo, imagens
+2. Analisar referências fornecidas
+3. Gerar deliverables AGNÓSTICOS de biblioteca (ui-mockups, ui-components, ui-flows)
+4. Validar acessibilidade (WCAG 2.1) e responsividade
+- **⛔ PAUSA:** Aprovar / Ajustar wireframes / Adicionar fluxos
+
+### FASE 2: DESIGN
+1. Gerar spec.md com requisitos completos
+2. **DECISION POINTS** (cada um requer aprovação):
+   - Biblioteca UI (Fluent UI vs MudBlazor)
+   - Padrões Arquiteturais (CQRS vs simples, Repository vs EF direto)
+   - Estrutura de Dados (entidades, relacionamentos)
+   - Infraestrutura Azure (recursos, SKUs, custos)
+   - Bibliotecas/SDKs (NuGet packages)
+3. Gerar contracts.cs, documentar decisões em decisions.md
+- **⛔ PAUSA:** Aprovar / Ajustar escopo / Modificar contracts
+
+### FASE 3: CLARIFY
+1. Identificar ambiguidades, fazer perguntas, documentar em spec.md, validar edge cases
+
+### FASE 4: TASKS
+1. Quebrar spec em tasks T001-TXXX, definir ordem, checkpoints, dependências
+- **⛔ PAUSA:** Aprovar / Repriorizar / Adicionar-remover tasks
+
+### FASE 5: IMPLEMENT
+1. Implementar task por task
+2. `npx morph-spec task done {feature} {task-id}` após cada task
+3. Framework gerencia checkpoints automaticamente (a cada 3 tasks)
+4. Gerar recap.md ao final
+
+### FASE 6: SYNC (condicional - se complexidade média/alta)
+1. Revisar decisions.md, categorizar (coding, architecture, azure, integrations, ui-ux)
+2. Promover para `.morph/project/standards/{category}.md`
+3. Gerar commit dedicado de sync
+- **⛔ PAUSA:** Aprovar promoção de decisões para standards
+
+## Outputs Completos
+proposal.md, ui-design-system.md, ui-mockups.md, ui-components.md, ui-flows.md, spec.md, contracts.cs, tasks.json, decisions.md, recap.md
+
+## Exemplos
+- "Sistema de relatórios com jobs agendados Hangfire"
+- "Autenticação completa com Clerk (login, signup, OAuth)"
+- "Dashboard com gráficos, tabelas e filtros complexos"
+- "RAG pipeline com Azure AI Search e embeddings"
+- "Infraestrutura Azure completa com Bicep"

package/content/.morph/docs/workflows/standard.md

@@ -0,0 +1,44 @@
+# Workflow: STANDARD (Média Complexidade)
+
+> **Layer:** 1 | **Load:** on-keyword | **Keywords:** paginação, filtro, refatorar, performance, exportar
+
+## Critérios
+
+- 3-10 arquivos, 50-500 linhas, 1-2 componentes simples
+- Sem infraestrutura complexa, decisões táticas (não estratégicas)
+
+## Fases
+
+### 1. FASE 0: PROPOSAL (simplificada)
+- Análise inicial em 1 parágrafo
+- Detecta agentes relevantes
+- **PAUSA:** Aprovar?
+
+### 2. FASE 2: DESIGN (apenas spec.md)
+- Spec técnico conciso (1-2 páginas)
+- Sem contracts.cs se trivial
+- Decisões táticas em decisions.md
+- **PAUSA:** Aprovar?
+
+### 3. FASE 4: TASKS (se > 5 tasks)
+- Breakdown em tasks
+- **PAUSA:** Aprovar?
+
+### 4. FASE 5: IMPLEMENT
+- Implementa task por task
+- Gera recap.md ao final
+
+## Outputs
+proposal.md, spec.md, recap.md (mínimo necessário)
+
+## Fases Puladas
+- FASE 1 (SETUP) - contexto já carregado
+- FASE 1.5 (UI/UX) - se não tiver front-end significativo
+- FASE 3 (CLARIFY) - se spec for claro
+- FASE 6 (SYNC) - decisões não são estratégicas
+
+## Exemplos
+- "Adicionar paginação na tabela de usuários"
+- "Criar filtro por data no relatório"
+- "Refatorar serviço de email para async"
+- "Adicionar botão de exportar CSV"

package/content/.morph/docs/workflows/ui-refresh.md

@@ -0,0 +1,39 @@
+# Workflow: UI REFRESH (Redesign Visual)
+
+> **Layer:** 1 | **Load:** on-keyword | **Keywords:** redesign, redesenhar, bonito, visual, estetica, modernizar
+
+## Critérios
+
+- Páginas existentes com código funcional
+- Apenas mudanças visuais (CSS, HTML, layout)
+- Sem mudanças em lógica de negócio, sem infraestrutura
+
+## Fases
+
+### 1. ANÁLISE VISUAL (FASE 0+1 combinadas)
+- Listar páginas a redesenhar
+- Identificar componentes compartilhados e design system existente
+- Se protótipo existir: ler e extrair padrões
+- **PAUSA:** Escolher direção estética
+
+### 2. DESIGN SYSTEM (FASE 1.5 simplificada)
+- Definir variáveis CSS novas
+- Listar componentes CSS a criar (checklist)
+- Gerar/atualizar design-system.css
+- **PAUSA:** Aprovar componentes
+
+### 3. IMPLEMENT (por página)
+- Atualizar CSS primeiro, depois cada página .razor
+- Build incremental a cada 2-3 páginas
+- Validar com `morph-spec validate-css`
+
+## Outputs
+design-refresh-checklist.md, CSS atualizado, páginas .razor, recap.md
+
+## Fases Puladas
+Setup completo, Contracts, Tasks detalhadas, Infra, Clarify, Sync
+
+## Exemplos
+- "Redesenhar as páginas do checkout para ficar mais bonito"
+- "Modernizar visual do dashboard"
+- "Aplicar novo design system nas telas existentes"

package/content/.morph/examples/scheduled-reports/decisions.md

@@ -0,0 +1,158 @@
+# Decisões Arquiteturais - Scheduled Reports
+
+> Exemplo real de decisions.md gerado pelo MORPH-SPEC
+
+---
+
+## ADR-001: Biblioteca de Background Jobs
+
+**Data:** 2024-01-15
+**Status:** Aceito
+**Contexto:** Precisamos executar relatórios em horários agendados.
+
+### Opções Consideradas
+
+| Opção | Pros | Cons |
+|-------|------|------|
+| **Hangfire** | Dashboard, retry, SQL storage | Licença para recursos avançados |
+| Azure Functions (Timer) | Serverless, escalável | Mais complexo, cold start |
+| Quartz.NET | Open source completo | Sem dashboard built-in |
+
+### Decisão
+
+**Hangfire** - Já usado no projeto, dashboard útil para monitoramento, integração simples com DI.
+
+### Consequências
+- ✅ Fácil implementação
+- ✅ Dashboard para operações
+- ⚠️ Considerar licença Pro se precisar de batches
+
+---
+
+## ADR-002: Geração de PDF
+
+**Data:** 2024-01-15
+**Status:** Aceito
+**Contexto:** Precisamos gerar PDFs dos relatórios.
+
+### Opções Consideradas
+
+| Opção | Pros | Cons |
+|-------|------|------|
+| **QuestPDF** | Fluent API, .NET nativo, gratuito | Mais novo, menos exemplos |
+| iTextSharp | Maduro, muitos exemplos | Licença AGPL (viral) |
+| PuppeteerSharp | HTML→PDF | Requer Chrome, pesado |
+
+### Decisão
+
+**QuestPDF** - API moderna, totalmente .NET, licença MIT.
+
+### Consequências
+- ✅ Código limpo e legível
+- ✅ Sem dependências externas
+- ⚠️ Curva de aprendizado para layouts complexos
+
+---
+
+## ADR-003: Biblioteca UI
+
+**Data:** 2024-01-15
+**Status:** Aceito
+**Contexto:** Componentes UI para as telas de relatórios.
+
+### Opções Consideradas
+
+| Opção | Pros | Cons |
+|-------|------|------|
+| **Fluent UI Blazor** | Já no projeto, design MS | Menos componentes |
+| MudBlazor | Mais componentes | Adicionar dependência |
+
+### Decisão
+
+**Fluent UI Blazor** - Já instalado no projeto, manter consistência.
+
+### Consequências
+- ✅ Sem nova dependência
+- ✅ Visual consistente
+- ⚠️ Pode precisar criar componentes custom
+
+---
+
+## ADR-004: Armazenamento de Arquivos
+
+**Data:** 2024-01-15
+**Status:** Aceito
+**Contexto:** Onde armazenar os PDFs/Excels gerados.
+
+### Opções Consideradas
+
+| Opção | Pros | Cons |
+|-------|------|------|
+| **Azure Blob Storage** | Escalável, barato, SAS tokens | Requer setup |
+| Sistema de arquivos | Simples | Não escala, perde em redeploy |
+| Database (BLOB) | Tudo junto | Performance ruim |
+
+### Decisão
+
+**Azure Blob Storage** - Já usado para outros arquivos, suporta SAS tokens para links temporários.
+
+### Consequências
+- ✅ Escalável
+- ✅ Links com expiração
+- ⚠️ Custo adicional (baixo)
+
+---
+
+## ADR-005: Padrão CQRS
+
+**Data:** 2024-01-15
+**Status:** Aceito
+**Contexto:** Estruturar commands e queries.
+
+### Decisão
+
+**CQRS com MediatR** - Separação clara de responsabilidades, já é o padrão do projeto.
+
+### Commands
+- `CreateScheduledReportCommand`
+- `UpdateScheduledReportCommand`
+- `DeleteScheduledReportCommand`
+- `ExecuteReportCommand`
+
+### Queries
+- `GetScheduledReportByIdQuery`
+- `GetScheduledReportsQuery`
+- `GetReportExecutionsQuery`
+
+---
+
+## ADR-006: Estratégia de Retry
+
+**Data:** 2024-01-15
+**Status:** Aceito
+**Contexto:** Como lidar com falhas na execução de jobs.
+
+### Decisão
+
+**Exponential backoff com limite:**
+- Retry 1: 1 minuto
+- Retry 2: 5 minutos
+- Retry 3: 15 minutos
+- Após 3 falhas: marcar como Error, notificar admin
+
+```csharp
+[AutomaticRetry(Attempts = 3, DelaysInSeconds = new[] { 60, 300, 900 })]
+public async Task ExecuteReportJob(int reportId) { ... }
+```
+
+---
+
+## Histórico de Mudanças
+
+| Data | ADR | Mudança |
+|------|-----|---------|
+| 2024-01-15 | 001-006 | Decisões iniciais |
+
+---
+
+_Gerado por MORPH-SPEC Framework_

package/content/.morph/examples/scheduled-reports/proposal.md

@@ -0,0 +1,95 @@
+# Proposta: Sistema de Relatórios Agendados
+
+> Exemplo real de proposal.md gerado pelo MORPH-SPEC
+
+---
+
+## 📋 Resumo da Solicitação
+
+O usuário solicitou um sistema para agendar e executar relatórios automaticamente, com suporte a diferentes formatos de saída (PDF, Excel) e notificação por email.
+
+---
+
+## 🎯 Análise Inicial
+
+### Stack Identificado
+- **Backend:** .NET 8 + Blazor Server
+- **Database:** SQL Server (Entity Framework Core)
+- **Background Jobs:** Hangfire
+- **UI:** Fluent UI Blazor (detectado no projeto)
+
+### Complexidade Estimada
+**ALTA** - Justificativa:
+- Múltiplos componentes (entidades, jobs, UI)
+- Integração com sistema de email
+- Geração de arquivos (PDF, Excel)
+- CRON expressions para agendamento
+
+### Agentes Ativados
+1. 📐 Standards Architect
+2. ☁️ Azure Architect
+3. 🔥 Blazor Builder
+4. 🗄️ EF Modeler
+5. ⏰ Hangfire Orchestrator
+6. 🎨 UI/UX Designer
+
+---
+
+## 📊 Escopo Preliminar
+
+### Funcionalidades Core
+1. CRUD de relatórios agendados
+2. Configuração de periodicidade (CRON)
+3. Seleção de formato de saída (PDF/Excel)
+4. Execução manual e automática
+5. Histórico de execuções
+6. Notificação por email
+
+### Fora do Escopo (MVP)
+- [ ] Dashboard com métricas de execução
+- [ ] Relatórios customizáveis pelo usuário
+- [ ] Integração com BI tools
+
+---
+
+## 💰 Estimativa de Custos Azure
+
+| Recurso | SKU | Custo Estimado/mês |
+|---------|-----|-------------------|
+| Container App | 0.5 vCPU, 1GB | ~$15 |
+| SQL Database | Basic (5 DTU) | ~$5 |
+| Storage (blobs) | LRS | ~$1 |
+| **Total** | | **~$21/mês** |
+
+---
+
+## ⏱️ Estimativa de Esforço
+
+| Fase | Tasks Estimadas |
+|------|-----------------|
+| Design | 2-3 |
+| Entities + EF | 3-4 |
+| Handlers/Services | 4-5 |
+| Background Jobs | 2-3 |
+| UI Components | 4-5 |
+| Testes | 3-4 |
+| **Total** | **18-24 tasks** |
+
+---
+
+## ⛔ PAUSA OBRIGATÓRIA
+
+**Próximos passos sugeridos:**
+
+1. ✅ **Aprovar proposta e prosseguir para Setup**
+   Carregar contexto completo e ativar agentes detectados
+
+2. ❓ **Esclarecer escopo**
+   Você precisa de dashboard de métricas no MVP? Ou apenas a lista de relatórios?
+
+3. 💡 **Considerar MVP mais enxuto**
+   Começar apenas com PDF e adicionar Excel em iteração futura?
+
+---
+
+_Gerado por MORPH-SPEC Framework_

package/content/.morph/examples/scheduled-reports/spec.md

@@ -0,0 +1,267 @@
+# Especificação Técnica: Sistema de Relatórios Agendados
+
+> Exemplo real de spec.md gerado pelo MORPH-SPEC
+
+---
+
+## 📋 Informações do Documento
+
+| Campo | Valor |
+|-------|-------|
+| Feature | scheduled-reports |
+| Versão | 1.0 |
+| Status | Aprovado |
+| Data | 2024-01-15 |
+| Autor | MORPH-SPEC + User |
+
+---
+
+## 1. Visão Geral
+
+### 1.1 Objetivo
+Permitir que usuários criem relatórios que são executados automaticamente em horários configurados, gerando arquivos PDF ou Excel e notificando via email.
+
+### 1.2 Contexto
+O sistema atual não possui funcionalidade de relatórios agendados. Usuários precisam gerar relatórios manualmente, o que é ineficiente para relatórios recorrentes.
+
+### 1.3 Stakeholders
+- **Usuários finais:** Gestores que precisam de relatórios periódicos
+- **Administradores:** Configuração e monitoramento de jobs
+
+---
+
+## 2. Requisitos Funcionais
+
+### 2.1 CRUD de Relatórios Agendados
+
+#### RF-001: Criar Relatório Agendado
+- [ ] Usuário pode criar relatório com nome e descrição
+- [ ] Usuário pode selecionar tipo de relatório (vendas, estoque, financeiro)
+- [ ] Usuário pode definir formato de saída (PDF, Excel)
+- [ ] Usuário pode definir periodicidade (diário, semanal, mensal, custom CRON)
+- [ ] Usuário pode definir destinatários de email
+
+#### RF-002: Listar Relatórios
+- [ ] Listar relatórios do usuário com paginação
+- [ ] Filtrar por status (ativo, pausado, erro)
+- [ ] Ordenar por última execução ou próxima execução
+
+#### RF-003: Editar Relatório
+- [ ] Editar todas as propriedades exceto tipo
+- [ ] Pausar/retomar agendamento
+
+#### RF-004: Excluir Relatório
+- [ ] Soft delete com confirmação
+- [ ] Cancelar jobs pendentes ao excluir
+
+### 2.2 Execução de Relatórios
+
+#### RF-005: Execução Automática
+- [ ] Hangfire executa job no horário configurado
+- [ ] Job gera arquivo no formato selecionado
+- [ ] Arquivo é salvo em Azure Blob Storage
+- [ ] Email é enviado aos destinatários com link para download
+
+#### RF-006: Execução Manual
+- [ ] Botão "Executar Agora" na UI
+- [ ] Mesma lógica do job automático
+- [ ] Feedback imediato de "em execução"
+
+### 2.3 Histórico
+
+#### RF-007: Histórico de Execuções
+- [ ] Listar últimas 50 execuções por relatório
+- [ ] Mostrar: data, duração, status, link do arquivo
+- [ ] Filtrar por período
+
+---
+
+## 3. Requisitos Não-Funcionais
+
+### 3.1 Performance
+- **RNF-001:** Geração de PDF deve completar em < 30 segundos
+- **RNF-002:** Lista de relatórios deve carregar em < 500ms
+
+### 3.2 Segurança
+- **RNF-003:** Usuário só pode ver/editar seus próprios relatórios
+- **RNF-004:** Links de download expiram em 24h
+- **RNF-005:** Arquivos são criptografados em repouso
+
+### 3.3 Escalabilidade
+- **RNF-006:** Suportar até 1000 relatórios agendados simultâneos
+- **RNF-007:** Jobs executam em fila separada para não bloquear app
+
+---
+
+## 4. Modelo de Dados
+
+### 4.1 Entidade: ScheduledReport
+
+```csharp
+public class ScheduledReport
+{
+    public int Id { get; private set; }
+    public int UserId { get; private set; }
+    public string Name { get; private set; }
+    public string? Description { get; private set; }
+    public ReportType Type { get; private set; }
+    public OutputFormat Format { get; private set; }
+    public string CronExpression { get; private set; }
+    public ReportStatus Status { get; private set; }
+    public List<string> Recipients { get; private set; }
+    public DateTime? LastExecutedAt { get; private set; }
+    public DateTime? NextExecutionAt { get; private set; }
+    public DateTime CreatedAt { get; private set; }
+    public DateTime? UpdatedAt { get; private set; }
+    public bool IsDeleted { get; private set; }
+
+    // Navigation
+    public User User { get; private set; }
+    public ICollection<ReportExecution> Executions { get; private set; }
+}
+```
+
+### 4.2 Entidade: ReportExecution
+
+```csharp
+public class ReportExecution
+{
+    public int Id { get; private set; }
+    public int ScheduledReportId { get; private set; }
+    public ExecutionStatus Status { get; private set; }
+    public DateTime StartedAt { get; private set; }
+    public DateTime? CompletedAt { get; private set; }
+    public string? FilePath { get; private set; }
+    public long? FileSizeBytes { get; private set; }
+    public string? ErrorMessage { get; private set; }
+
+    // Navigation
+    public ScheduledReport ScheduledReport { get; private set; }
+}
+```
+
+### 4.3 Enums
+
+```csharp
+public enum ReportType { Sales, Inventory, Financial }
+public enum OutputFormat { Pdf, Excel }
+public enum ReportStatus { Active, Paused, Error }
+public enum ExecutionStatus { Pending, Running, Completed, Failed }
+```
+
+---
+
+## 5. Arquitetura
+
+### 5.1 Componentes
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         Blazor UI                           │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
+│  │ ReportList  │  │ ReportForm  │  │ ExecutionHistory    │  │
+│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                     Application Layer                        │
+│  ┌───────────────┐  ┌───────────────┐  ┌─────────────────┐  │
+│  │ CreateReport  │  │ ExecuteReport │  │ GetExecutions   │  │
+│  │   Handler     │  │    Handler    │  │    Handler      │  │
+│  └───────────────┘  └───────────────┘  └─────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                     Infrastructure                           │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
+│  │  Hangfire   │  │ Blob Storage│  │   Email Service     │  │
+│  │    Jobs     │  │             │  │                     │  │
+│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 5.2 Fluxo de Execução
+
+```
+1. Hangfire dispara job baseado em CRON
+2. Job carrega config do relatório
+3. Job chama ReportGenerator.Generate()
+4. Arquivo é salvo em Blob Storage
+5. EmailService envia notificação
+6. ReportExecution é registrado
+```
+
+---
+
+## 6. API/Commands
+
+### 6.1 Commands
+
+| Command | Descrição |
+|---------|-----------|
+| `CreateScheduledReportCommand` | Criar novo relatório |
+| `UpdateScheduledReportCommand` | Atualizar relatório |
+| `DeleteScheduledReportCommand` | Soft delete |
+| `ExecuteReportCommand` | Execução manual |
+| `PauseReportCommand` | Pausar agendamento |
+| `ResumeReportCommand` | Retomar agendamento |
+
+### 6.2 Queries
+
+| Query | Descrição |
+|-------|-----------|
+| `GetScheduledReportByIdQuery` | Buscar por ID |
+| `GetScheduledReportsQuery` | Listar com paginação |
+| `GetReportExecutionsQuery` | Histórico de execuções |
+
+---
+
+## 7. Dependências
+
+### 7.1 NuGet Packages
+- `Hangfire.Core` - Background jobs
+- `Hangfire.SqlServer` - Storage para Hangfire
+- `QuestPDF` - Geração de PDF
+- `ClosedXML` - Geração de Excel
+- `Azure.Storage.Blobs` - Blob storage
+
+### 7.2 Serviços Externos
+- Azure Blob Storage (arquivos gerados)
+- SendGrid ou SMTP (emails)
+
+---
+
+## 8. Edge Cases
+
+| Cenário | Comportamento |
+|---------|---------------|
+| Job falha no meio | Status = Error, retry em 5 min (max 3x) |
+| Email inválido | Log warning, continua com outros |
+| Blob storage offline | Status = Error, retry |
+| Relatório sem dados | Gera arquivo vazio com mensagem |
+| Usuário deleta enquanto job roda | Job completa, não envia email |
+
+---
+
+## 9. Validações
+
+| Campo | Regras |
+|-------|--------|
+| Name | Required, 3-100 chars |
+| CronExpression | Valid CRON, mínimo 1h entre execuções |
+| Recipients | 1-10 emails válidos |
+| Format | Enum válido |
+
+---
+
+## 10. Aprovações
+
+- [x] **Requisitos:** Aprovados em 2024-01-15
+- [x] **Modelo de Dados:** Aprovado em 2024-01-15
+- [x] **Arquitetura:** Aprovada em 2024-01-15
+
+---
+
+_Gerado por MORPH-SPEC Framework_