from sqlalchemy.ext.asyncio import AsyncSession
from app.models.user import AuditLog


async def log_audit(
    db: AsyncSession,
    user_id: int | None,
    action: str,
    resource: str,
    detail: str = "",
    ip_address: str | None = None,
):
    """Write an audit log entry.

    Args:
        db: async database session (must be flushed/committed by caller)
        user_id: ID of the acting user (None for system actions)
        action: one of login, create, update, delete, export, view,
                acknowledge, resolve
        resource: one of user, device, alarm, report, system, auth
        detail: human-readable description
        ip_address: client IP if available
    """
    entry = AuditLog(
        user_id=user_id,
        action=action,
        resource=resource,
        detail=detail,
        ip_address=ip_address,
    )
    db.add(entry)
    # Don't flush here — let the caller's transaction handle it