@saulwade/swl-ses 1.0.0

package/habilidades/csharp-patrones/SKILL.md

@@ -0,0 +1,316 @@
+---
+name: csharp-patrones
+description: >
+  Patrones C# modernos: records para CQRS, MediatR, Result<T> pattern,
+  Specification pattern, Unit of Work, Channel<T>, Polly y discriminated
+  unions con OneOf. Cargar cuando se diseñe arquitectura .NET, se implemente
+  CQRS/Mediator, o se necesite manejo robusto de errores sin excepciones.
+version: "1.0.0"
+herramientasPermitidas: [Read, Glob, Grep]
+exclusiones:
+  - "No cargar para implementar endpoints ASP.NET Core, EF Core o Background Services — para implementación cargar `csharp-experto`."
+  - "No cargar para escribir tests C# — para testing cargar `csharp-testing`."
+  - "No cargar para errores de compilación C# — para build errors cargar `build-errors-csharp`."
+  - "No cargar para patrones de diseño GoF genéricos sin contexto C# — este skill cubre patrones idiomáticos de C# moderno como CQRS con records, Result<T> y MediatR."
+evolvable: true  # default para skill estandar
+---
+# C# Patrones — CQRS, Result, MediatR y Más
+
+## Cuándo NO cargar
+
+- La pregunta es sobre implementar endpoints ASP.NET Core, EF Core o Background Services — para implementación concreta cargar `csharp-experto`.
+- La tarea es escribir tests C# — cargar `csharp-testing`.
+- Los errores son de compilación C# — cargar `build-errors-csharp`.
+- La discusión es sobre patrones GoF genéricos (Singleton, Observer) sin contexto C# — este skill cubre patrones idiomáticos de C# moderno como CQRS con records, Result<T> y MediatR.
+
+## CQRS con Records y MediatR
+
+```csharp
+// Command — estado mutable del sistema
+public record CrearFacturaCommand(
+    Guid EmpresaId,
+    string Folio,
+    List<ItemCommand> Items) : IRequest<Result<FacturaDto>>;
+
+// Query — solo lectura, sin efectos secundarios
+public record ObtenerFacturasQuery(
+    Guid EmpresaId,
+    int Pagina = 1,
+    int TamanoPagina = 20) : IRequest<Result<PaginaDto<FacturaDto>>>;
+
+// Handler de Command
+public class CrearFacturaHandler(
+    IFacturasRepository repo,
+    IUnitOfWork uow,
+    ILogger<CrearFacturaHandler> logger)
+    : IRequestHandler<CrearFacturaCommand, Result<FacturaDto>>
+{
+    public async Task<Result<FacturaDto>> Handle(
+        CrearFacturaCommand req, CancellationToken ct)
+    {
+        if (await repo.ExisteFolioAsync(req.EmpresaId, req.Folio, ct))
+            return Result.Failure<FacturaDto>(
+                Error.Conflicto("Facturas.FolioDuplicado", $"El folio {req.Folio} ya existe"));
+
+        var factura = Factura.Crear(req.EmpresaId, req.Folio, req.Items);
+        await repo.AgregarAsync(factura, ct);
+        await uow.GuardarCambiosAsync(ct);
+
+        logger.LogInformation("Factura {Folio} creada para empresa {EmpresaId}",
+            req.Folio, req.EmpresaId);
+        return Result.Success(FacturaDto.Desde(factura));
+    }
+}
+```
+
+---
+
+## Result<T> Pattern — Sin excepciones para flujo de control
+
+```csharp
+public class Result<T>
+{
+    private Result(T? valor, bool exitoso, Error error)
+    {
+        Valor = valor;
+        EsExitoso = exitoso;
+        Error = error;
+    }
+
+    public T? Valor { get; }
+    public bool EsExitoso { get; }
+    public bool EsFallido => !EsExitoso;
+    public Error Error { get; }
+
+    public static Result<T> Success(T valor) =>
+        new(valor, true, Error.Ninguno);
+
+    public static Result<T> Failure(Error error) =>
+        new(default, false, error);
+}
+
+public static class Result
+{
+    public static Result<T> Success<T>(T valor) => Result<T>.Success(valor);
+    public static Result<T> Failure<T>(Error error) => Result<T>.Failure(error);
+}
+
+public record Error(string Codigo, string Descripcion)
+{
+    public static readonly Error Ninguno = new("", "");
+    public static Error NoEncontrado(string entidad, Guid id) =>
+        new($"{entidad}.NoEncontrado", $"{entidad} con id {id} no existe");
+    public static Error Conflicto(string codigo, string desc) => new(codigo, desc);
+    public static Error Validacion(string campo, string mensaje) =>
+        new($"Validacion.{campo}", mensaje);
+}
+
+// Uso en endpoint — mapear Result a HTTP
+static async Task<IResult> Crear(
+    CrearFacturaCommand cmd,
+    ISender mediator,
+    CancellationToken ct)
+{
+    var resultado = await mediator.Send(cmd, ct);
+    return resultado switch
+    {
+        { EsExitoso: true } => TypedResults.Created($"/facturas/{resultado.Valor!.Id}", resultado.Valor),
+        { Error.Codigo: var c } when c.StartsWith("Validacion") => TypedResults.BadRequest(resultado.Error),
+        { Error.Codigo: var c } when c.EndsWith("Duplicado") => TypedResults.Conflict(resultado.Error),
+        _ => TypedResults.Problem("Error interno")
+    };
+}
+```
+
+---
+
+## Specification Pattern
+
+```csharp
+public abstract class Specification<T>
+{
+    public abstract Expression<Func<T, bool>> Criterio { get; }
+
+    public Specification<T> And(Specification<T> otra) =>
+        new SpecificacionAnd<T>(this, otra);
+
+    public Specification<T> Or(Specification<T> otra) =>
+        new SpecificacionOr<T>(this, otra);
+}
+
+public class FacturasPorEmpresaSpec : Specification<Factura>
+{
+    private readonly Guid _empresaId;
+    public FacturasPorEmpresaSpec(Guid empresaId) => _empresaId = empresaId;
+
+    public override Expression<Func<Factura, bool>> Criterio =>
+        f => f.EmpresaId == _empresaId;
+}
+
+public class FacturasPendientesSpec : Specification<Factura>
+{
+    public override Expression<Func<Factura, bool>> Criterio =>
+        f => f.Estatus == "pendiente";
+}
+
+// Uso compuesto
+var spec = new FacturasPorEmpresaSpec(empresaId)
+    .And(new FacturasPendientesSpec());
+
+var facturas = await _db.Facturas
+    .Where(spec.Criterio)
+    .ToListAsync(ct);
+```
+
+---
+
+## Unit of Work con EF Core
+
+```csharp
+public interface IUnitOfWork
+{
+    Task<int> GuardarCambiosAsync(CancellationToken ct = default);
+}
+
+// AppDbContext implementa IUnitOfWork directamente
+public class AppDbContext : DbContext, IUnitOfWork
+{
+    public Task<int> GuardarCambiosAsync(CancellationToken ct = default) =>
+        SaveChangesAsync(ct);
+}
+
+// Registro — mismo DbContext resuelve ambas interfaces
+builder.Services.AddDbContext<AppDbContext>(...);
+builder.Services.AddScoped<IUnitOfWork>(sp =>
+    sp.GetRequiredService<AppDbContext>());
+```
+
+---
+
+## Channel<T> — Pipelines async
+
+```csharp
+// Productor/consumidor sin bloqueo de thread
+public class ColaProcesamiento<T>
+{
+    private readonly Channel<T> _canal = Channel.CreateBounded<T>(
+        new BoundedChannelOptions(1000)
+        {
+            FullMode = BoundedChannelFullMode.Wait,
+            SingleReader = false,
+            SingleWriter = false
+        });
+
+    public ChannelWriter<T> Escritor => _canal.Writer;
+    public ChannelReader<T> Lector => _canal.Reader;
+}
+
+// Productor
+await _cola.Escritor.WriteAsync(nuevoElemento, ct);
+
+// Consumidor en BackgroundService
+await foreach (var elemento in _cola.Lector.ReadAllAsync(stoppingToken))
+{
+    await ProcesarAsync(elemento, stoppingToken);
+}
+```
+
+---
+
+## Polly — Resiliencia
+
+```csharp
+// Pipeline de resiliencia para llamadas HTTP externas
+var pipeline = new ResiliencePipelineBuilder<HttpResponseMessage>()
+    .AddRetry(new RetryStrategyOptions<HttpResponseMessage>
+    {
+        MaxRetryAttempts = 3,
+        Delay = TimeSpan.FromSeconds(1),
+        BackoffType = DelayBackoffType.Exponential,
+        ShouldHandle = new PredicateBuilder<HttpResponseMessage>()
+            .Handle<HttpRequestException>()
+            .HandleResult(r => r.StatusCode >= HttpStatusCode.InternalServerError)
+    })
+    .AddCircuitBreaker(new CircuitBreakerStrategyOptions<HttpResponseMessage>
+    {
+        FailureRatio = 0.5,
+        MinimumThroughput = 10,
+        BreakDuration = TimeSpan.FromSeconds(30)
+    })
+    .AddTimeout(TimeSpan.FromSeconds(10))
+    .Build();
+
+// Registro con HttpClient
+builder.Services.AddHttpClient<ISatClient, SatClient>()
+    .AddResilienceHandler("sat-pipeline", b => b.AddPipeline(pipeline));
+```
+
+---
+
+## OneOf — Discriminated Unions
+
+```csharp
+// dotnet add package OneOf
+public class FacturasService
+{
+    public async Task<OneOf<FacturaDto, NotFound, ValidationError>> ObtenerAsync(
+        Guid id, CancellationToken ct)
+    {
+        var factura = await _repo.ObtenerAsync(id, ct);
+        if (factura is null) return new NotFound();
+        return FacturaDto.Desde(factura);
+    }
+}
+
+// Uso exhaustivo en endpoint
+var resultado = await svc.ObtenerAsync(id, ct);
+return resultado.Match(
+    dto => TypedResults.Ok(dto),
+    _ => TypedResults.NotFound(),
+    error => TypedResults.BadRequest(error.Mensajes)
+);
+```
+
+---
+
+## Anti-patrones
+
+### Excepciones para flujo de control — NUNCA
+
+```csharp
+// MAL — las excepciones son costosas y ocultan la intención
+throw new NotFoundException($"Factura {id} no encontrada");
+
+// BIEN — Result o OneOf expresan el caso esperado
+return Result.Failure<FacturaDto>(Error.NoEncontrado("Factura", id));
+```
+
+### Service Locator — NUNCA
+
+```csharp
+// MAL — oculta dependencias, imposible de testear
+var svc = _serviceProvider.GetService<IFacturasService>();
+
+// BIEN — inyectar en el constructor
+public class Handler(IFacturasService svc) { }
+```
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+**MediatR con `IPipelineBehavior` registrado después del handler no se ejecuta en el orden correcto**: el orden de registro de behaviors en el DI container determina el orden de ejecución de la pipeline. Un behavior de validación registrado después del behavior de logging ejecuta después, no antes. Fix: registrar los behaviors en orden explícito: primero logging, luego validación, luego el handler — o usar `OrderedPipelineBehavior` si el orden debe ser determinístico independiente del registro.
+
+**`Result<T>` implementado con un `bool Success` y un `T Value` permite acceder a `Value` cuando `Success = false`**: si el tipo `Result<T>` no protege el acceso al valor cuando el resultado es error, el código que consume el resultado puede usar `result.Value` sin verificar `result.Success`. Fix: hacer que `Value` lance una excepción si se accede cuando `IsError` es true, o usar un patrón match que fuerce el manejo de ambos casos.
+
+**`Channel<T>` sin capacidad fija (`Channel.CreateUnbounded()`) puede crecer sin límite bajo presión**: si el productor es más rápido que el consumidor, el canal acumula mensajes en memoria hasta agotar RAM. Fix: usar `Channel.CreateBounded(capacity)` con una capacidad razonable y manejar `ChannelWriter.TryWrite()` retornando `false` (canal lleno) con backpressure.
+
+**Polly `WaitAndRetry` con la misma instancia de `HttpClient` no reintenta si el HttpMessageHandler tiene su propio timeout**: si el `HttpClient` tiene `Timeout = TimeSpan.FromSeconds(5)` y Polly tiene 3 reintentos, el `TaskCanceledException` del timeout interno del cliente se lanza antes del segundo intento y no es capturado por Polly. Fix: deshabilitar el timeout del `HttpClient` (`Timeout = InfiniteTimeSpan`) y configurar el timeout a través de Polly con `TimeoutPolicy`.
+
+## Checklist de arquitectura
+
+- [ ] Commands y Queries son records inmutables
+- [ ] Handlers retornan Result<T>, no lanzan excepciones para casos esperados
+- [ ] Unit of Work hace SaveChanges, no los repositorios
+- [ ] Polly configurado para todas las llamadas HTTP externas
+- [ ] Sin Service Locator (IServiceProvider en código de negocio)

