0030. Auditoría propia del servicio e historial por registro¶
Estado: Aceptado Fecha: 2026-10-27 Autor: David Garcia Módulo(s) afectado(s): app/core/, app/api/deps.py, app/domains/, alembic/, tests/unit/
Contexto¶
AuditMixin guarda quién creó y quién modificó por última vez cada fila, pero
no qué cambió ni los valores anteriores. Se necesita un historial como el
chatter de Odoo: en la página de un registro, lo que le pasó; en la página de
un catálogo, todo lo que se hizo en ese catálogo. docs-sql preveía una
bitácora central (erp.audit_log, en svc-identidad); se decidió reemplazarla
por tablas de auditoría propias de cada servicio (ADR transversal pendiente).
Después se sumará fuerza-ventas con el mismo diseño.
Decisión¶
- Dos tablas en el esquema
clientes, conEmpresaMixiny RLS, sinAuditMixin: sólo se insertan, nunca se editan ni se borran. aud_eventos:referencia_tipo/referencia_id(el registro en cuyo historial aparece),entidad_tipo/entidad_id(la fila que cambió),entidad_descripcion(ver abajo),tipo(creacion,cambio,borrado,restauracion),actor_user_id,actor_username(copia del token),permiso_codigo,metodo_http,endpointycreated_at.aud_cambios: un registro por campo modificado:evento_id,campo,etiqueta,valor_anterior/valor_nuevo(el texto que se muestra, copiado en el momento) yvalor_anterior_id/valor_nuevo_id(el UUID, cuando el campo apunta a otra tabla).- Lo escriben listeners de la
Session(app/shared/auditoria), comoauditar_cambiosllenacreated_by/updated_by:after_flushlee los ids y los valores anteriores, y los eventos se insertan en la misma transacción que el cambio. Sólo audita los modelos que declaran__seguimiento__(campos seguidos y su etiqueta). Marcardeleted_atesborradoy limpiarlo esrestauracion. Sin usuario en la sesión (migraciones, scripts) no se registra nada. - Qué detalle lleva cada evento:
creacion, los valores iniciales no vacíos de los campos seguidos (anterior vacío);cambio, los campos que cambiaron;borradoyrestauracion, sólo los campos seguidos que cambiaron con ellos, más la identidad cuando la fila se identifica con un id de otro servicio (hoy,promotor_idde la asignación), para saber qué promotor se quitó. - Referencias a otros servicios (
tipo_identificacion_idyciudad_idde core,promotor_idde fuerza-ventas) se guardan sólo como UUID, sin texto: los adaptadores sólo exponenexiste. El frontend muestra el nombre actual; qué registro era no se pierde, sólo cómo se llamaba si lo renombran en su servicio. Ciudades y tipos de identificación son catálogos globales de identidad, sin alcance: el frontend los nombra con su lista (una ciudad borrada después se muestra como eliminada). - Excepción: el promotor. Su nombre es el de su entidad en identidad, y
quien lee el historial puede no verlo en fuerza-ventas (alcance). Al
escribir, svc-clientes pide
GET /promotores/{id}con el token de quien escribe, que lo ve (asignar, quitar o transferir exige tenerlo en su alcance), y guarda su entidad enaud_cambios.valor_anterior_entidad_id/valor_nuevo_entidad_id. El frontend la nombra con la lista global de entidades, como al supervisor (ADR 0050 de fuerza-ventas). El service la pide antes delcommity de bloquear filas, y la deja en la sesión: el listener sólo la copia. Si fuerza-ventas no encuentra al promotor, la entidad queda vacía. entidad_descripcion: texto que identifica la fila hija en el historial del padre ("Local L001 · Matriz"), copiado en el momento del evento. Sólo se llena cuandoentidad_tipo ≠ referencia_tipo, y cada modelo hijo define cómo se arma con datos de este servicio: local,codigo · nombre; perfil financiero,anio; vínculo con contacto, el nombre del contacto; asignación de promotor, vacía (supromotor_idva en el detalle).- Lo que depende del cliente se registra en el historial del cliente:
locales, vínculos con contactos, asignaciones de promotor y perfil
financiero tienen
referencia_tipo = 'cliente'y su propiaentidad_tipo. Cambiar el tipo de cliente de un cliente aparece en su historial; renombrar el catálogo, sólo en el del catálogo. get_db_empresaguarda ensession.infoelusername, el método, el endpoint y el permiso de la ruta, además del usuario que ya guarda.- Lectura:
GET /api/v1/auditoria?referencia_tipo=…[&referencia_id=…][&antes_de=…], del más reciente al más antiguo y paginada porid(uuidv7), de alimiteeventos (50 por defecto, 100 como máximo). Exige el permiso de lectura del menú de esereferencia_tipo, según una tabla en el código:verconreferencia_id(un registro) ylistarsin él (la página completa), comoGET /{id}y la lista. Un tipo desconocido da 404. Encliente,prospectoycontactoaplica además la visibilidad de suGET(ADR 0029): un registro que el usuario no ve da 404, y el historial de la página trae sólo los eventos de los registros que hoy ve (si un cliente pasa a otro equipo, su historial se va con él). La decide el dominio de clientes: el router desharedla recibe al montarse enapp.main, sin importar el dominio (ADR 0002). - Nombres de otro dominio del servicio (los catálogos en el cliente y el prospecto) se leen por el nombre de la tabla, sin importar ese dominio (ADR 0002).
- Índices:
(empresa_id, referencia_tipo, referencia_id, id)para el historial de un registro y(empresa_id, referencia_tipo, id)para el de una página completa. - Fuera del alcance: notas escritas por el usuario, auditar lecturas, adjuntos y seguidores.
Alternativas descartadas¶
- Bitácora central
erp.audit_log: escribirla exige ir a otra base en cada transacción, y sudatos_antes/datos_despuesen jsonb no trae etiquetas ni nombres para mostrar. - Triggers genéricos en PostgreSQL con la fila en jsonb: registran hasta el SQL directo, pero sin etiquetas ni textos de catálogo, y el historial habría que reconstruirlo al leer.
- Registrar el cambio en cada service: cualquier escritura nueva que lo olvide se queda sin auditar.
- Filtrar el historial de una página por
permiso_codigo: desde una página se editan varias entidades (desde el cliente, sus locales); lo que el usuario ve es la entidad, no el permiso.
Consecuencias¶
- Cada escritura auditada suma inserciones en la misma transacción y, si cambia una referencia a otra tabla, una consulta para copiar su nombre. La que toca un promotor suma una llamada a fuerza-ventas por promotor distinto (una por request); si no responde, 503, como al pedir el alcance.
- Un
UPDATE/DELETEmasivo (update(),delete()) o un SQL directo no dispara el evento y no se audita; hoy ningún repository los usa. - Si core o fuerza-ventas renombran una ciudad, un tipo de identificación o un promotor, el historial muestra el nombre nuevo también en los eventos viejos. Copiar el texto exigiría llamarlos en cada escritura; podrá hacerse sin cambiar las tablas si un día publican eventos con el nombre.
- El historial empieza vacío: lo anterior al despliegue sólo conserva
created_by/updated_by. - fuerza-ventas necesitará primero su propio
auditar_cambios, que hoy no tiene. - docs-sql debe retirar
erp.audit_logy documentaraud_eventos/aud_cambiospor servicio.
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.