@saulwade/swl-ses 1.0.0

package/reglas/patrones.md

@@ -0,0 +1,225 @@
+# Regla: Patrones de Arquitectura — Next.js (App Router)
+
+El App Router de Next.js cambia fundamentalmente dónde y cómo se cargan datos.
+Estos patrones aprovechan el modelo de Server Components para reducir el JavaScript
+enviado al cliente, mejorar el rendimiento y simplificar la lógica de estado.
+
+---
+
+## Server Components: fetch en el servidor
+
+La forma correcta de cargar datos es en el servidor, no en el cliente con `useEffect`.
+
+```tsx
+// MAL — useEffect para cargar datos (patrón del Pages Router)
+'use client'
+export default function PaginaFacturas() {
+  const [facturas, setFacturas] = useState<Factura[]>([])
+  const [cargando, setCargando] = useState(true)
+
+  useEffect(() => {
+    fetch('/api/facturas')
+      .then(r => r.json())
+      .then(data => { setFacturas(data); setCargando(false) })
+  }, [])
+
+  if (cargando) return <p>Cargando...</p>
+  return <ListaFacturas facturas={facturas} />
+}
+
+// BIEN — Server Component, fetch directo en el servidor
+export default async function PaginaFacturas() {
+  const facturas = await obtenerFacturas() // llama directamente a la BD o API interna
+  return <ListaFacturas facturas={facturas} />
+}
+```
+
+- `obtenerFacturas()` puede llamar directamente a la BD, a un ORM o a un servicio
+  interno. No necesita pasar por una API REST si está en el mismo servidor.
+- Next.js deduplica y cachea las llamadas automáticamente dentro del mismo render.
+
+---
+
+## Server Actions para mutaciones
+
+Las mutaciones de datos van en Server Actions, no en Route Handlers cuando
+son invocadas desde formularios o componentes del mismo servidor.
+
+```tsx
+// app/facturas/actions.ts
+'use server'
+
+import { revalidatePath } from 'next/cache'
+import { redirect } from 'next/navigation'
+import { z } from 'zod'
+
+const EmitirFacturaSchema = z.object({
+  clienteId: z.coerce.number().int().positive(),
+})
+
+export async function emitirFactura(formData: FormData) {
+  const validado = EmitirFacturaSchema.safeParse({
+    clienteId: formData.get('clienteId'),
+  })
+
+  if (!validado.success) {
+    return { error: validado.error.flatten().fieldErrors }
+  }
+
+  await facturaService.emitir(validado.data.clienteId)
+  revalidatePath('/facturas')
+  redirect('/facturas')
+}
+```
+
+- Las Server Actions validan sus inputs server-side con zod. NUNCA asumir que
+  el cliente envió datos válidos.
+- `revalidatePath()` o `revalidateTag()` para invalidar el caché después de mutaciones.
+
+---
+
+## Streaming con Suspense
+
+- Envolver partes lentas del UI en `<Suspense>` para no bloquear el render completo:
+
+```tsx
+import { Suspense } from 'react'
+
+export default function Dashboard() {
+  return (
+    <main>
+      <ResumenRapido />                             {/* datos rápidos, sin Suspense */}
+      <Suspense fallback={<EsqueletoGrafica />}>
+        <GraficaVentasMensuales />                  {/* query lenta */}
+      </Suspense>
+      <Suspense fallback={<EsqueletoTabla />}>
+        <TablaTopClientes />                        {/* query lenta independiente */}
+      </Suspense>
+    </main>
+  )
+}
+```
+
+- Cada `<Suspense>` permite que los demás componentes se rendericen sin esperar.
+
+---
+
+## ISR para contenido semi-estático
+
+```tsx
+// Revalidar cada hora — ideal para catálogos de productos, precios, etc.
+export const revalidate = 3600
+
+// Revalidar bajo demanda con tag
+fetch(url, { next: { tags: ['catalogo-productos'] } })
+
+// En una Server Action o Route Handler:
+revalidateTag('catalogo-productos')
+```
+
+- Usar ISR para contenido que cambia con menos frecuencia que las visitas.
+- No usar ISR para datos que deben estar en tiempo real (inventario en compra,
+  saldo bancario). Para esos casos, `cache: 'no-store'`.
+
+---
+
+## Parallel Routes para dashboards
+
+```
+app/dashboard/
+  @resumen/
+    page.tsx
+  @alertas/
+    page.tsx
+  @actividad/
+    page.tsx
+  layout.tsx    ← recibe los tres slots en paralelo
+```
+
+```tsx
+// layout.tsx
+export default function DashboardLayout({
+  resumen, alertas, actividad
+}: {
+  resumen: React.ReactNode
+  alertas: React.ReactNode
+  actividad: React.ReactNode
+}) {
+  return (
+    <div className="grid grid-cols-3 gap-4">
+      {resumen}
+      {alertas}
+      {actividad}
+    </div>
+  )
+}
+```
+
+---
+
+## Intercepting Routes para modales
+
+- Para modales que muestran contenido de otra ruta sin navegar completamente:
+
+```
+app/
+  facturas/
+    page.tsx
+    [id]/
+      page.tsx        ← vista completa de la factura
+  @modal/
+    (.)facturas/[id]/
+      page.tsx        ← modal al hacer clic en la lista
+```
+
+---
+
+## Route Handlers para API endpoints
+
+- Usar `route.ts` para endpoints que son consumidos por clientes externos, móvil,
+  o por webhooks. No para datos internos del mismo servidor.
+
+```ts
+// app/api/facturas/route.ts
+export async function GET(request: Request) {
+  const { searchParams } = new URL(request.url)
+  const pagina = Number(searchParams.get('pagina') ?? '1')
+
+  const facturas = await obtenerFacturasPaginadas(pagina)
+  return Response.json(facturas)
+}
+```
+
+---
+
+## Middleware para auth, redirects, i18n
+
+```ts
+// middleware.ts (raíz del proyecto)
+export function middleware(request: NextRequest) {
+  const token = request.cookies.get('session')?.value
+
+  if (!token && request.nextUrl.pathname.startsWith('/app')) {
+    return NextResponse.redirect(new URL('/login', request.url))
+  }
+}
+
+export const config = {
+  matcher: ['/app/:path*', '/api/:path*'],
+}
+```
+
+- El middleware solo lee cookies y headers. No llama a la BD directamente.
+- Para verificación de sesión pesada, usar la función `auth()` del framework
+  de autenticación dentro del Server Component, no en el middleware.
+
+---
+
+## Checklist de patrones antes de merge
+
+- [ ] Sin `useEffect` para carga de datos que pueden ir en Server Component
+- [ ] Mutaciones en Server Actions con validación zod server-side
+- [ ] Secciones lentas del dashboard envueltas en `<Suspense>`
+- [ ] `revalidatePath` o `revalidateTag` después de toda mutación
+- [ ] Route Handlers solo para APIs externas, no para datos internos
+- [ ] Middleware sin llamadas a BD directas

