swl-ses 3.3.2

package/habilidades/extractor-de-aprendizajes/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: extractor-de-aprendizajes
+description: Convertir errores y patrones descubiertos durante la implementación en nuevas habilidades o reglas. Ciclo de mejora continua del sistema SWL.
+---
+
+# Extractor de Aprendizajes
+
+## Propósito
+
+Cada error cometido durante la implementación, cada bug inesperado, cada patrón que
+funcionó mejor de lo esperado, es una oportunidad de mejorar el sistema. Este skill
+define el proceso para convertir experiencia concreta en conocimiento estructurado
+que previene errores futuros.
+
+---
+
+## El ciclo de mejora continua
+
+```
+Implementación
+     ↓
+Error / Insight descubierto
+     ↓
+Clasificar: ¿es un anti-patrón, un patrón nuevo, o una regla de proyecto?
+     ↓
+Documentar en la estructura correcta
+     ↓
+El verificador lo usa en la siguiente iteración
+     ↓
+Errores prevenidos en el futuro
+```
+
+---
+
+## Tipos de aprendizajes
+
+### Tipo 1: Anti-patrón (error a prevenir)
+
+Se descubrió algo que parece correcto pero falla en producción o en testing.
+Debe convertirse en una **regla negativa** ("NUNCA hagas X").
+
+**Indicadores**:
+- Un test falló por una razón no obvia.
+- Un bug tardó más de 30 minutos en diagnosticarse.
+- Se asumió algo sobre una librería que resultó ser incorrecto.
+
+### Tipo 2: Patrón positivo (mejor práctica)
+
+Se encontró una forma de hacer algo que resuelve un problema recurrente con
+elegancia. Debe convertirse en una **regla positiva** ("SIEMPRE usa X para Y").
+
+**Indicadores**:
+- Se refactorizó código que inicialmente era verboso y quedó mucho más limpio.
+- Una solución resolvió 3 problemas distintos a la vez.
+- El code review elogió específicamente un patrón usado.
+
+### Tipo 3: Gotcha de librería o framework
+
+El comportamiento de una dependencia no era el esperado según la documentación o
+la intuición. Debe convertirse en una **nota de advertencia** en el skill relevante.
+
+**Indicadores**:
+- "La documentación dice X pero en realidad hace Y".
+- El comportamiento cambia según la versión de la dependencia.
+- Hay una edge case no documentada.
+
+### Tipo 4: Decisión de proyecto
+
+Se tomó una decisión de arquitectura o diseño que debe respetarse en el futuro.
+Debe registrarse en **DECISIONS.md** del proyecto.
+
+---
+
+## Protocolo de extracción
+
+### Paso 1: Capturar el contexto del error
+
+Cuando se descubre un error o insight, documentarlo inmediatamente con:
+
+```markdown
+## Aprendizaje: [título corto]
+
+**Fecha**: 2026-03-25
+**Contexto**: Implementando endpoint POST /facturas en FastAPI con SQLAlchemy async.
+**Error observado**: MissingGreenlet al acceder a factura.usuario.nombre en el schema Pydantic.
+**Causa raíz**: La relación `usuario` no tenía selectinload() en el query. SQLAlchemy async
+no puede hacer lazy loading fuera de una sesión async activa.
+**Solución aplicada**: Agregar `.options(selectinload(Factura.usuario))` al query.
+**Clasificación**: Anti-patrón → Gotcha de SQLAlchemy async
+```
+
+### Paso 2: Determinar el destino del aprendizaje
+
+| Tipo de aprendizaje | Destino |
+|--------------------|---------|
+| Regla universal de Python | `habilidades/patrones-python/SKILL.md` |
+| Gotcha de FastAPI | `habilidades/fastapi-experto/SKILL.md` |
+| Gotcha de SQLAlchemy | `habilidades/fastapi-experto/SKILL.md` o `CLAUDE.md` del proyecto |
+| Regla de diseño de API | `habilidades/api-rest-diseno/SKILL.md` |
+| Regla de testing | `habilidades/testing-python/SKILL.md` |
+| Decisión de proyecto específico | `DECISIONS.md` del proyecto |
+| Regla que aplica a TODOS los proyectos | `CLAUDE.md` del sistema SWL |
+
+### Paso 3: Escribir la regla en el formato correcto
+
+#### Formato para regla negativa (anti-patrón)
+
+```markdown
+### NUNCA: [título del anti-patrón]
+
+**Problema**: Descripción clara de qué falla y por qué.
+
+```python
+# MAL — esto causa [error específico]
+query = select(Factura).where(Factura.id == factura_id)
+result = await db.execute(query)
+factura = result.scalar_one()
+# Acceder a factura.usuario aquí causa MissingGreenlet
+print(factura.usuario.nombre)
+```
+
+```python
+# BIEN — con selectinload explícito
+query = (
+    select(Factura)
+    .where(Factura.id == factura_id)
+    .options(selectinload(Factura.usuario))
+)
+result = await db.execute(query)
+factura = result.scalar_one()
+print(factura.usuario.nombre)  # Funciona correctamente
+```
+```
+
+#### Formato para regla positiva (mejor práctica)
+
+```markdown
+### SIEMPRE: [título de la mejor práctica]
+
+**Cuándo aplicar**: Descripción de la situación.
+**Beneficio**: Por qué esta forma es mejor.
+
+```python
+# Patrón correcto con ejemplo concreto
+```
+```
+
+### Paso 4: Integrar la regla al skill correspondiente
+
+1. Abrir el SKILL.md del skill donde debe vivir la regla.
+2. Agregar la regla en la sección más relevante.
+3. Si no hay sección relevante, crear una nueva sección "Gotchas y casos especiales".
+4. Hacer commit del cambio al skill con mensaje:
+   ```
+   docs(skills): agrega regla sobre selectinload en SQLAlchemy async
+   ```
+
+---
+
+## Plantilla de nuevo skill desde cero
+
+Si el aprendizaje no encaja en ningún skill existente, crear uno nuevo:
+
+```
+habilidades/
+└── nuevo-skill/
+    └── SKILL.md
+```
+
+```yaml
+---
+name: nuevo-skill
+description: Una línea describiendo cuándo activar este skill.
+---
+
+# Título del Skill
+
+## Cuándo activar
+- Caso 1 donde este skill es relevante
+- Caso 2 donde este skill es relevante
+
+## Reglas fundamentales
+
+### Regla 1
+...
+
+### Regla 2
+...
+
+## Anti-patrones
+
+### NUNCA: Anti-patrón 1
+...
+
+## Referencia rápida
+...
+```
+
+---
+
+## Indicadores de calidad de un aprendizaje bien documentado
+
+Un aprendizaje está bien documentado si:
+
+- [ ] Tiene un ejemplo de código concreto (MAL vs. BIEN).
+- [ ] La causa raíz está explicada, no solo el síntoma.
+- [ ] Es accionable: quien lo lee sabe exactamente qué hacer o no hacer.
+- [ ] Está en el skill correcto (no en un lugar genérico).
+- [ ] El título es buscable (contiene la tecnología y el patrón).
+
+---
+
+## Frecuencia de extracción
+
+| Momento | Acción |
+|---------|--------|
+| Al terminar una tarea | Revisar si hubo algún insight que documentar |
+| Al resolver un bug difícil | OBLIGATORIO documentar causa raíz y solución |
+| Al hacer code review | Documentar patrones observados |
+| Al finalizar una fase | Revisar STATE.md y DECISIONS.md, promover aprendizajes relevantes |
+| Al finalizar el proyecto | Revisar todos los aprendizajes y consolidarlos en los skills |
+
+---
+
+## Anti-patrones del proceso de extracción
+
+- **Documentar en el momento incorrecto**: Hacerlo DURANTE o inmediatamente DESPUÉS del
+  error, no días después cuando el contexto se pierde.
+- **Ser demasiado genérico**: "No cometer errores en SQLAlchemy" no es útil.
+  "NUNCA acceder a relaciones lazy en async fuera de session" sí lo es.
+- **Duplicar reglas**: Antes de agregar una regla, buscar si ya existe en el skill.
+- **No incluir ejemplo de código**: Las reglas sin código concreto se olvidan.
+- **Documentar en DECISIONS.md lo que debería estar en el skill**: Las decisiones de
+  proyecto van en DECISIONS.md; los patrones reutilizables van en skills.

