Saltar a contenido

0065. Subida de la foto de perfil con fila pendiente

Estado: Aceptado
Fecha: 2026-11-10
Módulo(s) afectado(s): app/domains/usuarios/, alembic/versions/, tests/

Contexto

El flujo de la foto de perfil (ADR 0061) pide a svc-documentos una subida prefirmada, el navegador sube el binario directo al almacenamiento y después identidad confirma. La clave del objeto era fija por usuario (usuarios/perfil/{usuario_id}.{ext}), con dos problemas:

  1. El PUT del navegador pisa la foto vigente antes de confirmar. Si la confirmación nunca llega, o falla la validación, la foto del usuario ya cambió en el almacenamiento aunque la base siga apuntando a ella.
  2. El object_key interno viajaba al frontend, que lo devolvía en la confirmación. Identidad tenía que validar que fuera del usuario porque el dato venía del cliente.

Decisión

La subida es una fila pendiente en identidad.mae_usuarios_img:

  • crear_intencion inserta una fila con estado = 'pendiente'. Su id (UUIDv7, generado en el service con uuid.uuid7() porque tiene que existir antes de pedir la subida) es el nombre del archivo y el upload_id opaco que ve el frontend. La clave queda usuarios/perfil/{usuario_id}/{id}.{ext}, nueva en cada intento, así que subir nunca pisa la foto vigente.
  • Ninguna transacción queda abierta durante la llamada HTTP a documentos. El orden es: leer la cuenta, cerrar esa transacción de lectura (rollback, que devuelve la conexión al pool), pedir la subida a documentos y recién entonces insertar la fila pendiente con su commit en una transacción corta. Esto es posible porque el id y la clave se calculan en identidad sin consultar la base. Si documentos falla, o devuelve una clave distinta de la esperada, no se escribe ninguna fila.
  • confirmar recibe solo el upload_id: busca la pendiente del usuario del token (si no existe o es ajena responde 404), valida con head que el objeto exista y que tipo y tamaño coincidan con lo declarado en la intención (si no, 409), pasa la fila a confirmada, da de baja lógica la anterior y apunta mae_usuarios.imagen_id a la nueva, todo en una transacción. Después del commit borra el objeto anterior como mejor esfuerzo. Confirmar un upload_id que ya es la imagen vigente es idempotente.
  • La intención ahora declara nombre y hash_sha256, porque la fila se crea ahí.

Se agrega estado (String(20), NOT NULL, server_default 'confirmada') con un CHECK (ck_mae_usuarios_img_estado) que admite pendiente y confirmada. El índice único parcial uq_mae_usuarios_img_usuario_id pasa de deleted_at IS NULL a deleted_at IS NULL AND estado = 'confirmada': puede haber varias pendientes, pero una sola confirmada vigente por usuario. Las filas existentes quedan confirmada por el default y siguen leyéndose y borrándose con sus claves del formato anterior. La migración es 20261110_001_estado_subida_imagen_usuario.py.

Contrato para los frontends

Las rutas son las mismas en ambas audiencias (/api/v1/usuarios/me/foto/... y /api/v1/usuarios/admin/perfil/foto/...).

Endpoint Antes Después
POST .../intencion (cuerpo) content_type, size_bytes content_type, size_bytes, nombre, hash_sha256
POST .../intencion (respuesta) object_key, upload, expires_at upload_id, upload, expires_at
POST .../confirmar (cuerpo) object_key, nombre, hash_sha256 upload_id
POST .../confirmar (errores nuevos) no aplica 404 subida inexistente o ajena, 409 el archivo no coincide con lo declarado
GET y DELETE .../foto sin cambios sin cambios

El frontend conserva el upload_id entre la intención y la confirmación y deja de manejar la clave del objeto.

Consecuencias

  • La foto vigente solo cambia al confirmar: un PUT abandonado o fallido deja un objeto huérfano, pero nunca altera la foto del usuario.
  • El object_key ya no sale de identidad y el cliente no puede apuntar la confirmación a una clave arbitraria. La validación de la clave se conserva como defensa en profundidad (ObjectKeyAjenoError, 403).
  • Una llamada lenta a documentos ya no retiene una conexión del pool. Si las intenciones concurrentes retuvieran conexiones mientras esperan la red, el pool se agotaría y fallarían también las rutas que no tienen nada que ver con fotos.
  • Si documentos responde bien pero el INSERT de la fila falla, queda emitida una URL prefirmada sin fila. El frontend recibe un 500 y no sube; si subiera, la confirmación responde 404 porque la subida no existe. El objeto, si llega a existir, es un huérfano más para la tarea de limpieza.
  • Las filas pendiente abandonadas y sus objetos quedan sin limpiar. Queda fuera de este cambio una tarea de limpieza que las dé de baja y borre el objeto.
  • También quedan fuera las fallas 3 y 4 del análisis del flujo; se tratan en cambios aparte.
  • El downgrade borra las filas pendientes antes de recrear el índice anterior, porque bajo ese índice chocarían con la imagen vigente.
  • La migración no se aplicó contra una base en este cambio: se verifica en el despliegue con alembic upgrade head.