"""修复已撤回 migration 写入的 alembic_version（跨环境一次性兼容）。"""

from __future__ import annotations

from sqlalchemy import Connection, text

_WITHDRAWN_0020_REVISIONS = frozenset(
    {
        "0020_add_tts_audio_urls_column",
        "0020_backfill_missing_schema",
        "0020_backfill_all_missing_columns",
        # 曾本地试运行后从仓库撤回，仅 dev 库可能残留 stamp
        "0020_chapters_book_id",
    }
)
_REPAIR_TARGET_REVISION = "0018_users_language_preference"


def try_repair_withdrawn_0020_revision(conn: Connection) -> bool:
    """
    若当前 stamp 为已撤回的 0020_*，回退到 0018 以便重新执行 0019_align_legacy_schema。

    返回 True 表示已执行 UPDATE；调用方负责 commit。
    """
    row = conn.execute(text("SELECT version_num FROM alembic_version")).fetchone()
    if row is None:
        return False
    current = row[0]
    if current not in _WITHDRAWN_0020_REVISIONS:
        return False
    conn.execute(
        text("UPDATE alembic_version SET version_num = :target"),
        {"target": _REPAIR_TARGET_REVISION},
    )
    return True