"""Field-level audit hooks for RIMS grants.

Implements the comprehensive action-logging requirement called out by
PRD §5.1 FRFA-AM041 ("log all actions across all application management
sub-processes"), as well as the wider PRD NFRFA011 / FRFA-GPS025 audit
trails. Every privileged write inside ``apps.rims.grants`` calls
:func:`audit_rims` so reviewers / archivists can reconstruct who did what.
"""

from __future__ import annotations

from typing import Any

from apps.core.audit.mixins import log_audit
from apps.core.audit.middleware import AuditMiddleware
from apps.core.audit.models import AuditLog


def audit_rims(
    *,
    actor,
    action: str,
    target_model: str,
    object_id,
    object_repr: str = "",
    changes: dict[str, Any] | None = None,
    request=None,
) -> None:
    ip = None
    ua = ""
    if request is not None:
        ip = AuditMiddleware._client_ip(request)
        ua = (request.META.get("HTTP_USER_AGENT") or "")[:512]
    log_audit(
        actor=actor,
        action=action,
        target_app="rims_grants",
        target_model=target_model[:64],
        object_id=str(object_id)[:64] if object_id is not None else "",
        object_repr=(object_repr or "")[:200],
        changes=changes,
        ip_address=ip,
        user_agent=ua,
    )


def action_update() -> str:
    return AuditLog.Action.UPDATE


def action_create() -> str:
    return AuditLog.Action.CREATE