Saltar a contenido

0001. Stack, dependencias y herramientas de calidad

Estado: Aceptado Fecha: 2026-10-05 Autor: David Garcia Módulo(s) afectado(s): pyproject.toml, poetry.lock, app/

Contexto

Todos los servicios de la plataforma comparten el mismo stack (ADR 0005 transversal), y crm-svc-clientes y core-svc-identidad ya lo fijaron en su ADR 0001. Este servicio arranca después y tiene dos diferencias: valida tokens de identidad contra su JWKS, así que necesita un cliente HTTP en producción, y no firma tokens ni guarda contraseñas.

Decisión

  • Python >=3.14,<4.0 y Poetry, con pyproject.toml en formato PEP 621 y las dependencias de desarrollo en [dependency-groups]. Se versiona poetry.lock.
  • Ejecución: fastapi, uvicorn[standard], sqlalchemy[asyncio], asyncpg, alembic, pydantic, pydantic-settings, python-jose[cryptography], argon2-cffi y httpx2. El extra asyncio de SQLAlchemy instala greenlet (ADR 0012).
  • httpx2 va en producción, no en desarrollo: descarga el JWKS de identidad (ADR 0007). También es el cliente de las pruebas.
  • python-jose lo fija arquitectura para toda la plataforma. Sus CVE sin corregir se mitigan al usarlo (ADR 0007), no reemplazándolo.
  • argon2-cffi se mantiene por consistencia con el stack común, aunque este servicio no hashea contraseñas.
  • Desarrollo: pytest, pytest-asyncio, pytest-cov, ruff y mypy.
  • Calidad: ruff check (reglas E, F, I, UP, B) y ruff format, mypy en modo strict con el plugin de pydantic, y pytest con asyncio_mode = "auto". Sin black.

Alternativas descartadas

  • Python 3.12 como los otros servicios — el servicio nace nuevo y no arrastra código que lo ate a una versión anterior.
  • PyJWT o joserfc en lugar de python-jose — no es una decisión de este servicio; ya se avisó a arquitectura.
  • httpx2 sólo en desarrollo — el servicio no arrancaría la validación del token en producción.

Consecuencias

  • python-jose no publica tipos: mypy ignora sólo los imports jose.*.
  • argon2-cffi es una dependencia instalada y sin uso; si arquitectura la libera, se quita.
  • Las migraciones de alembic/versions/ quedan exentas de E501, F401 e I001: las genera Alembic y las formatea ruff format vía post_write_hooks.

Media página como máximo. Si el ADR crece más que eso, probablemente estás documentando el diseño completo del módulo, no una decisión puntual — separa.