@polymorphism-tech/morph-spec 2.2.0 → 2.4.0

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_

package/content/.morph/examples/state-v3.json

@@ -0,0 +1,188 @@
+{
+  "version": "3.0.0",
+  "project": {
+    "name": "FishArt",
+    "type": "blazor-server",
+    "createdAt": "2024-01-15T10:00:00Z",
+    "updatedAt": "2024-01-15T14:30:00Z"
+  },
+  "features": {
+    "scheduled-reports": {
+      "status": "in_progress",
+      "phase": "implement",
+      "activeAgents": [
+        "standards-architect",
+        "blazor-builder",
+        "ef-modeler",
+        "hangfire-orchestrator"
+      ],
+      "tasks": [
+        {
+          "id": "T001",
+          "title": "Create ScheduledReport entity",
+          "status": "completed",
+          "completedAt": "2024-01-15T10:30:00Z",
+          "completedBy": "claude",
+          "dependencies": [],
+          "files": [
+            "Domain/Entities/ScheduledReport.cs",
+            "Infrastructure/Persistence/Config/ScheduledReportConfig.cs"
+          ],
+          "checkpoint": "CHECKPOINT_001"
+        },
+        {
+          "id": "T002",
+          "title": "Create CreateReportCommand + Handler",
+          "status": "completed",
+          "completedAt": "2024-01-15T11:15:00Z",
+          "completedBy": "claude",
+          "dependencies": ["T001"],
+          "files": [
+            "Application/Commands/CreateReport/CreateReportCommand.cs",
+            "Application/Commands/CreateReport/CreateReportHandler.cs"
+          ]
+        },
+        {
+          "id": "T003",
+          "title": "Create Hangfire job for report generation",
+          "status": "completed",
+          "completedAt": "2024-01-15T12:00:00Z",
+          "completedBy": "claude",
+          "dependencies": ["T002"],
+          "files": [
+            "Infrastructure/Jobs/GenerateReportJob.cs"
+          ],
+          "checkpoint": "CHECKPOINT_002"
+        },
+        {
+          "id": "T004",
+          "title": "Create ReportList component (Blazor)",
+          "status": "in_progress",
+          "startedAt": "2024-01-15T13:00:00Z",
+          "dependencies": ["T001"],
+          "files": [
+            "Components/Reports/ReportList.razor",
+            "Components/Reports/ReportList.razor.cs",
+            "Components/Reports/ReportList.razor.css"
+          ]
+        },
+        {
+          "id": "T005",
+          "title": "Create CreateReportForm component (Blazor)",
+          "status": "pending",
+          "dependencies": ["T002"],
+          "files": [
+            "Components/Reports/CreateReportForm.razor",
+            "Components/Reports/CreateReportForm.razor.cs",
+            "Components/Reports/CreateReportForm.razor.css"
+          ]
+        },
+        {
+          "id": "T006",
+          "title": "Create API controller for reports",
+          "status": "pending",
+          "dependencies": ["T002"],
+          "files": [
+            "API/Controllers/ReportsController.cs"
+          ]
+        },
+        {
+          "id": "T007",
+          "title": "Add Hangfire dashboard configuration",
+          "status": "pending",
+          "dependencies": ["T003"],
+          "files": [
+            "Program.cs"
+          ]
+        },
+        {
+          "id": "T008",
+          "title": "Create unit tests for CreateReportCommand",
+          "status": "pending",
+          "dependencies": ["T002"],
+          "files": [
+            "Tests/Application/Commands/CreateReportCommandTests.cs"
+          ]
+        },
+        {
+          "id": "T009",
+          "title": "Create integration tests for report generation",
+          "status": "pending",
+          "dependencies": ["T003", "T006"],
+          "files": [
+            "Tests/Integration/ReportGenerationTests.cs"
+          ],
+          "checkpoint": "CHECKPOINT_003"
+        }
+      ],
+      "progress": {
+        "total": 9,
+        "completed": 3,
+        "inProgress": 1,
+        "pending": 5,
+        "percentage": 33
+      },
+      "checkpoints": [
+        {
+          "id": "CHECKPOINT_001",
+          "timestamp": "2024-01-15T10:30:00Z",
+          "tasksCompleted": ["T001"],
+          "note": "Checkpoint: Create ScheduledReport entity"
+        },
+        {
+          "id": "CHECKPOINT_002",
+          "timestamp": "2024-01-15T12:00:00Z",
+          "tasksCompleted": ["T003"],
+          "note": "Checkpoint: Create Hangfire job for report generation"
+        },
+        {
+          "id": "CHECKPOINT_AUTO_1705326000000",
+          "timestamp": "2024-01-15T12:00:00Z",
+          "tasksCompleted": ["T001", "T002", "T003"],
+          "note": "Auto-checkpoint: 3 tasks completed"
+        }
+      ],
+      "outputs": {
+        "proposal": {
+          "created": true,
+          "path": ".morph/project/outputs/scheduled-reports/proposal.md"
+        },
+        "spec": {
+          "created": true,
+          "path": ".morph/project/outputs/scheduled-reports/spec.md"
+        },
+        "contracts": {
+          "created": true,
+          "path": ".morph/project/outputs/scheduled-reports/contracts.cs"
+        },
+        "ui-spec": {
+          "created": true,
+          "path": ".morph/project/outputs/scheduled-reports/ui-spec.md"
+        },
+        "tasks": {
+          "created": true,
+          "note": "Tasks are now inline in state.json (schema 3.0.0)"
+        },
+        "decisions": {
+          "created": true,
+          "path": ".morph/project/outputs/scheduled-reports/decisions.md"
+        }
+      },
+      "costs": {
+        "estimated": 5.50,
+        "approved": true,
+        "breakdown": {
+          "hangfire": 0,
+          "storage": 0.02,
+          "sql": 4.99,
+          "containerApp": 0.49
+        }
+      }
+    }
+  },
+  "metadata": {
+    "totalFeatures": 1,
+    "completedFeatures": 0,
+    "totalCostEstimated": 5.50
+  }
+}

