# [DEF:backend.src.services.clean_release.audit_service:Module]
# @TIER: STANDARD
# @SEMANTICS: clean-release, audit, lifecycle, logging
# @PURPOSE: Provide lightweight audit hooks for clean release preparation/check/report lifecycle.
# @LAYER: Infra
# @RELATION: DEPENDS_ON -> backend.src.core.logger
# @INVARIANT: Audit hooks are append-only log actions.

from __future__ import annotations

from datetime import datetime, timezone
from typing import Any, Dict, Optional
from uuid import uuid4

from ...core.logger import logger


def _append_event(repository, payload: Dict[str, Any]) -> None:
    if repository is not None and hasattr(repository, "append_audit_event"):
        repository.append_audit_event(payload)


def audit_preparation(candidate_id: str, status: str, repository=None, actor: str = "system") -> None:
    logger.info(f"[REASON] clean-release preparation candidate={candidate_id} status={status}")
    _append_event(
        repository,
        {
            "id": f"audit-{uuid4()}",
            "action": "PREPARATION",
            "candidate_id": candidate_id,
            "actor": actor,
            "status": status,
            "timestamp": datetime.now(timezone.utc).isoformat(),
        },
    )


def audit_check_run(
    check_run_id: str,
    final_status: str,
    repository=None,
    *,
    candidate_id: Optional[str] = None,
    actor: str = "system",
) -> None:
    logger.info(f"[REFLECT] clean-release check_run={check_run_id} final_status={final_status}")
    _append_event(
        repository,
        {
            "id": f"audit-{uuid4()}",
            "action": "CHECK_RUN",
            "run_id": check_run_id,
            "candidate_id": candidate_id,
            "actor": actor,
            "status": final_status,
            "timestamp": datetime.now(timezone.utc).isoformat(),
        },
    )


def audit_violation(
    run_id: str,
    stage_name: str,
    code: str,
    repository=None,
    *,
    candidate_id: Optional[str] = None,
    actor: str = "system",
) -> None:
    logger.info(f"[EXPLORE] clean-release violation run_id={run_id} stage={stage_name} code={code}")
    _append_event(
        repository,
        {
            "id": f"audit-{uuid4()}",
            "action": "VIOLATION",
            "run_id": run_id,
            "candidate_id": candidate_id,
            "actor": actor,
            "stage_name": stage_name,
            "code": code,
            "timestamp": datetime.now(timezone.utc).isoformat(),
        },
    )


def audit_report(
    report_id: str,
    candidate_id: str,
    repository=None,
    *,
    run_id: Optional[str] = None,
    actor: str = "system",
) -> None:
    logger.info(f"[EXPLORE] clean-release report_id={report_id} candidate={candidate_id}")
    _append_event(
        repository,
        {
            "id": f"audit-{uuid4()}",
            "action": "REPORT",
            "report_id": report_id,
            "run_id": run_id,
            "candidate_id": candidate_id,
            "actor": actor,
            "timestamp": datetime.now(timezone.utc).isoformat(),
        },
    )
# [/DEF:backend.src.services.clean_release.audit_service:Module]