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 porpersona_id, que llega en elPOST, 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. PUTcon 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(SQLSTATE23505) enDuplicadotras 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_iddel usuario en identidad — exige la integración con identidad antes de tener el maestro. PATCHparcial — un body incompleto cambiaría sólo parte del promotor sin que quien llama lo note; elPUTcompleto 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_idque 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.