package/content/.morph/features/.gitkeep

@@ -1,25 +1,25 @@
-# Features em Desenvolvimento
-
-Esta pasta contém as features ATIVAS em desenvolvimento.
-
-## Estrutura
-
-```
-features/
-└── {feature-name}/
-    ├── proposal.md    # Proposta (por que e o quê)
-    ├── spec.md        # Especificação técnica
-    ├── tasks.md       # Checklist de implementação
-    ├── contracts.cs   # Interfaces e DTOs
-    ├── decisions.md   # ADRs
-    └── recap.md       # Resumo pós-implementação
-```
-
-## Workflow
-
-1. `/morph-proposal {feature}` - Criar nova feature
-2. Revisar e aprovar proposal
-3. `/morph-apply {feature}` - Implementar
-4. `/morph-archive {feature}` - Arquivar quando concluída
-
-*Gerado pelo MORPH Framework*
+# Features em Desenvolvimento
+
+Esta pasta contém as features ATIVAS em desenvolvimento.
+
+## Estrutura
+
+```
+features/
+└── {feature-name}/
+    ├── proposal.md    # Proposta (por que e o quê)
+    ├── spec.md        # Especificação técnica
+    ├── tasks.md       # Checklist de implementação
+    ├── contracts.cs   # Interfaces e DTOs
+    ├── decisions.md   # ADRs
+    └── recap.md       # Resumo pós-implementação
+```
+
+## Workflow
+
+1. `/morph-proposal {feature}` - Criar nova feature
+2. Revisar e aprovar proposal
+3. `/morph-apply {feature}` - Implementar
+4. `/morph-archive {feature}` - Arquivar quando concluída
+
+*Gerado pelo MORPH Framework*