theus-cli-linux-arm64 0.2.84

package/vendor/theus-arsenal/skills/patrones-emr-clinico/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: patrones-emr-clinico
+description: Patrones de desarrollo de sistemas EMR/EHR para aplicaciones de salud. Seguridad clínica, flujos de consulta, generación de recetas, integración de soporte a la decisión clínica (CDSS) y UI accesible para captura de datos médicos.
+---
+
+# Patrones de desarrollo EMR/EHR
+
+Patrones para construir sistemas de Historia Clínica Electrónica (EMR/EHR). Prioriza la seguridad del paciente, la exactitud clínica y la eficiencia del personal sanitario.
+
+> **Aviso:** este material es una guía de ingeniería. No sustituye la asesoría de profesionales clínicos, regulatorios ni legales; cualquier sistema clínico real debe validarse con especialistas cualificados y la normativa aplicable.
+
+## Cuándo usarla
+
+- Al construir flujos de consulta de pacientes (motivo, exploración, diagnóstico, receta).
+- Al implementar notas clínicas (estructuradas + texto libre + dictado por voz).
+- Al diseñar módulos de recetas/medicación con verificación de interacciones farmacológicas.
+- Al integrar sistemas de soporte a la decisión clínica (CDSS).
+- Al construir visualizaciones de resultados de laboratorio con resaltado de rangos de referencia.
+- Al implementar trazas de auditoría para datos clínicos.
+- Al diseñar interfaces accesibles para captura de datos clínicos.
+
+## Cómo funciona
+
+### La seguridad del paciente primero
+
+Toda decisión de diseño debe evaluarse contra la pregunta: "¿Podría esto dañar a un paciente?"
+
+- Las interacciones farmacológicas DEBEN alertar, nunca pasar en silencio.
+- Los valores de laboratorio anormales DEBEN señalarse visualmente.
+- Las constantes vitales críticas DEBEN disparar flujos de escalamiento.
+- Ninguna modificación de datos clínicos sin traza de auditoría.
+
+### Flujo de consulta en una sola página
+
+Las consultas clínicas deben fluir verticalmente en una sola página — sin cambiar de pestaña:
+
+```
+Cabecera del paciente (fija — siempre visible)
+├── Datos demográficos, alergias, medicación activa
+│
+Flujo de la consulta (scroll vertical)
+├── 1. Motivo de consulta (plantillas estructuradas + texto libre)
+├── 2. Historia de la enfermedad actual
+├── 3. Exploración física (por sistemas)
+├── 4. Constantes vitales (dispara scoring clínico automático)
+├── 5. Diagnóstico (búsqueda ICD-10/SNOMED)
+├── 6. Medicación (base de fármacos + verificación de interacciones)
+├── 7. Pruebas complementarias (órdenes de laboratorio/radiología)
+├── 8. Plan y seguimiento
+└── 9. Firmar / Bloquear / Imprimir
+```
+
+### Sistema de plantillas inteligentes
+
+```typescript
+interface ClinicalTemplate {
+  id: string;
+  name: string;             // p. ej., "Dolor torácico"
+  chips: string[];          // chips de síntomas clicables
+  requiredFields: string[]; // datos obligatorios
+  redFlags: string[];       // dispara una alerta no descartable
+  icdSuggestions: string[]; // códigos de diagnóstico pre-mapeados
+}
+```
+
+Los red flags de cualquier plantilla deben disparar una alerta visible y no descartable — NUNCA una notificación tipo toast.
+
+### Patrón de seguridad en medicación
+
+```
+El usuario selecciona un fármaco
+  → Verificar interacciones con la medicación actual
+  → Verificar interacciones con la medicación de esta consulta
+  → Verificar alergias del paciente
+  → Validar dosis según peso/edad/función renal
+  → Si la interacción es CRÍTICA: BLOQUEAR la prescripción por completo
+  → El clínico debe documentar el motivo de la anulación para superar un bloqueo
+  → Si la interacción es MAYOR: mostrar advertencia y exigir confirmación explícita
+  → Registrar todas las alertas y motivos de anulación en la traza de auditoría
+```
+
+Las interacciones críticas **bloquean la prescripción por defecto**. El clínico debe anular explícitamente con un motivo documentado que queda en la traza de auditoría. El sistema nunca permite en silencio una interacción crítica.
+
+### Patrón de consulta bloqueada
+
+Una vez firmada una consulta clínica:
+
+- No se permiten ediciones — solo una adenda (un registro separado y vinculado).
+- Tanto el original como la adenda aparecen en la línea de tiempo del paciente.
+- La traza de auditoría captura quién firmó, cuándo, y cualquier adenda posterior.
+
+### Patrones de UI para datos clínicos
+
+**Constantes vitales:** valores actuales con resaltado de rango normal (verde/amarillo/rojo), flechas de tendencia respecto a la medición anterior, scoring clínico auto-calculado (NEWS2, qSOFA), guía de escalamiento en línea.
+
+**Resultados de laboratorio:** resaltado de rango normal, comparación con el valor previo, valores críticos con alerta no descartable, marcas de tiempo de toma de muestra y análisis, órdenes pendientes con tiempo de respuesta esperado.
+
+**PDF de receta:** generación en un clic con datos demográficos del paciente, alergias, diagnóstico, detalle del fármaco (genérico + marca, dosis, vía, frecuencia, duración) y bloque de firma del clínico.
+
+### Accesibilidad en salud
+
+Las interfaces sanitarias tienen requisitos más estrictos que una web típica:
+
+- Contraste mínimo de 4.5:1 (WCAG AA) — el personal clínico trabaja con iluminación variable.
+- Objetivos táctiles grandes (mínimo 44x44 px) — para interacción con guantes o con prisa.
+- Navegación completa por teclado — para usuarios avanzados que capturan datos a gran velocidad.
+- Nunca indicar solo por color — acompañar siempre con texto/icono (clínicos con daltonismo).
+- Etiquetas de lector de pantalla en todos los campos de formulario.
+- Nada de toasts que se auto-descartan para alertas clínicas — el clínico debe confirmar activamente.
+
+### Antipatrones
+
+- Almacenar datos clínicos en el localStorage del navegador.
+- Fallos silenciosos en la verificación de interacciones farmacológicas.
+- Toasts descartables para alertas clínicas críticas.
+- Interfaces de consulta por pestañas que fragmentan el flujo clínico.
+- Permitir ediciones a consultas firmadas/bloqueadas.
+- Mostrar datos clínicos sin traza de auditoría.
+- Usar el tipo `any` en estructuras de datos clínicos.
+
+## Ejemplos
+
+### Ejemplo 1: flujo de consulta de paciente
+
+```
+El médico abre la consulta del paciente #4521
+  → La cabecera fija muestra: "Rajesh M, 58H, Alergias: Penicilina, Medicación activa: Metformina 500mg"
+  → Motivo de consulta: selecciona la plantilla "Dolor torácico"
+    → Clica los chips: "retroesternal", "irradiado a brazo izquierdo", "opresivo"
+    → El red flag "dolor torácico opresivo retroesternal" dispara una alerta no descartable
+  → Exploración: sistema cardiovascular — "R1 R2 normales, sin soplos"
+  → Constantes: FC 110, TA 90/60, SpO2 94%
+    → NEWS2 se auto-calcula: puntuación 8, riesgo ALTO, se muestra alerta de escalamiento
+  → Diagnóstico: busca "SCA" → selecciona ICD-10 I21.9
+  → Medicación: selecciona Aspirina 300mg
+    → El CDSS verifica contra Metformina: sin interacción
+  → Firma la consulta → bloqueada, a partir de aquí solo adendas
+```
+
+### Ejemplo 2: flujo de seguridad en medicación
+
+```
+El médico prescribe Warfarina al paciente #4521
+  → El CDSS detecta: Warfarina + Aspirina = interacción CRÍTICA
+  → UI: un modal rojo no descartable bloquea la prescripción
+  → El médico pulsa "Anular con motivo"
+  → Escribe: "El beneficio supera el riesgo — protocolo de INR monitorizado"
+  → El motivo de anulación + la alerta quedan en la traza de auditoría
+  → La prescripción continúa con la anulación documentada
+```
+
+### Ejemplo 3: consulta bloqueada + adenda
+
+```
+Consulta #E-2024-0891 firmada por la Dra. Shah a las 14:30
+  → Todos los campos bloqueados — sin botones de edición visibles
+  → El botón "Añadir adenda" sigue disponible
+  → La Dra. Shah añade la adenda: "Resultados de laboratorio recibidos — Troponina elevada"
+  → Se crea el registro E-2024-0891-A1 vinculado al original
+  → La línea de tiempo muestra ambos: consulta original + adenda con sus marcas de tiempo
+```
+
+## Skills relacionadas
+
+- `datos-sensibles-salud`
+- `cumplimiento-hipaa`
+- `harness-eval-clinico`
+- `accesibilidad`

