텔레그램 봇 아키텍처 및 생태계 개요

import os
import sys
import logging
from telegram import Update
from telegram.ext import (
    Application,
    CommandHandler,
    MessageHandler,
    ContextTypes,
    filters,
)
 
# 1. 로깅 구성 (DashCloud 실시간 웹 콘솔에 출력됨)
logging.basicConfig(
    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
    level=logging.INFO,
)
logger = logging.getLogger("TelegramBot")
 
# 2. 명령어 핸들러 정의
async def start_command(update: Update, context: ContextTypes.DEFAULT_TYPE):
    user = update.effective_user
    logger.info(f"유저 [{user.id}] {user.first_name}님이 /start를 실행했습니다.")
    await update.message.reply_text(
        f"반갑습니다, {user.first_name}님!\n"
        "DashCloud 24시간 클라우드 런타임에서 안전하게 가동 중입니다. 🚀\n\n"
        "도움말을 보려면 /help 를 입력하세요."
    )
 
async def help_command(update: Update, context: ContextTypes.DEFAULT_TYPE):
    help_text = (
        "📖 *명령어 안내*\n\n"
        "/start - 봇 시작 및 인사말\n"
        "/status - 봇 가동 상태 및 Uptime 확인\n"
        "/help - 이 도움말 보기"
    )
    await update.message.reply_markdown(help_text)
 
async def status_command(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text("🟢 시스템 상태: 정상 가동 중 (24/7 Cloud Running)")
 
# 3. 일반 텍스트 에코 핸들러
async def echo_message(update: Update, context: ContextTypes.DEFAULT_TYPE):
    user_text = update.message.text
    logger.info(f"메시지 수신: {user_text}")
    await update.message.reply_text(f"수신 확인: {user_text}")
 
# 4. 전역 에러 핸들러 (예외 발생 시 봇 다운 방지)
async def error_handler(update: object, context: ContextTypes.DEFAULT_TYPE):
    logger.error("요청 처리 중 예외 발생:", exc_info=context.error)
 
def main():
    token = os.environ.get("TELEGRAM_BOT_TOKEN")
    if not token:
        logger.critical("환경변수 TELEGRAM_BOT_TOKEN이 누락되었습니다!")
        sys.exit(1)
 
    logger.info("텔레그램 봇 인스턴스를 빌드합니다...")
    app = Application.builder().token(token).build()
 
    # 핸들러 등록
    app.add_handler(CommandHandler("start", start_command))
    app.add_handler(CommandHandler("help", help_command))
    app.add_handler(CommandHandler("status", status_command))
    app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo_message))
 
    # 에러 핸들러 바인딩
    app.add_error_handler(error_handler)
 
    logger.info("24/7 무중단 롱폴링 루프를 가동합니다...")
    # drop_pending_updates=True: 재시작 시 누적된 이전 구 메시지 중복 처리 방지
    app.run_polling(drop_pending_updates=True)
 
if __name__ == "__main__":
    main()