مدیریت وضعیت‌ها (States) در Telebot: ساخت ربات‌های چندمرحله‌ای

در دنیای تعاملی ربات‌های تلگرام، توانایی یک ربات برای به خاطر سپردن “کجای یک مکالمه قرار دارد” یا “چه اطلاعاتی را از کاربر درخواست کرده است”، از ویژگی‌های کلیدی است که آن را از یک ابزار ساده به یک دستیار هوشمند تبدیل می‌کند. این قابلیت که با عنوان “مدیریت وضعیت‌ها” یا State Management شناخته می‌شود، امکان ساخت ربات‌های پیچیده، تعاملی و چندمرحله‌ای را فراهم می‌آورد. Telebot، یکی از محبوب‌ترین و قدرتمندترین کتابخانه‌های پایتون برای توسعه ربات‌های تلگرام، ابزارهایی را برای مدیریت وضعیت‌ها ارائه می‌دهد که به توسعه‌دهندگان کمک می‌کند تا تجربه کاربری روان‌تر و منطقی‌تری را ایجاد کنند.

این پست جامع، به بررسی عمیق و تخصصی مفهوم مدیریت وضعیت‌ها در Telebot می‌پردازد. ما از مفاهیم اولیه و چرایی اهمیت این موضوع شروع کرده، سپس به سراغ روش‌های پیاده‌سازی مختلف – از رویکردهای ساده تا استفاده از Finite State Machine (FSM) قدرتمند Telebot – خواهیم رفت. همچنین، به چالش‌های ذخیره‌سازی پایدار وضعیت‌ها و بهترین روش‌ها برای طراحی ربات‌های وضعیت‌مند مقیاس‌پذیر و قابل اعتماد خواهیم پرداخت. هدف نهایی این راهنما، توانمندسازی شما برای ساخت ربات‌هایی است که فراتر از پاسخگویی به دستورات ساده، قادر به هدایت کاربران از طریق فرآیندهای پیچیده و تعاملی باشند.

مقدمه‌ای بر مدیریت وضعیت‌ها در ربات‌های تلگرام و Telebot

پروتکل‌های ارتباطی وب، از جمله API تلگرام، ذاتاً بی‌وضعیت (stateless) هستند. این بدان معناست که هر درخواست (مانند ارسال یک پیام توسط کاربر) مستقل از درخواست‌های قبلی یا بعدی پردازش می‌شود. سرور (در اینجا، ربات شما) هیچ اطلاعاتی از تعاملات گذشته کاربر را به طور خودکار به خاطر نمی‌سپارد. در حالی که این بی‌وضعیت بودن مزایایی از نظر مقیاس‌پذیری و سادگی دارد، چالش‌هایی را نیز برای ساخت برنامه‌های کاربردی تعاملی و چندمرحله‌ای ایجاد می‌کند.

تصور کنید یک ربات سفارش غذا می‌سازید. کاربر ابتدا “شروع سفارش” را انتخاب می‌کند، سپس ربات از او می‌پرسد که چه نوع غذایی می‌خواهد، پس از آن نام غذا را می‌پرسد، تعداد را می‌پرسد و در نهایت آدرس تحویل را. در هر مرحله، ربات نیاز دارد بداند که کاربر در کجای فرآیند سفارش‌دهی قرار دارد تا بتواند سوال مناسب بعدی را بپرسد و ورودی‌های او را به درستی تفسیر کند. اینجاست که مدیریت وضعیت وارد می‌شود.

وضعیت (State) در این زمینه، به معنی مرحله یا فازی است که یک کاربر در یک فرآیند تعاملی خاص با ربات شما قرار دارد. با مدیریت وضعیت، ربات می‌تواند:

• تعاملات چندمرحله‌ای مانند فرم‌ها، نظرسنجی‌ها یا بازی‌ها را هندل کند.
• ورودی‌های کاربر را بر اساس انتظار فعلی خود، تفسیر کند.
• تجربه کاربری منسجم و بدون سردرگمی را ارائه دهد.

Telebot، به عنوان یک کتابخانه سطح بالا برای پایتون، توسعه ربات‌ها را آسان می‌کند. با این حال، به صورت پیش‌فرض، Telebot نیز همانند API تلگرام، بی‌وضعیت عمل می‌کند. خوشبختانه، Telebot مکانیزم‌های قدرتمندی را برای افزودن قابلیت مدیریت وضعیت به ربات‌ها ارائه می‌دهد که محور اصلی این مقاله را تشکیل می‌دهد.

چرا مدیریت وضعیت برای ربات‌های Telebot حیاتی است؟

همانطور که اشاره شد، بدون مدیریت وضعیت، ربات‌ها تنها می‌توانند به دستورات اتمیک و مستقل پاسخ دهند. هر دستور کاربر به عنوان یک ورودی کاملاً جدید و بی‌ارتباط با ورودی‌های قبلی در نظر گرفته می‌شود. این رویکرد برای ربات‌های بسیار ساده که فقط به چند دستور “/start” یا “/help” پاسخ می‌دهند، کفایت می‌کند. اما با افزایش پیچیدگی وظایف ربات، مدیریت وضعیت به یک ضرورت تبدیل می‌شود.

دلایل اصلی که مدیریت وضعیت را برای ربات‌های Telebot حیاتی می‌کند، عبارتند از:

1. تجربه کاربری بهبودیافته: کاربران انتظار دارند که ربات‌ها هوشمند باشند و زمینه مکالمه را درک کنند. یک ربات بدون وضعیت، ممکن است در میانه یک فرآیند، با یک دستور بی‌ربط، روند را قطع کند و کاربر را گیج سازد. مدیریت وضعیت امکان هدایت کاربر از طریق یک مسیر منطقی و گام به گام را فراهم می‌کند که منجر به رضایت بیشتر کاربر می‌شود.

