Saltar a contenido

0021. Dominio promotores: una persona por promotor, PUT completo y restauración del borrado

Estado: Aceptado Fecha: 2026-10-08 Autor: David Garcia Módulo(s) afectado(s): app/domains/promotores/, alembic/versions/20261008_001_crear_mae_promotores.py

Contexto

mae_promotores es el primer maestro del servicio. El borrador del modelo de datos lo liga a un usuario de identidad (usuario_id) y a una persona (persona_id), pero este servicio todavía no consulta a identidad. Además, a diferencia de un catálogo (ADR 0015), un promotor guarda dinero (comisión y cupo de crédito) y lo referencian otras tablas, así que un PUT incompleto o un borrado por error cuestan más.

Decisión

  • Sin usuario_id. El promotor se identifica por persona_id, que llega en el POST, no se edita y es único por empresa aunque el promotor esté borrado (uq_mae_promotores_empresa_persona). Todavía no se valida contra identidad.
  • PUT con todos los campos editables obligatorios: omitir uno responde 422, nunca vuelve a su valor por defecto. Código y persona no se envían.
  • Un promotor borrado no se edita (409); se restaura con POST /promotores/{id}/restaurar, que es idempotente.
  • El 409 por código o persona repetidos da el id del promotor existente y avisa si está borrado, para restaurarlo en vez de crear otro.
  • Una carrera también responde 409. Si otro request guarda el mismo código o persona entre la comprobación y el INSERT, el repository convierte el unique_violation (SQLSTATE 23505) en Duplicado tras el rollback, y el service vuelve a buscar al existente para dar el mismo 409. Otra violación de integridad (FK, CHECK) sigue siendo 500.
  • Tipo de promotor y modalidad de comisión van por FK compuesta (empresa_id, id); uno inexistente o borrado responde 400, salvo que el promotor ya lo tuviera.

Alternativas descartadas

  • Derivar persona_id del usuario en identidad — exige la integración con identidad antes de tener el maestro.
  • PATCH parcial — un body incompleto cambiaría sólo parte del promotor sin que quien llama lo note; el PUT completo es además el contrato de los catálogos.
  • UNIQUE parcial WHERE deleted_at IS NULL — permitiría recrear la persona, pero dejaría dos promotores para ella; restaurar conserva su id y su historia.
  • INSERT ... ON CONFLICT — sólo resuelve la inserción, y el mensaje necesita al promotor existente de todos modos.

Consecuencias

  • Mientras no haya integración, se puede guardar un persona_id que no exista en identidad.
  • Los catálogos siguen sin restaurar y con el 500 ante la carrera; llevarles esto queda pendiente del estándar de services y repositories.
  • La RLS, el UNIQUE por empresa y la carrera real sólo se prueban contra PostgreSQL, y aún no hay tests de integración.

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.