ChingTech OS：Telegram Bot 完整實作

class TelegramBotAdapter:
    """同時實作 BotAdapter / EditableMessageAdapter / ProgressNotifier"""

    platform_type: str = "telegram"

    def __init__(self, token: str):
        self.bot = Bot(token=token)
        self._bot_username: str | None = None

    async def ensure_bot_info(self) -> None:
        """取得並快取 Bot 資訊（username 等）"""
        if self._bot_username is None:
            me = await self.bot.get_me()
            self._bot_username = me.username

async def send_file(self, target, file_url, file_name, **kwargs):
    # 先下載檔案到記憶體
    async with httpx.AsyncClient(follow_redirects=True, timeout=60) as client:
        resp = await client.get(file_url)
        resp.raise_for_status()

    buf = BytesIO(resp.content)
    buf.name = file_name

    msg = await self.bot.send_document(
        chat_id=target,
        document=InputFile(buf, filename=file_name),
    )
    return SentMessage(message_id=str(msg.message_id), platform_type="telegram")

@router.post("/webhook")
async def telegram_webhook(request: Request, background_tasks: BackgroundTasks):
    # 驗證 secret token
    if settings.telegram_webhook_secret:
        secret_header = request.headers.get("X-Telegram-Bot-Api-Secret-Token", "")
        if secret_header != settings.telegram_webhook_secret:
            raise HTTPException(status_code=403, detail="Invalid secret token")

    adapter = _get_adapter()
    body = await request.json()
    update = Update.de_json(body, adapter.bot)

    # 背景處理，不阻塞回應
    background_tasks.add_task(handle_update, update, adapter)
    return {"status": "ok"}

PLATFORM_TYPE = "telegram"

async def _save_message(conn, message_id, bot_user_id, bot_group_id,
                        message_type, content, is_from_bot) -> str:
    row = await conn.fetchrow(
        """
        INSERT INTO bot_messages (
            message_id, bot_user_id, bot_group_id,
            message_type, content, is_from_bot, platform_type
        ) VALUES ($1, $2, $3, $4, $5, $6, $7)
        RETURNING id
        """,
        message_id, bot_user_id, bot_group_id,
        message_type, content, is_from_bot, PLATFORM_TYPE,
    )
    return row["id"]

async def _ensure_bot_user(user, conn) -> str:
    """確保 Telegram 用戶存在於 bot_users，回傳 UUID"""
    platform_user_id = str(user.id)
    display_name = user.full_name

    row = await conn.fetchrow(
        "SELECT id, display_name FROM bot_users "
        "WHERE platform_type = $1 AND platform_user_id = $2",
        PLATFORM_TYPE, platform_user_id,
    )

    if row:
        # display_name 有變化就更新
        if display_name and display_name != row["display_name"]:
            await conn.execute(
                "UPDATE bot_users SET display_name = $1, updated_at = NOW() WHERE id = $2",
                display_name, row["id"],
            )
        return row["id"]

    # 新建用戶
    row = await conn.fetchrow(
        "INSERT INTO bot_users (platform_type, platform_user_id, display_name) "
        "VALUES ($1, $2, $3) RETURNING id",
        PLATFORM_TYPE, platform_user_id, display_name,
    )
    return row["id"]

# 共用 AI 模組
from ..linebot_ai import (
    build_system_prompt,
    get_conversation_context,
    log_linebot_ai_call,
)

# 檢查是否為綁定驗證碼（6 位數字）
if bot_user_id and await is_binding_code_format(text.strip()):
    success, msg = await verify_binding_code(bot_user_id, text.strip())
    await adapter.send_text(chat_id, msg)
    return

await adapter.send_text(
    chat_id,
    "請先在 CTOS 系統綁定您的 Telegram 帳號才能使用此服務。\n\n"
    f"📋 您的 Telegram ID：{chat_id}\n"
    "（設定 Admin Chat ID 時可使用此 ID）",
)

def _should_respond_in_group(message, bot_username):
    """判斷群組訊息是否應該觸發 AI 回覆"""
    # 條件 1：回覆 Bot 的訊息
    if message.reply_to_message and message.reply_to_message.from_user:
        if message.reply_to_message.from_user.is_bot:
            return True

    # 條件 2：@Bot mention
    if message.entities and bot_username:
        for entity in message.entities:
            if entity.type == "mention":
                mention_text = message.text[entity.offset:entity.offset + entity.length]
                if mention_text.lower() == f"@{bot_username.lower()}":
                    return True

    return False

if is_group:
    text = _strip_bot_mention(message.text, adapter.bot_username)
    if not text:
        text = "（用戶呼叫了你，請根據最近的對話歷史回應）"