2. ایجاد فرم‌های تعاملی و جمع‌آوری داده: بسیاری از ربات‌ها نیاز به جمع‌آوری اطلاعات چندگانه از کاربر دارند، مانند ثبت‌نام، ایجاد پروفایل، سفارش محصول یا پاسخ به سوالات نظرسنجی. مدیریت وضعیت به ربات اجازه می‌دهد تا هر قطعه اطلاعات را به صورت جداگانه در یک مرحله خاص از فرآیند درخواست کرده و ذخیره کند.

3. پیاده‌سازی گردش‌کارهای (Workflows) پیچیده: ربات‌هایی که کارهایی مانند رزرو وقت، مدیریت پروژه‌ها یا حتی بازی‌های تعاملی را انجام می‌دهند، نیازمند یک سلسله مراتب از مراحل هستند. در هر مرحله، ربات ممکن است گزینه‌های متفاوتی را ارائه دهد و به ورودی‌های خاصی انتظار داشته باشد. مدیریت وضعیت، ابزار لازم برای طراحی و اجرای این گردش‌کارهای پیچیده را فراهم می‌کند.

4. تفسیر صحیح ورودی‌های کاربر: گاهی اوقات، یک کلمه یا عبارت می‌تواند در زمینه‌های مختلف، معانی متفاوتی داشته باشد. به عنوان مثال، در یک مرحله ممکن است “بله” به معنی تایید سفارش باشد و در مرحله‌ای دیگر به معنی ادامه دادن به بخش بعدی فرم. وضعیت فعلی کاربر، به ربات کمک می‌کند تا ورودی‌های او را به درستی تفسیر کند.

5. افزایش قابلیت اطمینان ربات: با تعریف وضعیت‌های مشخص، می‌توانید منطق ربات را به بخش‌های کوچک‌تر و قابل مدیریت تقسیم کنید. این کار به کاهش پیچیدگی کد، بهبود نگهداری و آسان‌تر شدن دیباگ کردن کمک می‌کند. همچنین، می‌توانید حالت‌های خطا و لغو را به صورت کنترل‌شده‌تری مدیریت کنید.

بدون مدیریت وضعیت، ساخت ربات‌هایی که بتوانند با پیچیدگی‌های تعاملات انسانی مقابله کنند، عملاً غیرممکن است. این قابلیت، دروازه‌ای برای ساخت ربات‌های واقعاً هوشمند، کارآمد و مورد علاقه کاربران است.

روش‌های ابتدایی (و محدود) مدیریت وضعیت در Telebot

قبل از اینکه به راه‌حل‌های پیشرفته Telebot برای مدیریت وضعیت بپردازیم، خوب است نگاهی به روش‌های ابتدایی (و غالباً نامناسب) بیاندازیم که ممکن است توسعه‌دهندگان تازه‌کار سعی در استفاده از آن‌ها داشته باشند. درک محدودیت‌های این روش‌ها، اهمیت استفاده از راه‌حل‌های استاندارد را برجسته‌تر می‌کند.

1. استفاده از متغیرهای سراسری (Global Variables) یا دیکشنری‌های ساده در حافظه

ساده‌ترین ایده برای ذخیره وضعیت یک کاربر، استفاده از یک متغیر سراسری یا یک دیکشنری در حافظه برنامه است که User ID را به وضعیت فعلی او مپ می‌کند. برای مثال:

user_states = {} # {chat_id: current_state}
user_data = {} # {chat_id: {key: value}}

@bot.message_handler(commands=['start'])
def handle_start(message):
    user_states[message.chat.id] = 'awaiting_name'
    user_data[message.chat.id] = {}
    bot.send_message(message.chat.id, "لطفاً نام خود را وارد کنید:")

@bot.message_handler(func=lambda message: user_states.get(message.chat.id) == 'awaiting_name')
def handle_name(message):
    user_data[message.chat.id]['name'] = message.text
    user_states[message.chat.id] = 'awaiting_age'
    bot.send_message(message.chat.id, "سن خود را وارد کنید:")

# ... و به همین ترتیب برای وضعیت‌های بعدی

محدودیت‌ها:

• عدم پایداری (Non-Persistent): با هر بار ری‌استارت شدن ربات، تمام اطلاعات وضعیت و داده‌های کاربران از بین می‌رود. این برای ربات‌های تولیدی غیرقابل قبول است.
• مشکلات همروندی (Concurrency Issues): در محیط‌های چندرشته‌ای یا چندپردازشی (که ربات‌های واقعی معمولاً در آن‌ها اجرا می‌شوند)، دسترسی همزمان چندین thread به متغیرهای سراسری می‌تواند منجر به Race Condition و داده‌های ناسازگار شود.
• مشکلات مقیاس‌پذیری: ذخیره تمام داده‌ها در حافظه اصلی یک فرآیند واحد، با افزایش تعداد کاربران به سرعت حافظه را اشغال کرده و عملکرد ربات را کاهش می‌دهد.
• پیچیدگی کد: مدیریت دستی وضعیت‌ها با `if/else`های تو در تو یا `lambda`های پیچیده در `message_handler`ها، به سرعت کد را غیرقابل خواندن و نگهداری می‌کند.

2. استفاده از دکوراتورهای شرطی با `message.text` یا `message.chat.id`

گاهی اوقات توسعه‌دهندگان سعی می‌کنند با استفاده از دکوراتورهای `message_handler` و بررسی محتوای پیام یا ID چت، نوعی از مدیریت وضعیت را شبیه‌سازی کنند:

@bot.message_handler(func=lambda message: message.text == "ثبت‌نام")
def start_registration(message):
    # شروع فرآیند ثبت‌نام
    pass

@bot.message_handler(func=lambda message: message.text.isdigit())
def handle_number_input(message):
    # آیا این شماره سن است؟ یا مقدار سفارش؟ یا یک کد محصول؟
    # ربات در اینجا نمی‌تواند تفاوت را تشخیص دهد بدون داشتن وضعیت
    pass

محدودیت‌ها:

• عدم قطعیت (Ambiguity): یک ورودی واحد (مانند یک عدد) می‌تواند در زمینه‌های مختلف معنای متفاوتی داشته باشد. بدون وضعیت، ربات نمی‌تواند بفهمد کاربر به کدام سوال پاسخ می‌دهد.
• عدم انعطاف‌پذیری: این روش به شدت به محتوای دقیق پیام کاربر وابسته است و هرگونه تغییر در عبارت‌بندی می‌تواند Handler را از کار بیاندازد.
• پیچیدگی رشد: با افزایش تعداد حالات و فرآیندها، `func`های `lambda` بسیار پیچیده و غیرقابل مدیریت می‌شوند.

این روش‌ها برای ربات‌های کوچک و آزمایشی ممکن است کار کنند، اما برای ربات‌هایی که قرار است در محیط تولیدی استفاده شوند و با تعداد زیادی کاربر و تعاملات پیچیده سر و کار داشته باشند، به سرعت شکست می‌خورند. اینجاست که نیاز به یک رویکرد ساختارمندتر و قدرتمندتر مانند Finite State Machine (FSM) Telebot احساس می‌شود.

رویکرد Finite State Machine (FSM) در Telebot: قلب مدیریت وضعیت

Finite State Machine (FSM) یا ماشین حالت متناهی، یک الگوی طراحی قدرتمند در علوم کامپیوتر است که برای مدل‌سازی سیستم‌هایی با رفتارهای وابسته به وضعیت استفاده می‌شود. در یک FSM، سیستم در هر لحظه در یکی از تعداد محدودی از “حالت‌ها” (States) قرار دارد. رویدادها (مانند پیام‌های کاربر) باعث “انتقال” (Transition) سیستم از یک حالت به حالت دیگر می‌شوند و هر حالت می‌تواند منطق خاص خود را برای پردازش ورودی‌ها داشته باشد.

Telebot به طور بومی از یک پیاده‌سازی FSM از طریق ماژول `telebot.handler_backends` پشتیبانی می‌کند. این پیاده‌سازی به توسعه‌دهندگان اجازه می‌دهد تا وضعیت‌های مختلف را تعریف کرده و Handlerهای پیام را به گونه‌ای متصل کنند که فقط زمانی فعال شوند که کاربر در یک وضعیت خاص قرار دارد. این رویکرد، راه‌حلی پایدار، مقیاس‌پذیر و قابل نگهداری برای مدیریت وضعیت در ربات‌های تلگرام ارائه می‌دهد.

مفاهیم اصلی FSM در Telebot:

1. `StateContext` (یا `FSMContext`): این کلاس مسئول نگهداری و مدیریت وضعیت فعلی و داده‌های مرتبط با هر کاربر است. Telebot به صورت پیش‌فرض از `MemoryStorage` برای ذخیره وضعیت‌ها در حافظه استفاده می‌کند، اما می‌توان آن را با راه‌حل‌های ذخیره‌سازی پایدارتر (مانند دیتابیس‌ها) جایگزین کرد.

2. `StatesGroup` و تعریف وضعیت‌ها: برای تعریف مجموعه‌ای از وضعیت‌ها که یک فرآیند خاص را مدل می‌کنند، از کلاس `StatesGroup` استفاده می‌شود. هر وضعیت در این گروه به صورت یک شیء `State` تعریف می‌شود.

3. `bot.set_state(user_id, chat_id, state)`: این متد برای انتقال یک کاربر به وضعیت جدید استفاده می‌شود.

4. `bot.delete_state(user_id, chat_id)`: این متد برای پاک کردن وضعیت فعلی کاربر و بازگرداندن او به وضعیت پیش‌فرض (None) استفاده می‌شود.

5. دکوراتور `message_handler(state=…)` و `callback_query_handler(state=…)`: این دکوراتورها امکان اتصال یک Handler به یک یا چند وضعیت خاص را فراهم می‌کنند. یک Handler فقط زمانی فعال می‌شود که پیام یا Callback Query از کاربری با وضعیت منطبق دریافت شود.

6. دسترسی به داده‌های وضعیت: داخل Handlerهای وضعیت‌مند، می‌توانید به شیء `StateContext` دسترسی پیدا کنید و از طریق آن، داده‌های موقت مربوط به کاربر را که در مراحل قبلی جمع‌آوری شده‌اند، ذخیره و بازیابی کنید.

نحوه عملکرد FSM در Telebot:

هنگامی که یک پیام از کاربر دریافت می‌شود:

1. Telebot ابتدا وضعیت فعلی آن کاربر را از `StateContext` (یا همان Storage) بازیابی می‌کند.
2. سپس، Telebot لیستی از تمامی Handlerهای ثبت شده را بررسی می‌کند.
3. فقط Handlerهایی که `state` آن‌ها با وضعیت فعلی کاربر مطابقت دارد (یا `state=None` برای Handlerهای عمومی) و شرط `func` آن‌ها (اگر وجود داشته باشد) نیز برقرار است، کاندید فعال شدن می‌شوند.
4. اولین Handler منطبق اجرا می‌شود.
5. درون Handler، می‌توانید با استفاده از `bot.set_state` وضعیت کاربر را تغییر دهید و با `state.update_data()` یا `state.get_data()` داده‌های مربوط به آن فرآیند را ذخیره یا بازیابی کنید.

این مکانیزم، یک چارچوب قدرتمند و سازمان‌یافته برای مدیریت جریان مکالمات در ربات‌های Telebot ارائه می‌دهد و از پیچیدگی‌ها و مشکلات روش‌های ابتدایی جلوگیری می‌کند.

پیاده‌سازی FSM با Telebot: گام به گام یک مثال کاربردی

برای درک بهتر نحوه کار FSM در Telebot، یک مثال عملی را پیاده‌سازی می‌کنیم: یک ربات ثبت‌نام ساده که نام، سن و شهر کاربر را جمع‌آوری می‌کند.

import telebot
from telebot import types
from telebot.handler_backends import State, StatesGroup # مهم: وارد کردن State و StatesGroup

# توکن ربات خود را اینجا وارد کنید
API_TOKEN = 'YOUR_BOT_TOKEN'
bot = telebot.TeleBot(API_TOKEN)