package/vendor/theus-arsenal/skills/patrones-fastapi/SKILL.md

@@ -0,0 +1,513 @@
+---
+name: patrones-fastapi
+description: Buenas prácticas de FastAPI que cubren estructura de proyecto, esquemas Pydantic v2, inyección de dependencias, handlers async, autenticación, autorización, capas de servicio transaccionales y testing con httpx y pytest.
+---
+
+# Patrones de FastAPI
+
+Desarrollo moderno de FastAPI con calidad de producción: estructura de proyecto, esquemas Pydantic v2, inyección de dependencias, patrones async, autenticación, métodos de servicio transaccionales y testing.
+
+## Estructura del proyecto
+
+```text
+my_app/
+|-- app/
+|   |-- main.py               # Fábrica de la app, lifespan, middleware
+|   |-- config.py             # Configuración vía pydantic-settings
+|   |-- dependencies.py       # Dependencias compartidas de FastAPI
+|   |-- database.py           # Engine + sesión de SQLAlchemy
+|   |-- routers/
+|   |   `-- users.py
+|   |-- models/               # Modelos ORM de SQLAlchemy
+|   |   `-- user.py
+|   |-- schemas/              # Esquemas Pydantic de request/response
+|   |   `-- user.py
+|   `-- services/             # Capa de lógica de negocio
+|       `-- user_service.py
+|-- tests/
+|   |-- conftest.py
+|   `-- test_users.py
+|-- pyproject.toml
+`-- .env
+```
+
+---
+
+## Fábrica de la app y lifespan
+
+```python
+# app/main.py
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from app.config import settings
+from app.database import engine, Base
+from app.routers import users
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Crear las tablas automáticamente al arrancar, por comodidad en entornos de dev/demo.
+    # Para aplicaciones de producción estrictas, gestiona los esquemas con migraciones de Alembic.
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    yield
+    # Apagado: cerrar los recursos del pool.
+    await engine.dispose()
+
+
+def create_app() -> FastAPI:
+    app = FastAPI(
+        title=settings.app_name,
+        version=settings.app_version,
+        lifespan=lifespan,
+    )
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.allowed_origins,
+        allow_credentials=settings.allow_credentials,
+        allow_methods=settings.allowed_methods,
+        allow_headers=settings.allowed_headers,
+    )
+
+    app.include_router(users.router, prefix="/users", tags=["users"])
+
+    return app
+
+
+app = create_app()
+```
+
+---
+
+## Configuración con pydantic-settings
+
+```python
+# app/config.py
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")
+
+    app_name: str = "My App"
+    app_version: str = "0.1.0"
+    debug: bool = False
+
+    database_url: str
+    secret_key: str
+    algorithm: str = "HS256"
+    access_token_expire_minutes: int = 30
+
+    # pydantic-settings v2 evalúa de forma segura los literales de lista mutables
+    allowed_origins: list[str] = ["http://localhost:3000"]
+    allowed_methods: list[str] = ["GET", "POST", "PATCH", "DELETE", "OPTIONS"]
+    allowed_headers: list[str] = ["Authorization", "Content-Type"]
+    allow_credentials: bool = True
+
+
+settings = Settings()
+```
+
+---
+
+## Esquemas Pydantic (v2)
+
+```python
+# app/schemas/user.py
+from datetime import datetime
+from pydantic import BaseModel, EmailStr, Field, model_validator
+
+
+class UserBase(BaseModel):
+    email: EmailStr
+    username: str = Field(min_length=3, max_length=50)
+
+
+class UserCreate(UserBase):
+    password: str = Field(min_length=8)
+    password_confirm: str
+
+    @model_validator(mode="after")
+    def passwords_match(self) -> "UserCreate":
+        if self.password != self.password_confirm:
+            raise ValueError("Las contraseñas no coinciden")
+        return self
+
+
+class UserUpdate(BaseModel):
+    username: str | None = Field(default=None, min_length=3, max_length=50)
+    email: EmailStr | None = None
+
+
+class UserResponse(UserBase):
+    id: int
+    is_active: bool
+    created_at: datetime
+
+    model_config = {"from_attributes": True}
+
+
+class UserListResponse(BaseModel):
+    total: int
+    items: list[UserResponse]
+```
+
+---
+
+## Inyección de dependencias
+
+```python
+# app/dependencies.py
+from typing import Annotated, AsyncGenerator
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer
+from jose import JWTError, jwt
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.config import settings
+from app.database import AsyncSessionLocal
+from app.models.user import User
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/users/token")
+
+
+async def get_db() -> AsyncGenerator[AsyncSession, None]:
+    async with AsyncSessionLocal() as session:
+        try:
+            yield session
+        except Exception:
+            await session.rollback()
+            raise
+
+
+async def get_current_user(
+    token: Annotated[str, Depends(oauth2_scheme)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+) -> User:
+    credentials_exception = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="No se pudieron validar las credenciales",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+    try:
+        payload = jwt.decode(token, settings.secret_key, algorithms=[settings.algorithm])
+        subject = payload.get("sub")
+        if subject is None:
+            raise credentials_exception
+        user_id = int(subject)
+    except (JWTError, TypeError, ValueError):
+        raise credentials_exception
+
+    user = await db.get(User, user_id)
+    if user is None:
+        raise credentials_exception
+    return user
+
+
+async def get_current_active_user(
+    current_user: Annotated[User, Depends(get_current_user)],
+) -> User:
+    if not current_user.is_active:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Usuario inactivo")
+    return current_user
+
+
+DbDep = Annotated[AsyncSession, Depends(get_db)]
+CurrentUserDep = Annotated[User, Depends(get_current_user)]
+ActiveUserDep = Annotated[User, Depends(get_current_active_user)]
+```
+
+---
+
+## Diseño de routers y endpoints
+
+```python
+# app/routers/users.py
+from typing import Annotated
+from fastapi import APIRouter, HTTPException, Query, status
+from fastapi.security import OAuth2PasswordRequestForm
+
+from app.dependencies import ActiveUserDep, DbDep
+from app.schemas.user import UserCreate, UserResponse, UserUpdate, UserListResponse
+from app.services.user_service import DuplicateUserError, UserService
+
+router = APIRouter()
+
+
+@router.post("/", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
+async def create_user(payload: UserCreate, db: DbDep) -> UserResponse:
+    service = UserService(db)
+    try:
+        return await service.create(payload)
+    except DuplicateUserError:
+        raise HTTPException(status_code=400, detail="El email ya está registrado")
+
+
+@router.get("/me", response_model=UserResponse)
+async def get_me(current_user: ActiveUserDep) -> UserResponse:
+    return current_user
+
+
+@router.get("/", response_model=UserListResponse)
+async def list_users(
+    db: DbDep,
+    current_user: ActiveUserDep,
+    skip: Annotated[int, Query(ge=0)] = 0,
+    limit: Annotated[int, Query(ge=1, le=100)] = 20,
+) -> UserListResponse:
+    service = UserService(db)
+    users, total = await service.list(skip=skip, limit=limit)
+    return UserListResponse(total=total, items=users)
+
+
+@router.patch("/{user_id}", response_model=UserResponse)
+async def update_user(
+    user_id: int,
+    payload: UserUpdate,
+    db: DbDep,
+    current_user: ActiveUserDep,
+) -> UserResponse:
+    if current_user.id != user_id:
+        raise HTTPException(status_code=403, detail="No autorizado")
+    service = UserService(db)
+    try:
+        user = await service.update(user_id, payload)
+    except DuplicateUserError:
+        raise HTTPException(status_code=400, detail="El email ya está registrado")
+    if user is None:
+        raise HTTPException(status_code=404, detail="Usuario no encontrado")
+    return user
+
+
+@router.post("/token")
+async def login(
+    form_data: Annotated[OAuth2PasswordRequestForm, Depends()],
+    db: DbDep,
+) -> dict[str, str]:
+    service = UserService(db)
+    token = await service.authenticate(form_data.username, form_data.password)
+    if token is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Usuario o contraseña incorrectos",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    return {"access_token": token, "token_type": "bearer"}
+```
+
+---
+
+## Capa de servicio
+
+```python
+# app/services/user_service.py
+from datetime import datetime, timedelta, timezone
+
+from jose import jwt
+from passlib.context import CryptContext
+from sqlalchemy import func, select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.config import settings
+from app.models.user import User
+from app.schemas.user import UserCreate, UserUpdate
+
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+
+class DuplicateUserError(Exception):
+    """Se lanza cuando un campo único del usuario colisiona con una fila existente."""
+
+
+class UserService:
+    def __init__(self, db: AsyncSession) -> None:
+        self.db = db
+
+    async def get_by_email(self, email: str) -> User | None:
+        result = await self.db.execute(select(User).where(User.email == email))
+        return result.scalar_one_or_none()
+
+    async def create(self, payload: UserCreate) -> User:
+        user = User(
+            email=payload.email,
+            username=payload.username,
+            hashed_password=pwd_context.hash(payload.password),
+        )
+        self.db.add(user)
+        try:
+            # Confiar en las restricciones atómicas de la BD en lugar de
+            # prechequeos a nivel de aplicación propensos a condiciones de carrera
+            await self.db.commit()
+        except IntegrityError as exc:
+            await self.db.rollback()
+            raise DuplicateUserError from exc
+        await self.db.refresh(user)
+        return user
+
+    async def list(self, skip: int = 0, limit: int = 20) -> tuple[list[User], int]:
+        total_result = await self.db.execute(select(func.count(User.id)))
+        total = total_result.scalar_one()
+        # Forzar un orden determinista explícito para garantizar una paginación fiable
+        result = await self.db.execute(
+            select(User).order_by(User.id).offset(skip).limit(limit)
+        )
+        return list(result.scalars()), total
+
+    async def update(self, user_id: int, payload: UserUpdate) -> User | None:
+        user = await self.db.get(User, user_id)
+        if user is None:
+            return None
+        for field, value in payload.model_dump(exclude_unset=True).items():
+            setattr(user, field, value)
+        try:
+            await self.db.commit()
+        except IntegrityError as exc:
+            await self.db.rollback()
+            raise DuplicateUserError from exc
+        await self.db.refresh(user)
+        return user
+
+    async def authenticate(self, email: str, password: str) -> str | None:
+        user = await self.get_by_email(email)
+        if user is None or not pwd_context.verify(password, user.hashed_password):
+            return None
+        expire = datetime.now(timezone.utc) + timedelta(
+            minutes=settings.access_token_expire_minutes
+        )
+        return jwt.encode(
+            {"sub": str(user.id), "exp": expire},
+            settings.secret_key,
+            algorithm=settings.algorithm,
+        )
+```
+
+> **Nota sobre diseño de base de datos:** El manejo de unicidad a nivel de aplicación requiere un índice único subyacente en la base de datos (p. ej., `unique=True` en los atributos mapeados de SQLAlchemy). Sin restricciones subyacentes, capturar errores en la capa de aplicación no puede prevenir con seguridad las condiciones de carrera concurrentes.
+
+---
+
+## Testing con httpx y pytest
+
+```python
+# tests/conftest.py
+import pytest_asyncio
+from httpx import ASGITransport, AsyncClient
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+
+from app.database import Base
+from app.dependencies import get_db
+from app.main import create_app
+
+TEST_DATABASE_URL = "sqlite+aiosqlite:///:memory:"
+
+engine = create_async_engine(TEST_DATABASE_URL)
+TestingSessionLocal = async_sessionmaker(engine, expire_on_commit=False)
+
+
+@pytest_asyncio.fixture(autouse=True)
+async def setup_db():
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    yield
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.drop_all)
+
+
+@pytest_asyncio.fixture
+async def db_session():
+    async with TestingSessionLocal() as session:
+        yield session
+        await session.rollback()
+
+
+@pytest_asyncio.fixture
+async def client(db_session: AsyncSession):
+    app = create_app()
+
+    async def override_get_db():
+        yield db_session
+
+    app.dependency_overrides[get_db] = override_get_db
+
+    async with AsyncClient(
+        transport=ASGITransport(app=app), base_url="http://test"
+    ) as ac:
+        yield ac
+
+
+@pytest_asyncio.fixture
+async def registered_user(client: AsyncClient) -> dict:
+    resp = await client.post("/users/", json={
+        "email": "test@example.com",
+        "username": "testuser",
+        "password": "securepass1",
+        "password_confirm": "securepass1",
+    })
+    assert resp.status_code == 201
+    return resp.json()
+
+
+@pytest_asyncio.fixture
+async def auth_token(client: AsyncClient, registered_user: dict) -> str:
+    resp = await client.post("/users/token", data={
+        "username": "test@example.com",
+        "password": "securepass1",
+    })
+    assert resp.status_code == 200
+    return resp.json()["access_token"]
+
+
+@pytest_asyncio.fixture
+async def auth_client(client: AsyncClient, auth_token: str) -> AsyncClient:
+    client.headers.update({"Authorization": f"Bearer {auth_token}"})
+    return client
+```
+
+---
+
+## Antipatrones
+
+```python
+# Mal: lógica de negocio dentro de los handlers de ruta.
+@router.post("/users/")
+async def create_user(payload: UserCreate, db: DbDep):
+    hashed = bcrypt.hash(payload.password)
+    user = User(email=payload.email, hashed_password=hashed)
+    db.add(user)
+    await db.commit()
+    return user
+
+# Bien: ruta delgada, manejo transaccional en el servicio.
+@router.post("/users/", response_model=UserResponse, status_code=201)
+async def create_user(payload: UserCreate, db: DbDep):
+    try:
+        return await UserService(db).create(payload)
+    except DuplicateUserError:
+        raise HTTPException(status_code=400, detail="El email ya está registrado")
+
+
+# Mal: llamadas síncronas a la BD en rutas async bloquean el event loop.
+@router.get("/items/")
+async def list_items(db: Session = Depends(get_db)):
+    return db.query(Item).all()
+
+# Bien: usar ejecuciones async de SQLAlchemy.
+@router.get("/items/")
+async def list_items(db: AsyncSession = Depends(get_db)):
+    result = await db.execute(select(Item))
+    return result.scalars().all()
+```
+
+---
+
+## Buenas prácticas
+
+- Declara siempre un `response_model` tipado para prevenir fugas accidentales de PII/datos y producir esquemas OpenAPI limpios.
+- Consolida las inyecciones de dependencias estándar mediante alias de tipo: `DbDep = Annotated[AsyncSession, Depends(get_db)]`.
+- Envuelve los límites de mutación de la base de datos en transacciones dentro de tu capa de servicio, capturando directamente los errores estructurales de la BD.
+- Parsea los parámetros del JWT de forma defensiva, anticipando posibles desajustes de casteo string/entero en variaciones modernas de payload.
+- Fuerza un ordenamiento determinista (p. ej., `.order_by(Model.id)`) en todos los endpoints paginados con offset/limit para evitar saltos de datos.
+- Aísla las comprobaciones de autorización de las dependencias centrales de autenticación para dar señales REST precisas (`401` vs `403`).