package/reglas/performance.md

@@ -0,0 +1,195 @@
+# Regla: Performance
+
+La optimización prematura es la raíz de todos los males — Donald Knuth.
+Esta regla equilibra ese principio con las restricciones reales del sistema:
+algunos problemas de performance son predecibles y deben evitarse desde el diseño.
+
+---
+
+## No optimizar prematuramente
+
+- No escribir código complicado "por si acaso es lento".
+  Escribir el código más claro y simple primero.
+- No sacrificar legibilidad por micro-optimizaciones sin evidencia de que
+  el código es un cuello de botella real.
+- El código simple es más fácil de optimizar después que el código complejo
+  de hacer legible después.
+- Excepción: anti-patrones de performance con costo predecible y conocido
+  (N+1 queries, carga de archivos completos en memoria, loops anidados O(n²))
+  deben evitarse desde el diseño aunque no haya medición todavía.
+
+---
+
+## Medir antes de optimizar
+
+- Antes de cualquier optimización: tener una medición de baseline.
+  Sin número, no hay optimización — hay cambio ciego.
+- Formato mínimo de documentación de optimización:
+  ```
+  Problema: el endpoint /facturas tarda 4.2s promedio bajo carga de 100 req/s
+  Causa identificada: N+1 queries en la relación factura → items (profiled con py-spy)
+  Solución: eager loading con selectinload()
+  Resultado: 0.18s promedio (mejora 23x)
+  ```
+- Optimización sin medición: no se acepta en code review.
+- Las métricas de performance son parte del PR si el PR es una optimización.
+
+---
+
+## Profiling con herramientas
+
+Python — herramientas aprobadas:
+- `py-spy` para profiling en producción (sin reiniciar el proceso)
+- `cProfile` + `snakeviz` para profiling en desarrollo
+- `line_profiler` para análisis línea por línea
+- `memory_profiler` para problemas de memoria
+- `EXPLAIN ANALYZE` en PostgreSQL para queries lentas
+- `sqlalchemy echo=True` para ver queries generadas en desarrollo
+
+TypeScript/Angular — herramientas aprobadas:
+- Chrome DevTools Performance tab
+- Angular DevTools (profiler de componentes y change detection)
+- `webpack-bundle-analyzer` para tamaño de bundles
+- Lighthouse para métricas web (LCP, FID, CLS)
+
+Reglas de profiling:
+- Perfilar en condiciones similares a producción (no en localhost con 1 usuario).
+- Identificar el 20% del código que consume el 80% del tiempo antes de tocar nada.
+- Documentar el resultado del profiling en el ticket o PR.
+
+---
+
+## N+1 queries — prohibidos
+
+El problema N+1 es un bug de performance predecible y evitable desde el diseño:
+
+Síntoma:
+```python
+# MALO: genera N+1 queries
+facturas = db.query(Factura).all()
+for factura in facturas:
+    print(factura.cliente.nombre)  # query adicional por cada factura
+```
+
+Solución con eager loading:
+```python
+# BIEN: 2 queries totales independientemente de cuántas facturas
+facturas = db.query(Factura).options(selectinload(Factura.cliente)).all()
+for factura in facturas:
+    print(factura.cliente.nombre)  # ya cargado
+```
+
+Reglas estrictas:
+- Todo endpoint que devuelve colecciones con relaciones DEBE usar eager loading.
+- Revisión obligatoria en code review: buscar acceso a atributos de relaciones
+  dentro de loops.
+- En testing: activar logging de SQL en tests de integración para detectar N+1
+  contando queries ejecutadas.
+- `lazy="selectin"` en relaciones ORM frecuentemente accedidas como default seguro.
+
+---
+
+## Lazy loading para módulos pesados
+
+Frontend Angular:
+- Todo módulo que no es parte del critical rendering path DEBE cargarse con lazy loading.
+- Rutas de admin, reportes, configuración: siempre lazy.
+- Formato obligatorio en el router:
+  ```typescript
+  {
+    path: 'reportes',
+    loadChildren: () => import('./reportes/reportes.module')
+      .then(m => m.ReportesModule)
+  }
+  ```
+- Verificar el tamaño del bundle inicial con `webpack-bundle-analyzer`.
+  Bundle inicial objetivo: <500KB gzipped.
+- Preloading strategy para módulos que el usuario probablemente visitará:
+  `PreloadAllModules` o custom `QuicklinkStrategy`.
+
+Backend Python:
+- Imports costosos (modelos de ML, librerías de procesamiento) dentro de las
+  funciones que los usan, no en el nivel de módulo.
+- Conexiones a servicios externos: inicializar en el primer uso, no al arrancar.
+
+---
+
+## Caching con invalidación explícita
+
+El caching sin invalidación es un bug en espera:
+
+Reglas obligatorias:
+- Todo cache tiene un TTL explícito definido en código o configuración.
+  NUNCA TTL infinito en producción.
+- Los casos de invalidación anticipada están documentados en el código.
+- El cache key incluye todos los parámetros que afectan el resultado.
+  Un cache key incorrecto causa bugs silenciosos de datos obsoletos.
+
+Niveles de caching y herramientas:
+- **In-memory (proceso)**: `functools.lru_cache` / `@cache` para valores
+  computacionalmente costosos e inmutables. Documentar el tamaño máximo.
+- **Distribuido**: Redis para datos compartidos entre instancias.
+  Usar prefijos de key por entorno (`prod:`, `staging:`).
+- **HTTP**: Cache-Control headers explícitos. `no-store` para datos sensibles.
+  `max-age` con revalidación para recursos estáticos.
+- **BD query cache**: Con precaución — Postgres no tiene query cache nativo.
+  Usar vistas materializadas para queries complejas y costosas.
+
+Patrón de invalidación:
+```python
+CACHE_KEY_FACTURAS = "facturas:{empresa_id}:{mes}"
+CACHE_TTL_FACTURAS = 300  # 5 minutos
+
+# Al mutar datos: invalidar explícitamente
+async def crear_factura(empresa_id: UUID, ...):
+    factura = await _persistir_factura(...)
+    await cache.delete(CACHE_KEY_FACTURAS.format(empresa_id=empresa_id, mes=...))
+    return factura
+```
+
+---
+
+## Índices de BD documentados
+
+- Todo índice creado en la BD tiene un comentario en la migración que explica
+  qué query lo justifica.
+- Formato obligatorio en la migración:
+  ```python
+  # Índice para la query: GET /facturas?empresa_id=X&estatus=Y
+  # Antes del índice: 450ms (seq scan 2M filas)
+  # Después: 3ms (index scan)
+  op.create_index('ix_facturas_empresa_estatus', 'facturas',
+                  ['empresa_id', 'estatus'])
+  ```
+- No crear índices "preventivos" sin query que los justifique.
+- Revisar índices no utilizados en producción cada 3 meses:
+  ```sql
+  SELECT * FROM pg_stat_user_indexes WHERE idx_scan = 0;
+  ```
+- Índices compuestos: el orden de columnas importa. La columna más selectiva
+  o la usada en igualdad va primero.
+
+---
+
+## Métricas de performance objetivo
+
+Definir por proyecto, documentar en el README. Valores de referencia razonables:
+
+| Tipo de operación | Objetivo | Alerta |
+|-------------------|----------|--------|
+| API GET simple | <100ms p95 | >500ms |
+| API POST con escritura en BD | <300ms p95 | >1s |
+| API con agregaciones | <500ms p95 | >2s |
+| Render inicial de página | <2s LCP | >4s |
+| Bundle JavaScript inicial | <500KB gzip | >1MB |
+
+---
+
+## Checklist de performance antes de merge
+
+- [ ] Sin acceso a relaciones ORM dentro de loops (N+1)
+- [ ] Módulos pesados en Angular con lazy loading
+- [ ] Todo cache nuevo tiene TTL explícito e invalidación documentada
+- [ ] Índices nuevos documentados en la migración con query que los justifica
+- [ ] Si el PR es una optimización: tiene medición antes/después
+- [ ] Sin imports costosos a nivel de módulo que retrasen el arranque