# 1. تعریف StatesGroup برای مدیریت وضعیت‌ها
class RegistrationStates(StatesGroup):
    name = State()       # وضعیت انتظار برای نام
    age = State()        # وضعیت انتظار برای سن
    city = State()       # وضعیت انتظار برای شهر
    confirmation = State() # وضعیت تایید نهایی

# 2. هندلر دستور /start: شروع فرآیند ثبت‌نام
@bot.message_handler(commands=['start'])
def start_registration(message):
    bot.send_message(message.chat.id, "سلام! برای ثبت‌نام لطفاً نام خود را وارد کنید.")
    bot.set_state(message.from_user.id, RegistrationStates.name, message.chat.id) # انتقال به وضعیت name

# 3. هندلر برای وضعیت 'name': دریافت نام
@bot.message_handler(state=RegistrationStates.name)
def get_name(message):
    with bot.retrieve_data(message.from_user.id, message.chat.id) as data:
        data['name'] = message.text # ذخیره نام کاربر
    bot.send_message(message.chat.id, f"خوش آمدید، {message.text}! لطفاً سن خود را وارد کنید.")
    bot.set_state(message.from_user.id, RegistrationStates.age, message.chat.id) # انتقال به وضعیت age

# 4. هندلر برای وضعیت 'age': دریافت سن
@bot.message_handler(state=RegistrationStates.age)
def get_age(message):
    if not message.text.isdigit():
        bot.send_message(message.chat.id, "لطفاً سن را به صورت عددی وارد کنید.")
        return # باقی ماندن در وضعیت age

    age = int(message.text)
    if not (0 < age < 120):
        bot.send_message(message.chat.id, "سن وارد شده معتبر نیست. لطفاً یک عدد بین 1 تا 119 وارد کنید.")
        return # باقی ماندن در وضعیت age

    with bot.retrieve_data(message.from_user.id, message.chat.id) as data:
        data['age'] = age # ذخیره سن کاربر
    bot.send_message(message.chat.id, "لطفاً شهر محل سکونت خود را وارد کنید.")
    bot.set_state(message.from_user.id, RegistrationStates.city, message.chat.id) # انتقال به وضعیت city

# 5. هندلر برای وضعیت 'city': دریافت شهر
@bot.message_handler(state=RegistrationStates.city)
def get_city(message):
    with bot.retrieve_data(message.from_user.id, message.chat.id) as data:
        data['city'] = message.text # ذخیره شهر کاربر
    
    # نمایش خلاصه اطلاعات برای تایید
    markup = types.InlineKeyboardMarkup()
    markup.add(types.InlineKeyboardButton("تایید", callback_data="confirm_reg"))
    markup.add(types.InlineKeyboardButton("لغو", callback_data="cancel_reg"))
    
    bot.send_message(message.chat.id, 
                     f"اطلاعات شما:\nنام: {data['name']}\nسن: {data['age']}\nشهر: {data['city']}\n\nآیا تایید می‌کنید؟",
                     reply_markup=markup)
    bot.set_state(message.from_user.id, RegistrationStates.confirmation, message.chat.id) # انتقال به وضعیت confirmation

# 6. هندلر برای وضعیت 'confirmation' و callback_query
@bot.callback_query_handler(state=RegistrationStates.confirmation, func=lambda call: True)
def confirm_registration(call):
    if call.data == "confirm_reg":
        with bot.retrieve_data(call.from_user.id, call.message.chat.id) as data:
            # اینجا می‌توانید اطلاعات را در دیتابیس ذخیره کنید
            bot.send_message(call.message.chat.id, 
                             f"ثبت‌نام شما با موفقیت انجام شد:\nنام: {data['name']}, سن: {data['age']}, شهر: {data['city']}")
        bot.delete_state(call.from_user.id, call.message.chat.id) # پایان فرآیند و پاک کردن وضعیت
        bot.send_message(call.message.chat.id, "با تشکر از شما!")
    elif call.data == "cancel_reg":
        bot.delete_state(call.from_user.id, call.message.chat.id) # لغو و پاک کردن وضعیت
        bot.send_message(call.message.chat.id, "ثبت‌نام لغو شد.")
    bot.edit_message_reply_markup(call.message.chat.id, call.message.message_id, reply_markup=None) # حذف کیبورد اینلاین

# 7. هندلر عمومی برای لغو فرآیند در هر وضعیت
@bot.message_handler(commands=['cancel'], state='*') # '*' به معنی هر وضعیتی
def cancel_process(message):
    bot.delete_state(message.from_user.id, message.chat.id)
    bot.send_message(message.chat.id, "فرآیند لغو شد. می‌توانید از ابتدا شروع کنید با /start.")

# 8. هندلر برای پیام‌های نامربوط در وضعیت‌های خاص
@bot.message_handler(func=lambda message: True, state=RegistrationStates.name)
@bot.message_handler(func=lambda message: True, state=RegistrationStates.age)
@bot.message_handler(func=lambda message: True, state=RegistrationStates.city)
@bot.message_handler(func=lambda message: True, state=RegistrationStates.confirmation)
def handle_invalid_input(message):
    bot.send_message(message.chat.id, "ورودی نامعتبر است. لطفاً طبق دستورالعمل عمل کنید یا با /cancel فرآیند را لغو کنید.")


# شروع ربات
if __name__ == '__main__':
    print("ربات در حال اجرا است...")
    bot.infinity_polling(skip_pending=True)

تحلیل کد و مفاهیم کلیدی:

ساختاردهی وضعیت‌ها با StatesGroup

ما با تعریف یک کلاس `RegistrationStates` که از `StatesGroup` ارث می‌برد، وضعیت‌های مختلف فرآیند ثبت‌نام را مشخص کردیم. هر متغیر درون این کلاس (`name`, `age`, `city`, `confirmation`) یک شیء `State` را نشان می‌دهد. این رویکرد کد را سازمان‌یافته‌تر و خواناتر می‌کند و از خطاهای تایپی جلوگیری می‌کند.

