"""Overview version snapshotting — port of v1 ``snapshot_overview``
(main.py ~2096-2119).

Before a service overwrites an entity's overview-style field (species/variety
``description``, year/area ``notes``), it snapshots the *previous* content
into ``overview_versions`` so history is never lost. Idempotent: no row is
written when the content is unchanged.

v1 read the current value back from the DB; in v2 the calling service already
holds the ORM row, so it passes the current content explicitly.
"""
from __future__ import annotations

from datetime import datetime, timezone

from sqlalchemy.orm import Session

from ..models.history import OverviewVersion


def snapshot_overview(
    db: Session,
    entity_type: str,
    entity_id: int,
    current_content: str | None,
    new_content: str | None,
    author: str = "user",
    change_note: str = "",
) -> None:
    """Snapshot ``current_content`` if ``new_content`` differs. No-op
    otherwise — mirrors v1's unchanged-content early return."""
    if (current_content or "") == (new_content or ""):
        return
    db.add(
        OverviewVersion(
            entity_type=entity_type,
            entity_id=entity_id,
            content=current_content or "",
            created_at=datetime.now(timezone.utc),
            author=author,
            change_note=change_note,
        )
    )