Saltar a contenido

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, con EmpresaMixin y RLS, sin AuditMixin: 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, endpoint y created_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) y valor_anterior_id / valor_nuevo_id (el UUID, cuando el campo apunta a otra tabla).
  • Lo escriben listeners de la Session (app/shared/auditoria), como auditar_cambios llena created_by / updated_by: after_flush lee 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). Marcar deleted_at es borrado y limpiarlo es restauracion. 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; borrado y restauracion, 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_id de la asignación), para saber qué promotor se quitó.
  • Referencias a otros servicios (tipo_identificacion_id y ciudad_id de core, promotor_id de fuerza-ventas) se guardan sólo como UUID, sin texto: los adaptadores sólo exponen existe. 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 en aud_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 del commit y 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 cuando entidad_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 (su promotor_id va 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 propia entidad_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_empresa guarda en session.info el username, 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 por id (uuidv7), de a limite eventos (50 por defecto, 100 como máximo). Exige el permiso de lectura del menú de ese referencia_tipo, según una tabla en el código: ver con referencia_id (un registro) y listar sin él (la página completa), como GET /{id} y la lista. Un tipo desconocido da 404. En cliente, prospecto y contacto aplica además la visibilidad de su GET (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 de shared la recibe al montarse en app.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 su datos_antes / datos_despues en 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 / DELETE masivo (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_log y documentar aud_eventos / aud_cambios por 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.