@polymorphism-tech/morph-spec 2.4.0 → 3.0.0

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

@@ -1,267 +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_
+# 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_