@polymorphism-tech/morph-spec 2.2.0 → 2.4.0

package/content/.claude/skills/stacks/dotnet-blazor.md

@@ -1,588 +1,210 @@
-# .NET + Blazor Stack
-
-Stack principal para desenvolvimento de aplicações web com .NET e Blazor Server.
-
-## Visão Geral
-
-| Aspecto | Tecnologia |
-|---------|------------|
-| **Backend** | .NET 10 / C# 14 |
-| **Frontend** | Blazor Server |
-| **Database** | Entity Framework Core 10 + Azure SQL |
-| **Hosting** | Azure Container Apps |
-| **Background** | Hangfire |
-| **AI** | Microsoft Agent Framework (exclusivo) |
-
-## Triggers
-
-Keywords: `blazor`, `razor`, `server-side`, `.net`, `csharp`, `dotnet`
-
-## Estrutura de Projeto
-
-```
-src/
-├── {App}.Domain/                  # Entidades, Value Objects, Enums
-│   ├── Entities/
-│   ├── ValueObjects/
-│   ├── Enums/
-│   └── Exceptions/
-│
-├── {App}.Application/             # Serviços, DTOs, Interfaces
-│   ├── Services/
-│   ├── DTOs/
-│   ├── Interfaces/
-│   └── Validators/
-│
-├── {App}.Infrastructure/          # EF Core, External Services
-│   ├── Data/
-│   │   ├── AppDbContext.cs
-│   │   ├── Configurations/
-│   │   └── Migrations/
-│   ├── Services/
-│   └── Extensions/
-│
-├── {App}.Web/                     # Blazor Server
-│   ├── Program.cs
-│   ├── Components/
-│   │   ├── Layout/
-│   │   ├── Pages/
-│   │   └── Shared/
-│   ├── wwwroot/
-│   └── appsettings.json
-│
-└── tests/
-    ├── {App}.UnitTests/
-    └── {App}.IntegrationTests/
-```
-
-## Configuração do Projeto
-
-### csproj principal
-
-```xml
-<!-- {App}.Web.csproj -->
-<Project Sdk="Microsoft.NET.Sdk.Web">
-  <PropertyGroup>
-    <TargetFramework>net10.0</TargetFramework>
-    <Nullable>enable</Nullable>
-    <ImplicitUsings>enable</ImplicitUsings>
-  </PropertyGroup>
-
-  <ItemGroup>
-    <ProjectReference Include="..\{App}.Application\{App}.Application.csproj" />
-    <ProjectReference Include="..\{App}.Infrastructure\{App}.Infrastructure.csproj" />
-  </ItemGroup>
-</Project>
-```
-
-### Program.cs
-
-```csharp
-var builder = WebApplication.CreateBuilder(args);
-
-// Services
-builder.Services.AddRazorComponents()
-    .AddInteractiveServerComponents();
-
-// Database
-builder.Services.AddDbContext<AppDbContext>(options =>
-    options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection")));
-
-// Application Services
-builder.Services.AddScoped<IOrderService, OrderService>();
-builder.Services.AddScoped<ICustomerService, CustomerService>();
-
-// Hangfire
-builder.Services.AddHangfire(config => config
-    .UseSqlServerStorage(builder.Configuration.GetConnectionString("HangfireConnection")));
-builder.Services.AddHangfireServer();
-
-var app = builder.Build();
-
-// Pipeline
-if (!app.Environment.IsDevelopment())
-{
-    app.UseExceptionHandler("/Error");
-    app.UseHsts();
-}
-
-app.UseHttpsRedirection();
-app.UseStaticFiles();
-app.UseAntiforgery();
-
-app.MapRazorComponents<App>()
-    .AddInteractiveServerRenderMode();
-
-app.MapHangfireDashboard("/hangfire");
-
-app.Run();
-```
-
-## Componentes Blazor
-
-### Padrões de Componente
-
-```razor
-@* Components/Pages/Orders/OrderList.razor *@
-@page "/orders"
-@inject IOrderService OrderService
-@inject NavigationManager Navigation
-
-<PageTitle>Pedidos</PageTitle>
-
-<div class="container mx-auto p-4">
-    <div class="flex justify-between items-center mb-6">
-        <h1 class="text-2xl font-bold">Pedidos</h1>
-        <button @onclick="CreateNew" class="btn btn-primary">
-            Novo Pedido
-        </button>
-    </div>
-
-    @if (_orders is null)
-    {
-        <Loading />
-    }
-    else if (!_orders.Any())
-    {
-        <EmptyState Message="Nenhum pedido encontrado" />
-    }
-    else
-    {
-        <DataTable Items="_orders">
-            <HeaderTemplate>
-                <th>Número</th>
-                <th>Cliente</th>
-                <th>Total</th>
-                <th>Status</th>
-                <th>Ações</th>
-            </HeaderTemplate>
-            <RowTemplate Context="order">
-                <td>@order.OrderNumber</td>
-                <td>@order.CustomerName</td>
-                <td>@order.Total.ToString("C")</td>
-                <td><StatusBadge Status="@order.Status" /></td>
-                <td>
-                    <button @onclick="() => ViewOrder(order.Id)" class="btn btn-sm">
-                        Ver
-                    </button>
-                </td>
-            </RowTemplate>
-        </DataTable>
-    }
-</div>
-
-@code {
-    private List<OrderDto>? _orders;
-
-    protected override async Task OnInitializedAsync()
-    {
-        _orders = await OrderService.GetAllAsync();
-    }
-
-    private void CreateNew() => Navigation.NavigateTo("/orders/new");
-
-    private void ViewOrder(int id) => Navigation.NavigateTo($"/orders/{id}");
-}
-```
-
-### Formulários
-
-```razor
-@* Components/Pages/Orders/OrderForm.razor *@
-@page "/orders/new"
-@page "/orders/{Id:int}/edit"
-@inject IOrderService OrderService
-@inject NavigationManager Navigation
-
-<PageTitle>@(_isEdit ? "Editar" : "Novo") Pedido</PageTitle>
-
-<EditForm Model="_model" OnValidSubmit="HandleSubmit">
-    <DataAnnotationsValidator />
-
-    <div class="space-y-4">
-        <div>
-            <label for="customerId">Cliente</label>
-            <InputSelect @bind-Value="_model.CustomerId" id="customerId" class="input">
-                <option value="">Selecione...</option>
-                @foreach (var customer in _customers)
-                {
-                    <option value="@customer.Id">@customer.Name</option>
-                }
-            </InputSelect>
-            <ValidationMessage For="() => _model.CustomerId" />
-        </div>
-
-        <div>
-            <label for="notes">Observações</label>
-            <InputTextArea @bind-Value="_model.Notes" id="notes" class="input" />
-        </div>
-
-        <div class="flex gap-2">
-            <button type="submit" class="btn btn-primary" disabled="@_isSubmitting">
-                @if (_isSubmitting)
-                {
-                    <span class="loading"></span>
-                }
-                Salvar
-            </button>
-            <button type="button" @onclick="Cancel" class="btn">Cancelar</button>
-        </div>
-    </div>
-</EditForm>
-
-@code {
-    [Parameter] public int? Id { get; set; }
-
-    private OrderFormModel _model = new();
-    private List<CustomerDto> _customers = new();
-    private bool _isEdit => Id.HasValue;
-    private bool _isSubmitting;
-
-    protected override async Task OnInitializedAsync()
-    {
-        _customers = await CustomerService.GetAllAsync();
-
-        if (_isEdit)
-        {
-            var order = await OrderService.GetByIdAsync(Id!.Value);
-            _model = new OrderFormModel
-            {
-                CustomerId = order.CustomerId,
-                Notes = order.Notes
-            };
-        }
-    }
-
-    private async Task HandleSubmit()
-    {
-        _isSubmitting = true;
-
-        try
-        {
-            if (_isEdit)
-                await OrderService.UpdateAsync(Id!.Value, _model);
-            else
-                await OrderService.CreateAsync(_model);
-
-            Navigation.NavigateTo("/orders");
-        }
-        finally
-        {
-            _isSubmitting = false;
-        }
-    }
-
-    private void Cancel() => Navigation.NavigateTo("/orders");
-}
-```
-
-## Services
-
-```csharp
-// Application/Services/OrderService.cs
-public interface IOrderService
-{
-    Task<List<OrderDto>> GetAllAsync(CancellationToken ct = default);
-    Task<OrderDto> GetByIdAsync(int id, CancellationToken ct = default);
-    Task<OrderDto> CreateAsync(CreateOrderRequest request, CancellationToken ct = default);
-    Task UpdateAsync(int id, UpdateOrderRequest request, CancellationToken ct = default);
-}
-
-public class OrderService : IOrderService
-{
-    private readonly AppDbContext _context;
-    private readonly ILogger<OrderService> _logger;
-
-    public OrderService(AppDbContext context, ILogger<OrderService> logger)
-    {
-        _context = context;
-        _logger = logger;
-    }
-
-    public async Task<List<OrderDto>> GetAllAsync(CancellationToken ct = default)
-    {
-        return await _context.Orders
-            .Include(o => o.Customer)
-            .OrderByDescending(o => o.CreatedAt)
-            .Select(o => new OrderDto
-            {
-                Id = o.Id,
-                OrderNumber = o.OrderNumber,
-                CustomerName = o.Customer.Name,
-                Total = o.Total,
-                Status = o.Status.ToString()
-            })
-            .ToListAsync(ct);
-    }
-
-    public async Task<OrderDto> CreateAsync(CreateOrderRequest request, CancellationToken ct = default)
-    {
-        var order = Order.Create(request.CustomerId, request.Items);
-
-        _context.Orders.Add(order);
-        await _context.SaveChangesAsync(ct);
-
-        _logger.LogInformation("Order {OrderNumber} created", order.OrderNumber);
-
-        return new OrderDto { /* map */ };
-    }
-}
-```
-
----
-
-## 🎨 UI Component Libraries
-
-### Recomendação para Projetos AI-First
-
-| Biblioteca | Quando Usar | Vantagens | Desvantagens |
-|------------|-------------|-----------|--------------|
-| **Fluent UI** ⭐ | Projetos AI-first, Micro-SaaS | Componentes AI nativos, Microsoft integration, Performance (~200KB) | Menos componentes prontos |
-| **MudBlazor** | SaaS tradicional, Analytics pesados | 140+ componentes, Charts nativos, Templates prontos | Mais pesado (~500KB), Sem componentes AI |
-| **Híbrido** | SaaS complexo com AI | Melhor dos dois mundos | Maior bundle size (~350KB) |
-
-### Fluent UI Blazor (Recomendado)
-
-**Para:**
-- Projetos com AI agents/chat
-- Integração com Microsoft Agent Framework
-- Produtos com UX Copilot-like
-- Micro-SaaS que priorizam performance
-
-**Setup rápido:**
-```bash
-dotnet add package Microsoft.FluentUI.AspNetCore.Components
-```
-
-```csharp
-// Program.cs
-builder.Services.AddFluentUIComponents();
-```
-
-**Exemplo de Chat AI:**
-```razor
-<FluentMessageBar Intent="MessageIntent.Success">
-    <FluentLabel Weight="FontWeight.Bold">AI Assistant</FluentLabel>
-    <FluentLabel>@_aiResponse</FluentLabel>
-</FluentMessageBar>
-```
-
-**Guia completo:** [Fluent UI Setup](../../.morph/standards/fluent-ui-setup.md)
-
-### MudBlazor (Complemento)
-
-**Para:**
-- Grids complexos com filtros avançados
-- Charts e dashboards analytics
-- Componentes que Fluent UI não tem
-
-**Setup:**
-```bash
-dotnet add package MudBlazor
-```
-
-**Exemplo de Grid Avançado:**
-```razor
-<MudDataGrid T="Order" Items="@_orders"
-             Filterable="true"
-             Groupable="true"
-             Dense="true">
-    <Columns>
-        <PropertyColumn Property="x => x.OrderNumber" />
-        <PropertyColumn Property="x => x.Total" Format="C2" />
-    </Columns>
-</MudDataGrid>
-```
-
-### Abordagem Híbrida
-
-**Quando usar:**
-- SaaS com AI + analytics complexos
-- Dashboards com charts + chat AI
-- Aplicações enterprise completas
-
-**Pattern:**
-- **Base:** Fluent UI (layout, navegação, AI)
-- **Complemento:** MudBlazor (grids, charts)
-
-```razor
-<FluentLayout>
-    <FluentHeader>...</FluentHeader>
-    <FluentMain>
-        @* Grid complexo *@
-        <MudDataGrid ... />
-
-        @* Chat AI *@
-        <FluentMessageBar>AI response</FluentMessageBar>
-    </FluentMain>
-</FluentLayout>
-```
-
----
-
-## 🎯 Novas Features .NET 10
-
-### State Persistence
-
-**Novo:** Propriedades com `[PersistentState]` são persist idas automaticamente.
-
-```razor
-@page "/counter"
-
-<button @onclick="Increment">Count: @Count</button>
-
-@code {
-    // Persiste automaticamente em pre-rendering e circuit disconnections
-    [PersistentState]
-    private int Count { get; set; } = 0;
-
-    private void Increment() => Count++;
-}
-```
-
-**Quando usar:**
-- Componentes com estado que precisam sobreviver a pre-rendering
-- Aplicações com circuit disconnections frequentes
-- Formulários multi-step
-
-**Não usar para:**
-- Dados sensíveis (passwords, tokens)
-- Estado que deve ser recalculado (derived state)
-
-### Circuit Pause/Resume
-
-**Novo:** APIs JavaScript para pausar/resumir circuits.
-
-```razor
-@inject IJSRuntime JS
-
-@code {
-    protected override async Task OnAfterRenderAsync(bool firstRender)
-    {
-        if (firstRender)
-        {
-            await JS.InvokeVoidAsync("setupCircuitManagement");
-        }
-    }
-}
-```
-
-```javascript
-// wwwroot/app.js
-function setupCircuitManagement() {
-    // Pausar quando usuário minimiza/troca de aba
-    document.addEventListener('visibilitychange', () => {
-        if (document.hidden) {
-            Blazor.pauseCircuit();  // Libera recursos do servidor
-        } else {
-            Blazor.resumeCircuit(); // Restaura estado
-        }
-    });
-}
-```
-
-**Benefícios:**
-- Reduz uso de memória do servidor
-- Melhora escalabilidade
-- Estado mantido durante pausa
-
-### Blazor Metrics & Observability
-
-**Novo:** Métricas específicas de Blazor Server.
-
-```csharp
-// Program.cs
-builder.Services.AddOpenTelemetry()
-    .WithTracing(tracing =>
-    {
-        tracing.AddSource("Microsoft.AspNetCore.Components.Server");
-        tracing.AddAspireTracing();
-    })
-    .WithMetrics(metrics =>
-    {
-        metrics.AddMeter("Microsoft.AspNetCore.Components.Server");
-        metrics.AddAspireMetrics();
-    });
-```
-
-**Métricas disponíveis:**
-- Page navigations (por rota/componente)
-- UI events (eventos e duração)
-- Component lifecycle (render diff sizes)
-- Active circuits (usuários simultâneos)
-- Circuit state (connected/disconnected)
-
-**Visualização:** Aspire Dashboard integrado.
-
-### Hot Reload Aprimorado
-
-**Automático:** 10x mais rápido no Visual Studio 2026.
-
-**Nada a fazer:** Apenas use VS 2026 Preview ou `dotnet watch`.
-
-### Formulários com Validação Aninhada
-
-**Novo:** Validação automática de modelos aninhados.
-
-```csharp
-public class Order
-{
-    [Required]
-    public string OrderNumber { get; set; } = null!;
-
-    // Modelo aninhado - validado automaticamente
-    public Customer Customer { get; set; } = new();
-    public List<OrderItem> Items { get; set; } = new();
-}
-
-public class Customer
-{
-    [Required]
-    public string Name { get; set; } = null!;
-
-    [EmailAddress]
-    public string Email { get; set; } = null!;
-
-    // Aninhamento profundo - também validado
-    public Address ShippingAddress { get; set; } = new();
-}
-```
-
-```razor
-<EditForm Model="@_order" OnValidSubmit="HandleSubmit">
-    <DataAnnotationsValidator />
-    <ValidationSummary />
-    <!-- Campos... -->
-</EditForm>
-```
-
-**Configuração (Program.cs):**
-```csharp
-builder.Services.AddValidation(); // Habilita validação aninhada
-```
-
----
-
-## 📚 Documentação de Referência
-
-- [Blazor Documentation](https://learn.microsoft.com/aspnet/core/blazor/)
-- [Entity Framework Core 10](https://learn.microsoft.com/ef/core/)
-- [ASP.NET Core 10](https://learn.microsoft.com/aspnet/core/)
-- [Hangfire](https://docs.hangfire.io/)
-- **[Passkeys/WebAuthn](../../.morph/standards/passkeys-auth.md)**
-- **[Agent Framework](../../.morph/standards/agent-framework-setup.md)**
-
-## Checklist de Projeto
-
-- [ ] Estrutura de camadas (Domain, Application, Infrastructure, Web)
-- [ ] EF Core configurado com migrations
-- [ ] Blazor Server com componentes reutilizáveis
-- [ ] Services com injeção de dependência
-- [ ] Logging estruturado
-- [ ] Validação com FluentValidation ou DataAnnotations
-- [ ] Hangfire para background jobs
-- [ ] Dockerfile para containerização
-
----
-
-*MORPH-SPEC by Polymorphism Tech*
+# .NET + Blazor Stack
+
+Stack principal para aplicações web com .NET e Blazor Server.
+
+| Aspecto | Tecnologia |
+|---------|------------|
+| **Backend** | .NET 10 / C# 14 |
+| **Frontend** | Blazor Server |
+| **Database** | EF Core 10 + Azure SQL |
+| **Hosting** | Azure Container Apps |
+| **Background** | Hangfire |
+| **AI** | Microsoft Agent Framework |
+
+**Triggers:** `blazor`, `razor`, `server-side`, `.net`, `csharp`, `dotnet`
+
+---
+
+## Critical Standards (Read FIRST)
+
+| Standard | What |
+|----------|------|
+| `framework/standards/coding.md` | **C# naming conventions, code style, .editorconfig template** |
+| `framework/standards/architecture.md` | **Clean Architecture layers, SOLID, service patterns** |
+| `framework/standards/blazor-efcore.md` | DbContext concurrency, Repository Factory, background ops, migrations |
+| `framework/standards/blazor-pitfalls.md` | Common Blazor issues & solutions |
+| `framework/standards/fluent-ui-blazor.md` | Fluent UI APIs, icon sizes, dialog patterns |
+| `framework/standards/blazor-lifecycle.md` | Component lifecycle patterns |
+| `framework/standards/program-cs-checklist.md` | Required Program.cs setup |
+
+### Quick Checklist
+- [ ] Background ops: Use `IDbContextFactory` / Repository Factory (ref: blazor-efcore.md)
+- [ ] JSRuntime: ONLY in `OnAfterRenderAsync(firstRender)`
+- [ ] Program.cs: `UseStaticFiles()` BEFORE `UseAntiforgery()`
+- [ ] File Upload: Specify `maxAllowedSize` in `OpenReadStream()`
+- [ ] RenderMode: NO `@rendermode` on MainLayout
+- [ ] Package Versions: MudBlazor >= 8.15.0 for .NET 10
+
+---
+
+## Mandatory Code Patterns
+
+### Status Validation
+
+```csharp
+// ✅ Validate INVALID states (allows future extensions)
+if (order.Status >= OrderStatus.Completed || order.Status == OrderStatus.Failed)
+    throw new InvalidOperationException("Cannot process completed or failed order");
+
+// ❌ Never assume single valid flow
+if (order.Status != OrderStatus.PendingPayment)
+    throw new InvalidOperationException("Invalid status");
+```
+
+### Enums with Logical Order
+
+```csharp
+public enum OrderStatus
+{
+    Created = 0, PendingPayment = 1, Processing = 2, Completed = 3,  // Normal flow
+    Failed = 100, Cancelled = 101, Refunded = 102                    // Error states (high values)
+}
+```
+
+### Service Pattern
+
+```csharp
+public async Task<Result<Order>> ProcessAsync(Guid orderId, CancellationToken ct)
+{
+    _logger.LogInformation("Processing order {OrderId}", orderId);
+    var order = await _repository.GetByIdAsync(orderId, ct);
+    if (order == null) return Result.Failure<Order>("Order not found");
+    if (order.Status >= OrderStatus.Completed)
+        return Result.Failure<Order>("Order already completed");
+    // ... process ...
+    return Result.Success(order);
+}
+```
+
+**Rules:** Logging at critical points, CancellationToken propagated, Result pattern for business errors, exceptions for infrastructure.
+
+**More patterns:** See `code-review.md` for DTOs/contracts naming and service checklists.
+
+---
+
+## Project Structure
+
+```
+src/
+├── {App}.Domain/          # Entities, Value Objects, Enums, Exceptions
+├── {App}.Application/     # Services, DTOs, Interfaces, Validators
+├── {App}.Infrastructure/  # EF Core (DbContext, Configs, Migrations), External Services
+├── {App}.Web/             # Blazor Server (Program.cs, Components, Pages, wwwroot)
+└── tests/                 # UnitTests, IntegrationTests
+```
+
+### Program.cs Essentials
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddRazorComponents().AddInteractiveServerComponents();
+builder.Services.AddDbContext<AppDbContext>(o => o.UseSqlServer(connString));
+builder.Services.AddDbContextFactory<AppDbContext>(o => o.UseSqlServer(connString));
+// Register services, factories, Hangfire...
+
+var app = builder.Build();
+app.UseHttpsRedirection();
+app.UseStaticFiles();     // BEFORE UseAntiforgery!
+app.UseAntiforgery();
+app.MapRazorComponents<App>().AddInteractiveServerRenderMode();
+app.Run();
+```
+
+---
+
+## Blazor Component Patterns
+
+### Page with List
+
+```razor
+@page "/orders"
+@inject IOrderService OrderService
+
+@if (_orders is null) { <Loading /> }
+else if (!_orders.Any()) { <EmptyState Message="No orders found" /> }
+else
+{
+    @foreach (var order in _orders)
+    {
+        <FluentCard>@order.OrderNumber - @order.Total.ToString("C")</FluentCard>
+    }
+}
+
+@code {
+    private List<OrderDto>? _orders;
+    protected override async Task OnInitializedAsync()
+        => _orders = await OrderService.GetAllAsync();
+}
+```
+
+### Form with Validation
+
+```razor
+@page "/orders/new"
+<EditForm Model="_model" OnValidSubmit="HandleSubmit">
+    <DataAnnotationsValidator />
+    <InputSelect @bind-Value="_model.CustomerId">...</InputSelect>
+    <ValidationMessage For="() => _model.CustomerId" />
+    <button type="submit" disabled="@_isSubmitting">Save</button>
+</EditForm>
+```
+
+---
+
+## UI Libraries
+
+> **Decision matrix:** See `ui-ux-designer.md` skill for full comparison.
+
+| Library | When | Key Advantage |
+|---------|------|---------------|
+| **Fluent UI** | AI-first, Microsoft stack | Performance (~200KB), AI components |
+| **MudBlazor** | Complex dashboards | 140+ components, charts |
+| **Hybrid** | SaaS with AI + analytics | Best of both |
+
+---
+
+## .NET 10 Features
+
+### PersistentState (new)
+```razor
+@code {
+    [PersistentState]
+    private int Count { get; set; } = 0;  // Survives pre-rendering & circuit disconnections
+}
+```
+
+### Circuit Pause/Resume (new)
+```javascript
+document.addEventListener('visibilitychange', () => {
+    document.hidden ? Blazor.pauseCircuit() : Blazor.resumeCircuit();
+});
+```
+
+### Nested Model Validation (new)
+```csharp
+builder.Services.AddValidation(); // Enables automatic nested model validation
+```
+
+### Blazor Metrics
+```csharp
+builder.Services.AddOpenTelemetry()
+    .WithTracing(t => t.AddSource("Microsoft.AspNetCore.Components.Server"))
+    .WithMetrics(m => m.AddMeter("Microsoft.AspNetCore.Components.Server"));
+```
+
+---
+
+## Project Checklist
+
+- [ ] Clean Architecture layers (Domain, Application, Infrastructure, Web)
+- [ ] EF Core with migrations + IDbContextFactory
+- [ ] Repository Factory for background ops (ref: blazor-efcore.md)
+- [ ] Blazor Server with reusable components
+- [ ] Services with DI + structured logging
+- [ ] Validation (FluentValidation or DataAnnotations)
+- [ ] Hangfire for background jobs
+- [ ] Dockerfile for containerization
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*