package/reglas/pruebas.md

@@ -0,0 +1,159 @@
+# Regla: Pruebas
+
+Los tests no son opcionales. Son parte de la definición de "terminado" para
+cualquier feature, bugfix o refactor. Código sin tests es código que no se puede
+mantener con confianza.
+
+---
+
+## Tests obligatorios para toda feature nueva
+
+- Ninguna feature se considera completa sin tests que la cubran.
+- Definición de Done incluye:
+  - Tests unitarios para toda función de lógica de negocio nueva
+  - Tests de integración para todo endpoint nuevo
+  - Tests de frontera para inputs extremos y casos de error
+- El revisor rechaza PRs sin tests para código nuevo, sin excepción.
+- Refactors: si el código refactorizado no tenía tests, agregarlos es parte del
+  trabajo de refactor, no una tarea separada.
+- Bugfixes: escribir el test que reproduce el bug ANTES de escribir el fix.
+  Verificar que el test falla antes del fix y pasa después.
+
+---
+
+## Cobertura mínima >80%
+
+- La cobertura es una métrica, no el objetivo. Un 100% de cobertura con tests
+  triviales no garantiza calidad. Pero cobertura baja sí indica código sin probar.
+- Umbral mínimo: 80% de cobertura de líneas en módulos de lógica de negocio.
+- CI falla si la cobertura cae por debajo del umbral al agregar código nuevo.
+- Reportar cobertura diferencial en el PR (cobertura del código nuevo añadido).
+- Excepciones documentadas: código de configuración, __main__, scaffolding generado.
+  No se excluyen módulos por conveniencia — documentar explícitamente la razón.
+- Herramientas: `pytest-cov` con `--cov-fail-under=80` para Python,
+  `jest --coverage --coverageThreshold` para TypeScript.
+
+---
+
+## Patrón Arrange-Act-Assert (AAA)
+
+Todo test unitario sigue este patrón sin excepción:
+
+```python
+def test_calcular_impuesto_con_tasa_estandar():
+    # Arrange — preparar el estado inicial
+    producto = Producto(precio=100.0, categoria="electronico")
+    calculadora = CalculadoraImpuesto(tasa=0.16)
+
+    # Act — ejecutar la unidad bajo prueba
+    resultado = calculadora.calcular(producto)
+
+    # Assert — verificar el resultado
+    assert resultado == 16.0
+```
+
+Reglas del AAA:
+- Los tres bloques separados visualmente (línea en blanco o comentario).
+- Un solo Assert conceptual por test. Múltiples `assert` sobre el mismo resultado
+  están bien; assert sobre comportamientos distintos no.
+- Si el Arrange es muy extenso: extraer a función helper o usar factories.
+- Nombre del test describe el escenario completo:
+  `test_[unidad]_[escenario]_[resultado_esperado]`
+  Ejemplo: `test_crear_factura_sin_items_lanza_error_validacion`
+
+---
+
+## Tests deterministas — sin sleep ni delays
+
+- Un test que falla intermitentemente es peor que ningún test: genera desconfianza
+  en el suite completo.
+- NUNCA usar `time.sleep()`, `asyncio.sleep()`, `setTimeout()` en tests.
+- NUNCA depender de tiempo real. Mockear el reloj:
+  - Python: `freezegun`, `unittest.mock.patch('datetime.datetime.now')`
+  - JavaScript: `jest.useFakeTimers()`
+- NUNCA depender del orden de ejecución de los tests. Cada test es independiente.
+- NUNCA depender del estado de un test anterior. Limpiar estado en `teardown`.
+- Tests de integración con BD: usar transacciones que se revierten al final,
+  o fixtures aislados por test.
+- Seeds de datos en BD de test: deterministas y reproducibles.
+
+---
+
+## Factories sobre fixtures hardcodeados
+
+- Fixtures hardcodeados (dicts o JSON estáticos con todos los campos) son frágiles:
+  cambian con el schema y no comunican qué datos son relevantes para el test.
+- Usar factories que generan objetos con valores por defecto razonables y permiten
+  sobreescribir solo lo que importa para el test:
+
+  ```python
+  # factory_boy (Python)
+  class FacturaFactory(factory.Factory):
+      class Meta:
+          model = Factura
+      estatus = "borrador"
+      total = 0.0
+      cliente = factory.SubFactory(ClienteFactory)
+
+  # En el test — solo los datos relevantes
+  factura = FacturaFactory(estatus="pagada", total=1000.0)
+  ```
+
+- Factories en un módulo dedicado `tests/factories.py` o `tests/factories/`.
+- No duplicar factories entre módulos — importar desde el módulo central.
+- Para TypeScript: usar `@faker-js/faker` con funciones builder, no objetos
+  hardcodeados.
+
+---
+
+## Tests de frontera para edge cases
+
+Los casos felices son necesarios pero no suficientes. Todo test suite debe incluir:
+
+- **Valores nulos / vacíos**: `None`, `""`, `[]`, `{}`, `0`
+- **Valores en el límite**: longitud máxima, longitud mínima, valores justo
+  por encima y por debajo de umbrales numéricos
+- **Tipos inesperados**: qué pasa si llega un string donde se espera un número
+- **Colecciones extremas**: lista de 1 elemento, lista de 10,000 elementos
+- **Concurrencia**: si la función modifica estado compartido, probar acceso
+  concurrente
+- **Errores de dependencias externas**: qué pasa si la BD está caída, si la API
+  externa devuelve error 500, si el filesystem está lleno
+- **Strings con caracteres especiales**: Unicode, emojis, SQL injection attempts,
+  XSS payloads — para validar que la sanitización funciona
+
+Cada edge case que causó un bug en producción: agregar test de regresión.
+
+---
+
+## Nomenclatura y organización
+
+- Archivo de test espeja el módulo que prueba:
+  `app/services/factura_service.py` → `tests/services/test_factura_service.py`
+- Tests de integración en `tests/integration/`, unitarios en `tests/unit/`.
+- Agrupar tests relacionados en clases cuando hay mucho setup compartido.
+- Nombre de la clase: `TestNombreDelModulo`. Nombre del método: `test_escenario`.
+- No usar números en nombres de test (`test_1`, `test_caso_2`): sin semántica.
+
+---
+
+## Mocks y stubs
+
+- Mockear en el boundary del sistema: BD, APIs externas, filesystem, reloj.
+- No mockear código propio — si se mockea, es señal de acoplamiento excesivo.
+- Verificar que los mocks se configuran para el comportamiento esperado Y para
+  el comportamiento de error.
+- Limpiar mocks entre tests para evitar contaminación de estado.
+- Documentar en el test por qué se mockea algo si no es obvio.
+
+---
+
+## Checklist de tests antes de merge
+
+- [ ] Tests nuevos para todo código nuevo
+- [ ] Test de regresión para todo bug corregido
+- [ ] Cobertura del módulo modificado >= 80%
+- [ ] Sin sleep/delay en tests
+- [ ] Tests pasan de forma determinista 3 veces consecutivas en CI
+- [ ] Factories usadas para datos de prueba complejos
+- [ ] Edge cases cubiertos: nulos, vacíos, límites