package/habilidades/fastapi-experto/SKILL.md

@@ -0,0 +1,368 @@
+---
+name: fastapi-experto
+description: FastAPI con Pydantic v2, dependency injection, middleware, async patterns, OpenAPI y testing con httpx. Incluye anti-patrones críticos de SQLAlchemy async.
+---
+
+# FastAPI Experto
+
+## Estructura de proyecto recomendada
+
+```
+backend/
+├── app/
+│   ├── main.py              # App factory, lifespan, middleware
+│   ├── routers/             # Endpoints agrupados por dominio
+│   │   ├── __init__.py
+│   │   ├── usuarios.py
+│   │   └── facturas.py
+│   ├── schemas/             # Pydantic v2 — entrada/salida de API
+│   │   ├── usuario.py
+│   │   └── factura.py
+│   ├── models/              # SQLAlchemy ORM
+│   │   ├── base.py
+│   │   ├── usuario.py
+│   │   └── factura.py
+│   ├── services/            # Lógica de negocio (sin commit)
+│   │   └── factura_service.py
+│   ├── dependencies/        # Inyección de dependencias
+│   │   ├── auth.py
+│   │   └── database.py
+│   └── core/
+│       ├── config.py        # Settings con pydantic-settings
+│       └── security.py      # JWT, hashing
+```
+
+---
+
+## App factory con lifespan
+
+```python
+# app/main.py
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from app.core.config import settings
+from app.routers import usuarios, facturas
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup: inicializar recursos
+    await database.connect()
+    yield
+    # Shutdown: liberar recursos
+    await database.disconnect()
+
+def create_app() -> FastAPI:
+    app = FastAPI(
+        title=settings.APP_NOMBRE,
+        version=settings.APP_VERSION,
+        lifespan=lifespan,
+        docs_url="/docs" if settings.DEBUG else None,
+    )
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.CORS_ORIGINS,
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    app.include_router(usuarios.router, prefix="/api/v1")
+    app.include_router(facturas.router, prefix="/api/v1")
+    return app
+
+app = create_app()
+```
+
+---
+
+## Schemas Pydantic v2
+
+```python
+# app/schemas/factura.py
+from pydantic import BaseModel, Field, model_validator, field_validator
+from typing import Literal
+from datetime import date
+from decimal import Decimal
+
+class FacturaBase(BaseModel):
+    folio: str = Field(..., min_length=1, max_length=20)
+    fecha: date
+    subtotal: Decimal = Field(..., ge=0, decimal_places=2)
+
+class FacturaCreate(FacturaBase):
+    cliente_id: str
+    # Literal[] obliga a valores del dominio
+    estatus: Literal["borrador", "emitida", "cancelada"] = "borrador"
+
+class FacturaRead(FacturaBase):
+    id: str
+    estatus: Literal["borrador", "emitida", "cancelada"]
+    nombre_cliente: str  # viene de relación ORM, no de columna directa
+
+    model_config = {"from_attributes": True}
+
+    @model_validator(mode="wrap")
+    @classmethod
+    def extraer_nombre_cliente(cls, value, handler):
+        # Extraer campo de relación ORM antes de validar
+        if hasattr(value, "cliente"):
+            value.__dict__["nombre_cliente"] = (
+                value.cliente.nombre if value.cliente else ""
+            )
+        return handler(value)
+
+class PaginatedResponse[T](BaseModel):
+    items: list[T]
+    total: int
+    page: int
+    page_size: int
+    has_next: bool
+```
+
+---
+
+## Dependency Injection
+
+```python
+# app/dependencies/database.py
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+from typing import AsyncGenerator
+
+async def get_db() -> AsyncGenerator[AsyncSession, None]:
+    async with session_factory() as session:
+        try:
+            yield session
+        except Exception:
+            await session.rollback()
+            raise
+
+# app/dependencies/auth.py
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from app.core.security import decode_jwt
+
+bearer = HTTPBearer()
+
+async def get_current_user(
+    credentials: HTTPAuthorizationCredentials = Depends(bearer),
+    db: AsyncSession = Depends(get_db),
+) -> Usuario:
+    payload = decode_jwt(credentials.credentials)
+    if not payload:
+        raise HTTPException(status_code=401, detail="Token inválido")
+    usuario = await db.get(Usuario, payload["sub"])
+    if not usuario or not usuario.activo:
+        raise HTTPException(status_code=401, detail="Usuario inactivo")
+    return usuario
+
+def require_role(roles: list[str]):
+    async def verificar_rol(
+        usuario: Usuario = Depends(get_current_user),
+    ) -> Usuario:
+        if usuario.rol not in roles:
+            raise HTTPException(
+                status_code=403,
+                detail=f"Rol requerido: {roles}. Rol actual: {usuario.rol}"
+            )
+        return usuario
+    return verificar_rol
+```
+
+---
+
+## Endpoints con patrones correctos
+
+```python
+# app/routers/facturas.py
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, func
+from sqlalchemy.orm import selectinload
+
+router = APIRouter(prefix="/facturas", tags=["Facturas"])
+
+# Rutas estáticas ANTES de paramétricas
+@router.get("/exportar", response_model=list[FacturaRead])
+async def exportar_facturas(
+    formato: Literal["csv", "xlsx"] = Query("csv"),
+    db: AsyncSession = Depends(get_db),
+    usuario: Usuario = Depends(get_current_user),
+):
+    ...
+
+@router.get("/{factura_id}", response_model=FacturaRead)
+async def obtener_factura(
+    factura_id: str,
+    db: AsyncSession = Depends(get_db),
+    usuario: Usuario = Depends(get_current_user),
+):
+    query = (
+        select(Factura)
+        .where(Factura.id == factura_id)
+        # OBLIGATORIO: selectinload para todas las relaciones usadas en el schema
+        .options(selectinload(Factura.cliente))
+    )
+    result = await db.execute(query)
+    factura = result.scalar_one_or_none()
+
+    if not factura:
+        raise HTTPException(status_code=404, detail="Factura no encontrada")
+
+    # IDOR: validar que el recurso pertenece al usuario
+    if factura.empresa_id != usuario.empresa_id:
+        raise HTTPException(status_code=403, detail="Acceso denegado")
+
+    return factura
+
+@router.post("/", response_model=FacturaRead, status_code=201)
+async def crear_factura(
+    datos: FacturaCreate,
+    db: AsyncSession = Depends(get_db),
+    usuario: Usuario = Depends(get_current_user),
+    _: Usuario = Depends(require_role(["ADMIN", "FACTURISTA"])),
+):
+    # Service no hace commit
+    factura = await factura_service.crear(db, datos, owner=usuario)
+    await db.commit()
+    await db.refresh(factura)
+    # Recargar con relaciones para el schema de respuesta
+    await db.refresh(factura, ["cliente"])
+    return factura
+```
+
+---
+
+## SQLAlchemy Async — reglas críticas
+
+### NUNCA lazy loading en async
+
+```python
+# MAL — causa MissingGreenlet
+factura = await db.get(Factura, factura_id)
+print(factura.cliente.nombre)  # Error: acceso lazy fuera de sesión
+
+# BIEN — selectinload explícito
+query = select(Factura).where(Factura.id == factura_id).options(
+    selectinload(Factura.cliente)
+)
+result = await db.execute(query)
+factura = result.scalar_one()
+print(factura.cliente.nombre)  # OK
+```
+
+### Services: flush, no commit
+
+```python
+# app/services/factura_service.py
+class FacturaService:
+    async def crear(
+        self, db: AsyncSession, datos: FacturaCreate, owner: Usuario
+    ) -> Factura:
+        factura = Factura(
+            **datos.model_dump(),
+            creado_por=owner.email,
+            empresa_id=owner.empresa_id,
+        )
+        db.add(factura)
+        await db.flush()      # Obtiene ID sin commitear
+        await db.refresh(factura)
+        return factura
+        # NO hacer commit aquí — el endpoint es responsable
+```
+
+### lazy="selectin" para relaciones frecuentes
+
+```python
+class Factura(Base):
+    __tablename__ = "facturas"
+
+    id: Mapped[str] = mapped_column(primary_key=True)
+    cliente_id: Mapped[str] = mapped_column(ForeignKey("clientes.id"))
+
+    # Para relaciones accedidas en casi todos los queries
+    cliente: Mapped["Cliente"] = relationship(lazy="selectin")
+    # Para relaciones accedidas raramente — cargar con selectinload cuando se necesite
+    items: Mapped[list["ItemFactura"]] = relationship(lazy="select")
+```
+
+---
+
+## Middleware personalizado
+
+```python
+import time
+import uuid
+from fastapi import Request, Response
+
+async def middleware_request_id(request: Request, call_next):
+    request_id = str(uuid.uuid4())
+    request.state.request_id = request_id
+    inicio = time.time()
+    response: Response = await call_next(request)
+    duracion = time.time() - inicio
+    response.headers["X-Request-ID"] = request_id
+    response.headers["X-Response-Time"] = f"{duracion:.4f}s"
+    return response
+
+app.middleware("http")(middleware_request_id)
+```
+
+---
+
+## Testing con httpx
+
+```python
+# tests/test_facturas.py
+import pytest
+from httpx import AsyncClient, ASGITransport
+from app.main import app
+
+@pytest.fixture
+async def client(db_session):
+    async with AsyncClient(
+        transport=ASGITransport(app=app),
+        base_url="http://test",
+    ) as ac:
+        yield ac
+
+@pytest.mark.asyncio
+async def test_crear_factura(client, token_admin, factura_valida):
+    respuesta = await client.post(
+        "/api/v1/facturas/",
+        json=factura_valida,
+        headers={"Authorization": f"Bearer {token_admin}"},
+    )
+    assert respuesta.status_code == 201
+    data = respuesta.json()
+    assert data["estatus"] == "borrador"
+    assert "id" in data
+
+@pytest.mark.asyncio
+async def test_factura_requiere_autenticacion(client):
+    respuesta = await client.post("/api/v1/facturas/", json={})
+    assert respuesta.status_code == 403  # Sin token
+```
+
+---
+
+## Configuración con pydantic-settings
+
+```python
+# app/core/config.py
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")
+
+    APP_NOMBRE: str = "Mi API"
+    APP_VERSION: str = "1.0.0"
+    DEBUG: bool = False
+    DATABASE_URL: str
+    SECRET_KEY: str
+    CORS_ORIGINS: list[str] = ["http://localhost:4200"]
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 30
+
+settings = Settings()
+```