"""Audit log helper. Every state-changing endpoint must call record_audit."""

import json
from typing import Any

from sqlmodel import Session

from ten31portal.models import AuditLog


def record_audit(
    session: Session,
    actor_user_id: int | None,
    action: str,
    object_type: str,
    object_id: int | None = None,
    detail: Any = None,
) -> AuditLog:
    """Write one audit log entry and flush it.

    ``detail`` is a small JSON-serializable payload describing the change (typically a dict of
    changed fields, sometimes an identifying value on delete, or None). It is persisted to a
    JSON column on AuditLog.
    """
    entry = AuditLog(
        actor_user_id=actor_user_id,
        action=action,
        object_type=object_type,
        object_id=object_id,
        detail=detail,
    )
    session.add(entry)
    session.flush()
    return entry