"""Shared helpers for Feishu API routes."""

from __future__ import annotations

from typing import Any, Dict, Optional


def build_long_connection_failure(long_status: Dict[str, Any]) -> tuple[str, Optional[str]]:
    code = str(long_status.get("last_error_code") or "").strip().lower()
    last_error = str(long_status.get("last_error") or "").strip()
    retryable = bool(long_status.get("last_error_retryable"))
    if code in {"network_error", "thread_exited"} and not retryable:
        return (
            "长连接自动重连次数已耗尽，请检查网络/凭证后手动重启飞书长连接",
            last_error or None,
        )
    if code == "auth_failed":
        return (
            "长连接鉴权失败，请检查 App ID / App Secret、应用凭证是否已生效，以及飞书应用权限是否完整",
            last_error or None,
        )
    if code == "network_error":
        return (
            "长连接预检失败，后端到飞书开放平台的网络或 TLS 证书链异常",
            last_error or None,
        )
    if code == "sdk_missing":
        return ("长连接 SDK 未安装（缺少 lark-oapi）", None)
    if code == "thread_exited":
        return ("长连接已退出，系统正在等待下一次自动重连窗口", last_error or None)
    if last_error:
        return ("长连接未建立，请检查配置与后端日志", last_error)
    return ("长连接未建立，请检查配置后重试", None)