Registro de auditoría

Audience

Este artículo es para operadores de la plataforma GCM. Los administradores de iglesia ven una rebanada por organización de los mismos datos en Configuración -> Actividad dentro de su espacio de trabajo — esta página es el superconjunto cross-tenant, restringido al personal.

El registro de auditoría (/platform/audit) es el registro canónico de cada acción del personal y cada evento relevante para la seguridad en GCM. Organización creada, plan cambiado, reembolso emitido, suplantación iniciada, suplantación finalizada, inicio de sesión fallido, restablecimiento de contraseña activado, rol asignado — todos aterrizan en platform_audit_log con el actor, el objetivo, la marca de tiempo y un blob de metadatos JSONB. Esta pestaña es como preguntas "quién hizo qué, cuándo, a quién".

La franja de KPIs

Tres conteos en la parte superior, todos en vivo:

• Eventos totales — cada fila en platform_audit_log, jamás. Es útil sobre todo como verificación de cordura de que el escritor sigue escribiendo.
• Eventos hoy — filas desde la medianoche en la zona horaria de la plataforma. Un día normal son miles bajos; un fin de semana tranquilo son cientos. Un cero repentino normalmente significa que el escritor de auditoría se rompió.
• Suplantaciones (7 días) — filas donde action ilike '%impersonat%' en la última semana. Esta es la métrica para vigilar — cada inicio, fin y fallo de suplantación cuenta. Los picos aquí merecen una lectura rápida.

El visor

Debajo de la franja se encuentra el componente unificado AuditLogViewer, también usado por la página de actividad delimitada por organización. Admite:

• Rango de fechas — desde / hasta con granularidad por día. Por defecto los últimos 30 días.
• Acción — desplegable de valores distintos en platform_audit_log.action. La lista se auto-popula desde la base de datos para mantenerse al día a medida que se agregan nuevas acciones.
• Actor — coincidencia parcial de correo. Úsalo para delimitar a un usuario del personal.
• Organización — por id de organización. Busca en la ruta jsonb metadata->>target_org_id para capturar cada evento que menciona una organización, incluso cuando la propia organization_id de la fila es nula.

Los filtros se componen; limpiar uno mantiene los demás activos.

Leyendo una fila

Cada fila de la tabla muestra:

• Cuándo — marca de tiempo exacta.
• Acción — el verbo. El conjunto completo está documentado en la migración que añade la restricción de columna; las comunes incluyen org_created, plan_updated, refund_processed, subscription_overridden, impersonation_started, impersonation_failed, email_template_updated, auth_login_failed.
• Actor — correo del usuario del personal que activó la fila. Las filas de edge function y cron muestran system@geniuschurchmanager.com.
• Objetivo — el nombre de la organización afectada (resuelto desde los metadatos) o "platform" para filas de toda la plataforma.
• Metadatos — vista previa JSONB truncada.

Haz clic en cualquier fila para expandir los metadatos. Los reembolsos, por ejemplo, almacenan el importe original, el importe del reembolso, el método manual (si es fuera de plataforma) y el texto del motivo. Las sobrescrituras de suscripción almacenan los valores antes / después de cada campo cambiado.

Investigaciones comunes

"¿Quién reembolsó ese pago de $79 de First Church el martes?" Filtra action = refund_processed, establece el rango de fechas al martes, filtra organisation = First Church. La columna del actor es tu respuesta.

"¿Alguien de nuestro equipo ha iniciado sesión en el espacio de trabajo de Second Baptist este mes?" Filtra action = impersonation_started, establece el rango de fechas a "el mes", filtra organisation = Second Baptist. Cada fila lleva el motivo en metadatos — lee esos a continuación.

"¿De verdad cambió el plan del cliente la semana pasada o se lo está imaginando?" Filtra action = plan_updated, filtra organisation = <su organización>. Si existe una fila, los metadatos muestran el id del plan antes/después y quién lo hizo. Si no existe ninguna fila, el cliente lo está recordando mal — pero verifica también subscription_overridden por si el cambio vino a través del diálogo de edición de operaciones de facturación.

"¿Cuántos inicios de sesión fallidos en las últimas 24 horas?" Acción auth_login_failed, rango de fechas "ayer a hoy". Cruza el actor con la pestaña Usuarios para ver si una cuenta está siendo objetivo.

Referencia de acciones (las importantes)

Acción	Cuándo se dispara	Metadatos clave
org_created	Nueva organización provisionada	org_name, org_slug, plan_id, created_by_admin
org_deleted	Eliminación dura	org_name, org_slug, member_count, reason
plan_updated	Cambio de plan en línea en la pestaña Organizaciones	target_org_id, previous_plan, new_plan
subscription_overridden	Diálogo de edición de suscripción	target_org_id, before, after, reason, email_sent
renewal_triggered	Renovación manual (modo cobro)	target_org_id, mode, reason, result
refund_processed	Modal de reembolso	payment_history_id, amount, refund_type, reason
impersonation_started	Abrir cuenta desde la hoja de organización	target_org_id, org_name, reason
impersonation_ended	Regresar a la plataforma	target_org_id
impersonation_failed	El RPC rechazó el inicio	target_org_id, reason, error
email_template_updated	Guardar en la pestaña Plantillas de correo	slug, before, after
landing_content_updated	Guardar en la pestaña Landing	section, content_key, locale, before, after
branding_settings_saved	Guardar en la pestaña Branding	keys
auth_login_failed	Contraseña incorrecta o correo desconocido	email, ip, user_agent

La lista no es exhaustiva — se agregan nuevas acciones con cada característica.

Retención

platform_audit_log no se purga automáticamente. Las filas viven para siempre hasta que alguien las elimine, y deliberadamente no exponemos una interfaz para hacerlo — el rastro de auditoría es el rastro de auditoría. Si necesitas reducir el tamaño de la tabla para una migración, escribe una migración que archive a una tabla de almacenamiento en frío y documéntala en docs/runbooks/.

Lo que no puedes hacer aquí

El visor es de solo lectura. No hay "editar", no hay "anotar", no hay "marcar importante". Si necesitas adjuntar contexto a una fila, escribe una nueva fila realizando la acción que describe (por ejemplo, agrega un comentario en Slack en el ticket al que la fila de auditoría hace referencia, o abre el issue de Sentry vinculado). Trata el registro de auditoría como funciona una caja negra de vuelo: solo lectura, escritura única, nunca el lugar al que vas a borrar un problema.