انتقال بین وضعیت‌ها و جمع‌آوری داده‌ها

• `@bot.message_handler(commands=['start'])`: این Handler بدون وضعیت (یا با وضعیت پیش‌فرض `None`) کار می‌کند. پس از دریافت دستور `/start`، پیام خوش‌آمدگویی را ارسال کرده و بلافاصله با `bot.set_state` کاربر را به وضعیت `RegistrationStates.name` منتقل می‌کند.
• `@bot.message_handler(state=RegistrationStates.name)`: این Handler تنها زمانی فعال می‌شود که کاربر در وضعیت `name` باشد. پیام کاربر (که انتظار می‌رود نام او باشد) دریافت و با `bot.retrieve_data()` و `data['name'] = message.text` در Context ذخیره می‌شود. سپس کاربر به وضعیت `RegistrationStates.age` منتقل می‌شود.
• `bot.retrieve_data(user_id, chat_id)`: این تابع یک context manager را برمی‌گرداند که به شما امکان دسترسی به دیکشنری داده‌های کاربر را می‌دهد. هر داده‌ای که در این دیکشنری ذخیره کنید، تا زمانی که وضعیت کاربر پاک نشود، باقی می‌ماند.

رسیدگی به لغو و خطاهای ورودی

• اعتبارسنجی ورودی: در Handler مربوط به دریافت سن (`get_age`)، ما بررسی می‌کنیم که آیا ورودی عددی است و در محدوده معتبری قرار دارد یا خیر. اگر ورودی نامعتبر باشد، یک پیام خطا ارسال کرده و `return` می‌کنیم، که باعث می‌شود کاربر در همان وضعیت `RegistrationStates.age` باقی بماند تا ورودی صحیح را ارائه دهد.
• هندلر `/cancel`: یک Handler عمومی با `state='*'` (به معنی هر وضعیتی) برای دستور `/cancel` تعریف شده است. این Handler به کاربر اجازه می‌دهد در هر مرحله‌ای فرآیند را لغو کند. با فراخوانی `bot.delete_state()`, وضعیت کاربر پاک شده و او به حالت پیش‌فرض برمی‌گردد.
• هندلر ورودی نامعتبر: Handler نهایی `handle_invalid_input` با `func=lambda message: True` و تعیین وضعیت‌های خاص، تمامی پیام‌هایی را که در آن وضعیت‌ها دریافت می‌شوند اما توسط Handlerهای اختصاصی آن وضعیت (مانند `get_name`، `get_age` و...) گرفته نمی‌شوند، مدیریت می‌کند. این تضمین می‌کند که کاربران در صورت ارسال پیام‌های نامربوط، راهنمایی دریافت می‌کنند.
• کیبوردهای اینلاین (Inline Keyboards): در مرحله `confirmation`، از کیبورد اینلاین برای تایید یا لغو نهایی استفاده شده است. `callback_query_handler` نیز همانند `message_handler` می‌تواند با `state` کار کند تا فقط در وضعیت مربوطه فعال شود. پس از اتمام فرآیند، `edit_message_reply_markup` کیبورد را حذف می‌کند تا از تعاملات ناخواسته جلوگیری شود.

این مثال، یک دیدگاه جامع از قدرت FSM در Telebot و چگونگی سازماندهی منطق ربات برای تعاملات چندمرحله‌ای را ارائه می‌دهد. مهم است که به خاطر داشته باشید Telebot به صورت پیش‌فرض از `MemoryStorage` برای ذخیره این وضعیت‌ها و داده‌ها استفاده می‌کند، که به این معنی است که با هر بار ری‌استارت شدن ربات، تمامی این اطلاعات از بین می‌روند. برای ربات‌های تولیدی، نیاز به یک راه‌حل ذخیره‌سازی پایدار است.

ذخیره‌سازی وضعیت‌ها به صورت پایدار (Persistent States)

همانطور که در مثال قبل دیدید، `bot.retrieve_data()` و `bot.set_state()` اطلاعات وضعیت و داده‌های مربوط به کاربر را در حافظه ربات (با استفاده از `MemoryStorage`) ذخیره می‌کنند. این روش برای توسعه و تست‌های اولیه مناسب است، اما برای ربات‌های تولیدی با تعداد کاربران زیاد و نیاز به پایداری داده‌ها، ناکافی است. با هر بار ری‌استارت شدن ربات یا خرابی سرور، تمام اطلاعات وضعیت کاربران از بین می‌رود و آن‌ها باید فرآیندهای خود را از ابتدا آغاز کنند، که تجربه کاربری بسیار بدی را ایجاد می‌کند.

برای حل این مشکل، نیاز به پیاده‌سازی یک ذخیره‌ساز پایدار (Persistent Storage) برای وضعیت‌ها و داده‌های FSM داریم. Telebot این امکان را فراهم می‌کند تا شما یک کلاس ذخیره‌سازی سفارشی (Custom Storage) را به جای `MemoryStorage` پیش‌فرض استفاده کنید.

استفاده از MemoryStorage (پیش‌فرض) و محدودیت‌های آن

وقتی شما یک `TeleBot` instance را بدون هیچ پارامتر `state_storage` ایجاد می‌کنید، Telebot به صورت خودکار `MemoryStorage` را به عنوان ذخیره‌ساز وضعیت تنظیم می‌کند:

import telebot
# bot = telebot.TeleBot(API_TOKEN) # این خط به صورت پیش‌فرض از MemoryStorage استفاده می‌کند

محدودیت‌های MemoryStorage:

• عدم پایداری: داده‌ها فقط در حافظه RAM برنامه نگهداری می‌شوند. با توقف یا ری‌استارت شدن برنامه، همه چیز از دست می‌رود.
• عدم مقیاس‌پذیری: برای ربات‌های با تعداد کاربران بسیار زیاد، ذخیره همه چیز در حافظه می‌تواند منجر به مصرف بالای RAM و کاهش عملکرد شود.
• عدم امکان اشتراک‌گذاری: اگر چندین instance از ربات خود را برای load balancing اجرا کنید، هر instance وضعیت‌های خود را به صورت جداگانه مدیریت می‌کند و نمی‌توانند وضعیت‌های یک کاربر را با یکدیگر به اشتراک بگذارند.