package/habilidades/csharp-testing/SKILL.md

@@ -0,0 +1,286 @@
+---
+name: csharp-testing
+description: >
+  Testing C# con xUnit, NSubstitute, FluentAssertions y WebApplicationFactory.
+  Cubre IAsyncLifetime, TestContainers, Bogus para datos falsos, coverlet y
+  snapshot testing con Verify. Cargar cuando se escriban tests en .NET o se
+  configure el pipeline de testing para proyectos C#.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep]
+exclusiones:
+  - "No cargar para implementar el código C# de producción — primero implementar con `csharp-experto`, luego escribir tests."
+  - "No cargar para diseñar patrones C# (CQRS, MediatR, Result<T>) — para diseño cargar `csharp-patrones`."
+  - "No cargar para errores de compilación C# en los tests — para build errors cargar `build-errors-csharp`."
+  - "No cargar para tests de carga o rendimiento — NUnit/xUnit con Benchmark.NET requieren configuración distinta no cubierta en este skill."
+evolvable: true  # default para skill estandar
+---
+# C# Testing — xUnit, NSubstitute, FluentAssertions
+
+## Cuándo NO cargar
+
+- El código C# de producción aún no existe — primero implementar con `csharp-experto`, luego escribir tests.
+- La pregunta es sobre diseñar patrones C# (CQRS, MediatR) — cargar `csharp-patrones`.
+- Los errores son de compilación C# en los archivos de test — cargar `build-errors-csharp`.
+- La pregunta es sobre tests de carga o rendimiento con BenchmarkDotNet — no está cubierto en este skill.
+
+## Lifecycle de xUnit
+
+```csharp
+// IAsyncLifetime para setup/teardown async
+public class FacturasServiceTests : IAsyncLifetime
+{
+    private AppDbContext _db = null!;
+
+    public async Task InitializeAsync()
+    {
+        // Se ejecuta antes del primer test de la clase
+        _db = await TestDbContextFactory.CreateAsync();
+    }
+
+    public async Task DisposeAsync()
+    {
+        await _db.DisposeAsync();
+    }
+}
+
+// IClassFixture<T> — fixture compartido entre todos los tests de la clase
+// Solo para recursos costosos de inicializar (contenedor de BD, servidor HTTP)
+public class IntegrationTests(WebAppFixture fixture)
+    : IClassFixture<WebAppFixture>
+{
+    private readonly HttpClient _client = fixture.Client;
+}
+```
+
+---
+
+## Naming — Should_When
+
+```
+NombreMetodo_Debe_ResultadoEsperado_CuandoCondicion
+Ej: Crear_DebeRetornarFactura_CuandoDatosValidos
+    Crear_DebeLanzarValidacion_CuandoFolioVacio
+    ObtenerTodas_DebeRetornarVacia_CuandoNoHayFacturas
+```
+
+---
+
+## NSubstitute — Mocks
+
+```csharp
+// Crear sustituto
+var repo = Substitute.For<IFacturasRepository>();
+
+// Configurar respuesta
+repo.ObtenerAsync(Arg.Any<Guid>(), Arg.Any<CancellationToken>())
+    .Returns(new Factura { Id = Guid.NewGuid(), Folio = "F-001" });
+
+// Configurar respuesta async con Task
+repo.CrearAsync(Arg.Any<Factura>())
+    .Returns(Task.FromResult(new Factura()));
+
+// Verificar llamada
+await repo.Received(1).ObtenerAsync(
+    Arg.Is<Guid>(id => id == facturaId),
+    Arg.Any<CancellationToken>());
+
+// Verificar que NO se llamó
+repo.DidNotReceive().EliminarAsync(Arg.Any<Guid>());
+
+// Capturar argumento
+Factura? facturaCapturada = null;
+await repo.CrearAsync(Arg.Do<Factura>(f => facturaCapturada = f));
+```
+
+---
+
+## FluentAssertions
+
+```csharp
+// Objetos
+resultado.Should().NotBeNull();
+resultado.Should().BeOfType<FacturaDto>();
+resultado.Id.Should().Be(esperadoId);
+
+// Colecciones
+facturas.Should().HaveCount(3);
+facturas.Should().Contain(f => f.Folio == "F-001");
+facturas.Should().BeInAscendingOrder(f => f.FechaEmision);
+facturas.Should().AllSatisfy(f => f.EmpresaId.Should().Be(empresaId));
+
+// Excepciones
+var act = async () => await svc.CrearAsync(null!);
+await act.Should().ThrowAsync<ArgumentNullException>()
+    .WithMessage("*factura*");
+
+// Strings
+mensaje.Should().StartWith("Error").And.Contain("validación");
+
+// Fechas
+factura.FechaEmision.Should().BeCloseTo(DateTime.UtcNow, TimeSpan.FromSeconds(5));
+```
+
+---
+
+## WebApplicationFactory — Tests de integración
+
+```csharp
+public class WebAppFixture : WebApplicationFactory<Program>, IAsyncLifetime
+{
+    private readonly PostgreSqlContainer _pg = new PostgreSqlBuilder()
+        .WithImage("postgres:16-alpine")
+        .Build();
+
+    protected override void ConfigureWebHost(IWebHostBuilder builder)
+    {
+        builder.ConfigureTestServices(services =>
+        {
+            // Reemplazar DbContext con la BD del contenedor
+            services.RemoveAll<DbContextOptions<AppDbContext>>();
+            services.AddDbContext<AppDbContext>(o =>
+                o.UseNpgsql(_pg.GetConnectionString()));
+        });
+    }
+
+    public async Task InitializeAsync()
+    {
+        await _pg.StartAsync();
+        // Aplicar migraciones a la BD de test
+        using var scope = Services.CreateScope();
+        var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
+        await db.Database.MigrateAsync();
+    }
+
+    public new async Task DisposeAsync()
+    {
+        await _pg.StopAsync();
+    }
+}
+
+// Uso en test
+public class FacturasApiTests(WebAppFixture fixture)
+    : IClassFixture<WebAppFixture>
+{
+    [Fact]
+    public async Task PostFactura_Debe201_CuandoDatosValidos()
+    {
+        var client = fixture.CreateClient();
+        var body = new { Folio = "F-001", EmpresaId = Guid.NewGuid() };
+
+        var response = await client.PostAsJsonAsync("/api/v1/facturas", body);
+
+        response.StatusCode.Should().Be(HttpStatusCode.Created);
+        var dto = await response.Content.ReadFromJsonAsync<FacturaDto>();
+        dto!.Folio.Should().Be("F-001");
+    }
+}
+```
+
+---
+
+## Bogus — Datos falsos
+
+```csharp
+// Centralizar factories en Tests/Factories/
+public static class FacturaFaker
+{
+    private static readonly Faker<Factura> _faker = new Faker<Factura>("es")
+        .RuleFor(f => f.Id, f => f.Random.Guid())
+        .RuleFor(f => f.Folio, f => $"F-{f.Random.Int(1, 999):D3}")
+        .RuleFor(f => f.Total, f => f.Finance.Amount(100, 50000))
+        .RuleFor(f => f.FechaEmision, f => f.Date.Recent(30))
+        .RuleFor(f => f.Estatus, f => f.PickRandom("borrador", "emitida"));
+
+    public static Factura Generar() => _faker.Generate();
+    public static List<Factura> GenerarLista(int n = 5) => _faker.Generate(n);
+}
+```
+
+---
+
+## Coverlet — Configuración
+
+```xml
+<!-- MiApi.Tests.csproj -->
+<PackageReference Include="coverlet.collector" Version="6.*" />
+<PackageReference Include="coverlet.msbuild" Version="6.*" />
+```
+
+```bash
+# Ejecutar con cobertura mínima 80%
+dotnet test --collect:"XPlat Code Coverage" \
+  /p:Threshold=80 \
+  /p:ThresholdType=line \
+  /p:ExcludeByAttribute="GeneratedCodeAttribute"
+
+# Generar reporte HTML
+reportgenerator -reports:"**/coverage.cobertura.xml" \
+                -targetdir:"coveragereport" -reporttypes:Html
+```
+
+---
+
+## Verify — Snapshot Testing
+
+```csharp
+// Útil para DTOs complejos, HTML generado, respuestas de API
+[Fact]
+public async Task ObtenerReporte_DebeMatchSnapshot()
+{
+    var reporte = await _svc.GenerarReporteAsync(empresaId);
+
+    // Primera ejecución: crea el archivo .verified.txt
+    // Siguientes: compara contra el snapshot
+    await Verify(reporte)
+        .ScrubMember<ReporteDto>(r => r.FechaGeneracion); // excluir campos volátiles
+}
+```
+
+---
+
+## Anti-patrones
+
+### Sleep en tests — NUNCA
+
+```csharp
+// MAL — flaky e innecesario
+await Task.Delay(1000);
+Assert.True(resultado.Procesado);
+
+// BIEN — usar Polly o un mecanismo de espera explícito
+await Policy.Handle<AssertionException>()
+            .WaitAndRetryAsync(5, _ => TimeSpan.FromMilliseconds(200))
+            .ExecuteAsync(async () =>
+            {
+                var r = await _svc.ObtenerAsync(id);
+                r.Procesado.Should().BeTrue();
+            });
+```
+
+### Tests que dependen del orden — NUNCA
+
+```csharp
+// MAL — test 2 asume que test 1 ya insertó datos
+// BIEN — cada test crea sus propios datos con Bogus/factories
+```
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+**`WebApplicationFactory` con `IClassFixture<T>` comparte el servidor entre todos los tests de la clase — los datos de un test contaminan el siguiente**: el servidor y la BD del `WebApplicationFactory` son compartidos dentro de un `IClassFixture`. Si un test crea una entidad, el siguiente test la puede encontrar. Fix: usar `IAsyncLifetime` en la clase de test para truncar tablas en `InitializeAsync`, o envolver cada test en una transacción con rollback.
+
+**NSubstitute `.Returns()` en un método que retorna `Task` sin `await` no suspende realmente el test**: `sub.ObtenerAsync().Returns(Task.FromResult(entidad))` funciona, pero `sub.ObtenerAsync().Returns(entidad)` puede no compilar o retornar un `Task` ya completado que nunca se awaita. Fix: siempre usar `.Returns(Task.FromResult(valor))` o `.Returns(x => Task.FromResult(entidad))` para métodos async en NSubstitute.
+
+**`Bogus.Faker<T>` genera los mismos valores si se crea sin semilla diferente por test**: por defecto `new Faker<T>()` usa una semilla aleatoria diferente en cada ejecución — esto hace que los tests sean no reproducibles cuando fallan. Fix: en tests que requieren reproducibilidad, usar `new Faker<T>().UseSeed(42)` con semilla fija, o guardar la semilla en el output del test fallido.
+
+**FluentAssertions `BeEquivalentTo` compara propiedades por nombre y no detecta diferencias en tipos distintos con mismos nombres**: `expected.Should().BeEquivalentTo(actual)` puede pasar aunque `expected` sea un DTO y `actual` sea la entidad, porque las propiedades homónimas coinciden. Fix: usar `.BeOfType<T>()` antes de `BeEquivalentTo` cuando se quiere verificar que el tipo exacto también coincide.
+
+## Checklist de tests
+
+- [ ] Naming sigue Should_When (o Debe_Cuando en español)
+- [ ] Sin Task.Delay/Thread.Sleep en tests
+- [ ] Cada test crea sus datos (no depende de otro test)
+- [ ] WebApplicationFactory usa TestContainers para BD real
+- [ ] Cobertura >= 80% verificada con coverlet en CI
+- [ ] Factories de datos en Tests/Factories/, no inline