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:
- El
PUTdel 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. - El
object_keyinterno 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_intencioninserta una fila conestado = 'pendiente'. Suid(UUIDv7, generado en el service conuuid.uuid7()porque tiene que existir antes de pedir la subida) es el nombre del archivo y elupload_idopaco que ve el frontend. La clave quedausuarios/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 sucommiten una transacción corta. Esto es posible porque elidy 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. confirmarrecibe solo elupload_id: busca la pendiente del usuario del token (si no existe o es ajena responde 404), valida conheadque el objeto exista y que tipo y tamaño coincidan con lo declarado en la intención (si no, 409), pasa la fila aconfirmada, da de baja lógica la anterior y apuntamae_usuarios.imagen_ida la nueva, todo en una transacción. Después del commit borra el objeto anterior como mejor esfuerzo. Confirmar unupload_idque ya es la imagen vigente es idempotente.- La intención ahora declara
nombreyhash_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
PUTabandonado o fallido deja un objeto huérfano, pero nunca altera la foto del usuario. - El
object_keyya 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
INSERTde 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
pendienteabandonadas 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
downgradeborra 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.