پیاده‌سازی ذخیره‌ساز سفارشی (Custom Storage)

برای پیاده‌سازی ذخیره‌ساز سفارشی، باید کلاسی بنویسید که از `telebot.handler_backends.StateStorageBase` ارث‌بری کند و متدهای ضروری آن را پیاده‌سازی کند: `get_state`, `set_state`, `delete_state`, `get_data`, `set_data`, `del_data`. سپس این کلاس را هنگام ایجاد `TeleBot` به عنوان پارامتر `state_storage` ارسال کنید.

متدهای اصلی که باید پیاده‌سازی شوند:

• async get_state(chat_id: int, user_id: int) -> Optional[State]
• async set_state(chat_id: int, user_id: int, state: Optional[State])
• async delete_state(chat_id: int, user_id: int)
• async get_data(chat_id: int, user_id: int) -> Dict
• async set_data(chat_id: int, user_id: int, data: Dict)
• async del_data(chat_id: int, user_id: int)

توجه داشته باشید که این متدها باید به صورت `async` (آسنکرون) پیاده‌سازی شوند، زیرا Telebot برای کار با ذخیره‌سازهای پایدار، از Coroutineها استفاده می‌کند. این به ربات شما اجازه می‌دهد تا در حین انتظار برای پاسخ از دیتابیس، وظایف دیگری را انجام دهد.

انتخاب پایگاه داده مناسب: SQLite، Redis یا PostgreSQL؟

انتخاب پایگاه داده بستگی به نیازهای پروژه شما دارد:

SQLite:

• مزایا: سبک، بدون نیاز به سرور جداگانه، فایل‌محور، بسیار ساده برای راه‌اندازی و استفاده.
• معایب: کمتر مناسب برای محیط‌های با همروندی بالا (چندین ربات instance)، عملکرد محدود در مقایسه با دیتابیس‌های سرور-کلاینت، ممکن است در طول زمان با حجم زیاد داده‌ها کند شود.
• کاربرد: ربات‌های کوچک تا متوسط، ربات‌هایی که روی یک سرور واحد اجرا می‌شوند و نیاز به پایداری ساده دارند.
• پیاده‌سازی: نیاز به استفاده از ماژول `sqlite3` پایتون و ایجاد یک جدول برای ذخیره وضعیت‌ها و داده‌ها (معمولاً به صورت JSON یا Serialized).

# مثالی از یک ذخیره‌ساز SQLite (فقط منطق اصلی، بدون جزئیات کامل مدیریت Connection)
import sqlite3
import json
from telebot.handler_backends import StateStorageBase, State
from typing import Optional, Dict

class SQLiteStorage(StateStorageBase):
    def __init__(self, db_path='bot_states.db'):
        self.db_path = db_path
        self._create_table()

    def _get_connection(self):
        return sqlite3.connect(self.db_path)

    def _create_table(self):
        conn = self._get_connection()
        cursor = conn.cursor()
        cursor.execute('''
            CREATE TABLE IF NOT EXISTS user_states (
                chat_id INTEGER NOT NULL,
                user_id INTEGER NOT NULL,
                state TEXT,
                data TEXT,
                PRIMARY KEY (chat_id, user_id)
            )
        ''')
        conn.commit()
        conn.close()

    async def get_state(self, chat_id: int, user_id: int) -> Optional[State]:
        conn = self._get_connection()
        cursor = conn.cursor()
        cursor.execute('SELECT state FROM user_states WHERE chat_id = ? AND user_id = ?', (chat_id, user_id))
        result = cursor.fetchone()
        conn.close()
        return State(result[0]) if result and result[0] else None

    async def set_state(self, chat_id: int, user_id: int, state: Optional[State]):
        conn = self._get_connection()
        cursor = conn.cursor()
        state_str = state.full_state if state else None
        cursor.execute('''
            INSERT OR REPLACE INTO user_states (chat_id, user_id, state)
            VALUES (?, ?, ?)
        ''', (chat_id, user_id, state_str))
        conn.commit()
        conn.close()

    async def delete_state(self, chat_id: int, user_id: int):
        conn = self._get_connection()
        cursor = conn.cursor()
        cursor.execute('UPDATE user_states SET state = NULL WHERE chat_id = ? AND user_id = ?', (chat_id, user_id))
        conn.commit()
        conn.close()

    async def get_data(self, chat_id: int, user_id: int) -> Dict:
        conn = self._get_connection()
        cursor = conn.cursor()
        cursor.execute('SELECT data FROM user_states WHERE chat_id = ? AND user_id = ?', (chat_id, user_id))
        result = cursor.fetchone()
        conn.close()
        return json.loads(result[0]) if result and result[0] else {}

    async def set_data(self, chat_id: int, user_id: int, data: Dict):
        conn = self._get_connection()
        cursor = conn.cursor()
        data_str = json.dumps(data)
        cursor.execute('''
            INSERT OR REPLACE INTO user_states (chat_id, user_id, data)
            VALUES (?, ?, ?)
        ''', (chat_id, user_id, data_str))
        conn.commit()
        conn.close()

    async def del_data(self, chat_id: int, user_id: int):
        conn = self._get_connection()
        cursor = conn.cursor()
        cursor.execute('UPDATE user_states SET data = NULL WHERE chat_id = ? AND user_id = ?', (chat_id, user_id))
        conn.commit()
        conn.close()

# نحوه استفاده:
# storage = SQLiteStorage('my_bot_states.db')
# bot = telebot.TeleBot(API_TOKEN, state_storage=storage)

Redis:

• مزایا: بسیار سریع، In-memory (اما با قابلیت پایداری روی دیسک)، ایده‌آل برای ذخیره‌سازی موقت و وضعیت‌ها، پشتیبانی عالی از همروندی و مقیاس‌پذیری (از طریق کلاستر).
• معایب: نیاز به نصب و راه‌اندازی سرور Redis، پیچیدگی بیشتر در مدیریت نسبت به SQLite.
• کاربرد: ربات‌های با حجم ترافیک بالا، ربات‌های توزیع شده (چندین instance)، caching داده‌ها.
• پیاده‌سازی: استفاده از کتابخانه `redis-py` و ذخیره وضعیت‌ها و داده‌ها به صورت Key-Value (مانند 'state:{chat_id}:{user_id}' و 'data:{chat_id}:{user_id}').

Telebot یک ماژول داخلی برای Redis Storage دارد: `telebot.storage.RedisStorage`. می‌توانید به سادگی از آن استفاده کنید:

from telebot import TeleBot
from telebot.storage import RedisStorage
import redis

# اتصال به Redis
# اگر Redis روی لوکال هاست و پورت پیش‌فرض است، نیازی به پارامترهای بیشتر نیست
redis_instance = redis.Redis(host='localhost', port=6379, db=0) 
storage = RedisStorage(redis_instance)

# نحوه استفاده:
# bot = TeleBot(API_TOKEN, state_storage=storage)

PostgreSQL/MySQL:

• مزایا: قدرتمند، ACID-compliant، مناسب برای داده‌های رابطه‌ای پیچیده، پشتیبانی عالی از تراکنش‌ها، امنیت بالا، قابلیت مقیاس‌پذیری و انعطاف‌پذیری زیاد.
• معایب: پیچیدگی بیشتر در راه‌اندازی و مدیریت، مصرف منابع بالاتر نسبت به SQLite و Redis (برای وضعیت‌های ساده).
• کاربرد: ربات‌های پیچیده که نیاز به ذخیره سازی داده‌های ساختاریافته در کنار وضعیت‌ها دارند، ربات‌های سازمانی، پروژه‌های بزرگ.
• پیاده‌سازی: استفاده از ORMهایی مانند SQLAlchemy یا کتابخانه‌های دیتابیس مانند `psycopg2` (برای PostgreSQL) یا `mysql-connector-python` (برای MySQL) به همراه یک pooling connection manager.

برای دیتابیس‌های رابطه‌ای مثل PostgreSQL، می‌توانید یک `SQLAlchemyStorage` سفارشی بنویسید که همانند `SQLiteStorage` از یک جدول برای نگهداری `chat_id`, `user_id`, `state`, و `data` استفاده کند.

انتخاب ذخیره‌ساز مناسب گام مهمی در ساخت ربات‌های پایدار و قابل اعتماد است. برای اکثر ربات‌های متوسط، `RedisStorage` Telebot یک انتخاب عالی است، زیرا تعادل خوبی بین عملکرد، پایداری و سهولت استفاده ارائه می‌دهد. برای پروژه‌های بسیار کوچک یا آموزشی، SQLite ممکن است کافی باشد، و برای پروژه‌های بزرگ با نیازهای داده‌ای پیچیده، PostgreSQL یا MySQL بهترین گزینه هستند.

بهترین روش‌ها و ملاحظات پیشرفته در مدیریت وضعیت Telebot

پیاده‌سازی FSM تنها قدم اول است. برای ساخت ربات‌های وضعیت‌مند قوی، مقیاس‌پذیر و با تجربه کاربری عالی، باید بهترین روش‌ها را به کار گرفت و به ملاحظات پیشرفته توجه کرد.

1. وضوح و سادگی در طراحی وضعیت‌ها:

• تعداد وضعیت‌ها را بهینه نگه دارید: هرچند FSM قدرتمند است، اما تعریف تعداد زیادی وضعیت غیرضروری می‌تواند کد را پیچیده کند. سعی کنید وضعیت‌ها را تا حد ممکن کلی و منطقی نگه دارید.
• نام‌گذاری گویا: برای `StatesGroup` و هر `State`، نام‌های واضح و توصیفی انتخاب کنید تا خوانایی کد افزایش یابد.
• نمودار وضعیت‌ها (State Diagram): برای ربات‌های پیچیده، رسم یک نمودار وضعیت (State Diagram) می‌تواند به شما در تجسم جریان کار و اطمینان از پوشش همه مسیرهای ممکن کمک کند.

2. اعتبارسنجی قوی و بازخورد مناسب به کاربر:

• اعتبارسنجی در هر مرحله: هر Handler وضعیت‌مند باید ورودی دریافتی را اعتبارسنجی کند. اگر ورودی نامعتبر است، پیام خطای واضحی به کاربر ارسال کرده و او را در همان وضعیت نگه دارید تا ورودی صحیح را وارد کند.
• پیام‌های راهنما: در هر مرحله، به کاربر اطلاع دهید که ربات چه انتظاری از او دارد. این کار از سردرگمی جلوگیری می‌کند.
• تکرار مجدد درخواست (Retry): در صورت ورود نامعتبر، به کاربر فرصت دهید تا مجدداً ورودی را ارائه دهد، نه اینکه فرآیند را به طور کامل متوقف کنید.

3. مدیریت زمان‌بندی و انقضای وضعیت‌ها:

• Timeout برای وضعیت‌ها: اگر کاربر برای مدت طولانی (مثلاً 10 دقیقه) در یک وضعیت خاص بدون پاسخ بماند، ممکن است بخواهید وضعیت او را پاک کرده و فرآیند را لغو کنید تا منابع آزاد شوند و از تعاملات نیمه‌کاره جلوگیری شود. این را می‌توان با افزودن timestamp به داده‌های وضعیت و یک وظیفه پس‌زمینه (Background Task) برای بررسی آن‌ها انجام داد.
• یادآوری‌ها: برای فرآیندهای طولانی، می‌توانید پس از یک مدت زمان مشخص، یک پیام یادآوری برای کاربر ارسال کنید.

4. قابلیت لغو فرآیند در هر زمان:

• دستور /cancel: همیشه یک راه آسان برای کاربر فراهم کنید تا بتواند از یک فرآیند چندمرحله‌ای خارج شود. یک Handler سراسری برای `/cancel` با `state='*'` ضروری است.
• بازگشت به عقب: برای فرآیندهای پیچیده‌تر، ممکن است بخواهید قابلیت "بازگشت به مرحله قبلی" را نیز فراهم کنید. این کار نیاز به نگهداری تاریخچه وضعیت‌ها دارد.

5. معماری و مقیاس‌پذیری ربات‌های وضعیت‌مند:

• استفاده از ذخیره‌ساز پایدار: برای ربات‌های تولیدی، همیشه از یک `StateStorage` پایدار (Redis, PostgreSQL) استفاده کنید.
• جداسازی منطق (Separation of Concerns): منطق مربوط به هر وضعیت را در توابع جداگانه یا حتی ماژول‌های جداگانه نگه دارید. این کار کد را خواناتر، تست‌پذیرتر و قابل نگهداری‌تر می‌کند.
• مدیریت خطا جامع: هرچند اعتبارسنجی ورودی مهم است، اما باید برای خطاهای غیرمنتظره (مانند مشکلات دیتابیس یا API) نیز مکانیزم‌های مدیریت خطا داشته باشید.
• تست‌پذیری: ربات‌های وضعیت‌مند می‌توانند پیچیده باشند. از نوشتن تست‌های واحد (Unit Tests) و تست‌های یکپارچه‌سازی (Integration Tests) برای اطمینان از عملکرد صحیح تمام مسیرهای وضعیت اطمینان حاصل کنید.
• پشتیبانی از چندین فرآیند همزمان: اگر ربات شما همزمان چندین فرآیند چندمرحله‌ای متفاوت را انجام می‌دهد (مثلاً ثبت‌نام و سفارش همزمان)، مطمئن شوید که `StatesGroup`ها و داده‌های مربوط به هر فرآیند به درستی از هم تفکیک شده‌اند. معمولاً برای هر فرآیند اصلی یک `StatesGroup` جداگانه تعریف می‌شود.

6. بین‌المللی‌سازی (i18n):

اگر قصد دارید ربات خود را به زبان‌های مختلف ارائه دهید، محتوای پیام‌ها و حتی نام وضعیت‌ها را نیز باید قابلیت بین‌المللی‌سازی داشته باشند. این کار معمولاً با استفاده از یک سیستم مدیریت ترجمه (مانند `gettext`) انجام می‌شود.

با رعایت این بهترین روش‌ها، می‌توانید ربات‌های Telebot را توسعه دهید که نه تنها از نظر فنی قدرتمند هستند، بلکه تجربه کاربری فوق‌العاده‌ای را نیز ارائه می‌دهند و می‌توانند به راحتی رشد کرده و مقیاس‌پذیر شوند.

جمع‌بندی و گام‌های بعدی

در این راهنمای جامع، ما به بررسی عمیق مفهوم و پیاده‌سازی مدیریت وضعیت‌ها (State Management) در ربات‌های Telebot پرداختیم. دریافتیم که چرا مدیریت وضعیت برای ساخت ربات‌های تعاملی و چندمرحله‌ای ضروری است و چگونه رویکردهای ساده و ابتدایی در عمل با محدودیت‌های جدی مواجه می‌شوند. هسته اصلی بحث ما، معرفی و پیاده‌سازی الگوی Finite State Machine (FSM) با استفاده از `StatesGroup` و `StateContext` در Telebot بود که یک راهکار قدرتمند و سازمان‌یافته برای هندل کردن مکالمات پیچیده ارائه می‌دهد.

ما گام به گام یک مثال کاربردی از ربات ثبت‌نام را با FSM پیاده‌سازی کردیم و نحوه تعریف وضعیت‌ها، انتقال بین آن‌ها، ذخیره‌سازی و بازیابی داده‌ها، و همچنین مدیریت خطاهای ورودی و امکان لغو فرآیند را بررسی کردیم. همچنین، به اهمیت حیاتی ذخیره‌سازی پایدار وضعیت‌ها پرداختیم و گزینه‌های مختلفی مانند SQLite، Redis و PostgreSQL را به همراه مزایا و معایب هر یک برای ساخت ربات‌های تولیدی معرفی کردیم.

در نهایت، بهترین روش‌ها و ملاحظات پیشرفته‌ای از جمله طراحی وضعیت‌ها، اعتبارسنجی ورودی، مدیریت زمان‌بندی، قابلیت لغو، معماری و مقیاس‌پذیری و بین‌المللی‌سازی را برای ساخت ربات‌های وضعیت‌مند قوی، قابل اعتماد و کاربرپسند مورد بحث قرار دادیم.

گام‌های بعدی برای شما:

1. تمرین عملی: کد مثال ارائه‌شده را اجرا کرده و آن را برای سناریوهای مختلف دستکاری کنید. سعی کنید یک فرم پیچیده‌تر با انواع ورودی‌های مختلف ایجاد کنید.
2. پیاده‌سازی ذخیره‌ساز پایدار: یکی از ذخیره‌سازهای پایدار (به خصوص `RedisStorage` که در Telebot موجود است) را در پروژه خود ادغام کنید تا ربات شما در برابر ری‌استارت شدن مقاوم باشد.
3. کاوش بیشتر: به مستندات رسمی Telebot مراجعه کنید تا با جزئیات بیشتر `StateContext` و سایر ویژگی‌های FSM آشنا شوید.
4. پروژه‌های واقعی: سعی کنید این مفاهیم را در پروژه‌های ربات واقعی خود به کار ببرید و چالش‌های جدیدی را حل کنید.

مدیریت وضعیت، کلید ساخت ربات‌هایی است که می‌توانند فراتر از تعاملات ساده، به عنوان دستیارهای هوشمند و ابزارهای کارآمد عمل کنند. با تسلط بر این مفهوم و ابزارهای Telebot، شما قادر خواهید بود ربات‌هایی با سطح جدیدی از پیچیدگی و تجربه کاربری ایجاد کنید.