async def download_telegram_photo(bot, message, message_uuid, chat_id, is_group):
    photo = message.photo[-1]  # 取得最高解析度

    # 透過 Telegram API 下載
    file = await bot.get_file(photo.file_id)
    content = bytes(await file.download_as_bytearray())

    # 生成 NAS 路徑
    nas_path = _generate_telegram_nas_path(
        file_type="image", message_id=message.message_id,
        chat_id=chat_id, is_group=is_group, ext=".jpg",
    )

    # 儲存到 NAS
    success = await save_to_nas(nas_path, content)
    if not success:
        return None

    # 記錄到 bot_files 資料表
    await save_file_record(
        message_uuid=message_uuid,
        file_type="image", file_size=photo.file_size,
        mime_type="image/jpeg", nas_path=nas_path,
    )
    return nas_path

async def _get_reply_context(message, bot=None):
    reply = message.reply_to_message
    if not reply:
        return ""

    # 先查 DB
    reply_msg_id = f"tg_{reply.message_id}"
    async with get_connection() as conn:
        row = await conn.fetchrow(
            "SELECT m.content, m.message_type, f.nas_path, f.file_name "
            "FROM bot_messages m LEFT JOIN bot_files f ON f.message_id = m.id "
            "WHERE m.message_id = $1", reply_msg_id,
        )

    if not row:
        # DB 沒有記錄，直接從 Telegram message 物件取得
        return await _extract_reply_from_message(reply, bot)

    # 圖片：下載到暫存目錄讓 AI 讀取
    if row["message_type"] == "image" and row["nas_path"]:
        temp_path = await ensure_temp_image(reply_msg_id, row["nas_path"])
        if temp_path:
            return f"[回覆圖片: {temp_path}]\n"

    # 文字
    if row["content"]:
        return f"[回覆訊息: {row['content']}]\n"

THROTTLE_INTERVAL = 1.0  # 至少間隔 1 秒

async def _send_or_update_progress():
    nonlocal progress_message_id, last_update_ts
    now = time.time()
    full_text = "🤖 AI 處理中\n\n" + "\n\n".join(t["line"] for t in tool_status_lines)

    if progress_message_id is None:
        sent = await adapter.send_progress(chat_id, full_text)
        progress_message_id = sent.message_id
        last_update_ts = now
    elif now - last_update_ts >= THROTTLE_INTERVAL:
        await adapter.update_progress(chat_id, progress_message_id, full_text)
        last_update_ts = now

# ProgressNotifier 實作
async def send_progress(self, target, text):
    return await self.send_text(target, text)

async def update_progress(self, target, message_id, text):
    await self.edit_message(target, message_id, text)

async def finish_progress(self, target, message_id):
    try:
        await self.delete_message(target, message_id)
    except Exception:
        pass  # 訊息可能已過期

async def run_telegram_polling():
    adapter = TelegramBotAdapter(token=settings.telegram_bot_token)
    await adapter.ensure_bot_info()

    # 建立專用 Bot 實例，read_timeout 必須大於 POLL_TIMEOUT
    bot = Bot(
        token=settings.telegram_bot_token,
        request=HTTPXRequest(read_timeout=POLL_TIMEOUT + 10),
    )

    # 刪除現有 webhook（polling 與 webhook 不能同時使用）
    await bot.delete_webhook()

    offset = None
    retry_delay = 1

    try:
        while True:
            try:
                updates = await bot.get_updates(
                    offset=offset,
                    timeout=POLL_TIMEOUT,  # Long polling: 30 秒
                    allowed_updates=["message"],
                )
                retry_delay = 1  # 成功就重置

                for update in updates:
                    offset = update.update_id + 1
                    asyncio.create_task(_safe_handle_update(update, adapter))

            except asyncio.CancelledError:
                raise
            except Exception:
                await asyncio.sleep(retry_delay)
                retry_delay = min(retry_delay * 2, MAX_RETRY_DELAY)  # 指數退避

    except asyncio.CancelledError:
        logger.info("Telegram polling 已停止")

# 各平台的憑證欄位
PLATFORM_KEYS = {
    "line": ["channel_secret", "channel_access_token"],
    "telegram": ["bot_token", "webhook_secret", "admin_chat_id"],
}

# 需要加密儲存的欄位
ENCRYPTED_KEYS = {"channel_secret", "channel_access_token", "bot_token", "webhook_secret"}

async def get_bot_credentials(platform: str) -> dict[str, str]:
    async with get_connection() as conn:
        rows = await conn.fetch(
            "SELECT key, value FROM bot_settings WHERE platform = $1", platform,
        )
        db_values = {row["key"]: row["value"] for row in rows}

    result = {}
    for key in PLATFORM_KEYS[platform]:
        db_val = db_values.get(key, "")
        if db_val:
            # 資料庫有值，解密
            if key in ENCRYPTED_KEYS and is_encrypted(db_val):
                result[key] = decrypt_credential(db_val)
            else:
                result[key] = db_val
        else:
            # Fallback 到環境變數
            result[key] = _get_env_fallback(platform, key)

    return result