# راهنمای معماری پروژه (Architecture & Integration Guide)

> [!IMPORTANT]
> **قانون همگام‌سازی مستندات (Documentation Sync Rule):**
> هر زمان تغییر جدیدی در ساختار پروژه، کلاس‌ها، فایل‌های استقرار یا تنظیمات اعمال شد، باید همزمان هر دو فایل [README.md](file:///d:/Rambot/todo/README.md) (برای نمایش در گیت‌هاب) و [architecture_guide.md](file:///d:/Rambot/todo/architecture_guide.md) (راهنمای معماری داخلی) به‌روزرسانی شوند.
> 
> *Whenever any change is made to the project structure, classes, deployment files, or settings, both [README.md](file:///d:/Rambot/todo/README.md) and [architecture_guide.md](file:///d:/Rambot/todo/architecture_guide.md) must be updated simultaneously.*

این سند راهنما به منظور تشریح ساختار پرونده‌ها، نحوه مدیریت خطاها (Logging)، نحوه تعامل مینی‌اپ با سرور و به‌روزرسانی‌های تلگرام طبق متدهای مدرن نسخه 7+ آماده شده است.

---

## ۱. ساختار دایرکتوری‌ها و معماری پروژه

پروژه به صورت یک ربات تلگرام به همراه یک مینی‌اپ (Telegram Mini App) طراحی شده است. ساختار پوشه‌ها به شرح زیر سازماندهی شده است:

```
todo/
├── api/                  # وب‌سرویس‌ها و APIهای بک‌اند که توسط مینی‌اپ فراخوانی می‌شوند
│   ├── log_error.php     # مدیریت و ثبت خطاهای مربوط به کلاینت مینی‌اپ
│   ├── get_user_info.php # استعلام اطلاعات پروفایل قبلی کاربر جهت پیش‌فرض‌سازی فرم‌ها (جدید)
│   └── ...               # اندپوینت‌های عملیاتی (تسک‌ها، کاربران، گزارش‌ها و...)
├── assets/               # دارایی‌های ثابت پروژه (تصاویر و رسانه‌ها)
├── classes/              # کلاس‌های PHP (هسته پردازش منطق برنامه)
│   ├── BotHandler.php    # کنترل‌کننده مرکزی (سازماندهی شده با استفاده از Traitها برای کاهش حجم)
│   ├── CallbackHandler.php # ویژگی (Trait) پردازش CallbackQueryها (مدیریت شده با ساب‌هندلرها)
│   ├── Handler/          # هندلرهای تخصصی و تقسیم‌شده برای مدیریت CallbackQueryها (جدید)
│   │   ├── SprintCallbackHandler.php       # هندلر رویدادهای مربوط به اسپرینت‌ها
│   │   ├── EventCallbackHandler.php        # هندلر رویدادهای مربوط به مناسبت‌ها
│   │   ├── DocumentCallbackHandler.php     # هندلر رویدادهای مربوط به مدارک و آپلودها
│   │   ├── RegistrationCallbackHandler.php # هندلر رویدادهای ثبت‌نام و مدیریت اعضا
│   │   ├── ProjectCallbackHandler.php      # هندلر رویدادهای پروژه‌ها، تسک‌ها و تاریخچه
│   │   └── GeneralCallbackHandler.php      # هندلر عمومی و سایر دکمه‌های ناوبری
│   ├── RequestHandler.php  # ویژگی (Trait) پردازش پیام‌ها و دستورات معمولی تلگرام (جدید)
│   ├── LocationHandler.php # ویژگی (Trait) پردازش پیام‌های موقعیت مکانی (جدید)
│   ├── Functions.php     # ویژگی (Trait) حاوی توابع کمکی و فرعی متفرقه
│   ├── Database.php      # مدیریت ارتباط با پایگاه‌داده و اجرای کوئری‌ها
│   ├── ButtonHelper.php  # کلاس کمکی برای ساخت دکمه‌های شیشه‌ای رنگی و ایموجی سفارشی تلگرام (جدید)
│   ├── Logger.php        # کلاس لاگر برنامه برای ثبت وقایع و ارسال به ادمین تلگرام
│   └── ...
├── config/               # پیکربندی‌های کلی برنامه
│   ├── AppConfig.php     # تنظیمات محیطی، دیتابیس، توکن ربات و متغیرهای سراسری
│   └── jdf.php           # توابع تقویم جلالی (خورشیدی)
├── cronjobs/             # اسکریپت‌های کران‌جاب برای کارهای زمان‌بندی شده
├── json/                 # پایگاه‌داده‌های محلی و فایل‌های تنظیمات موقعیت جغرافیایی
├── log/                  # پوشه متمرکز ذخیره‌سازی فایل‌های لاگ (جدید)
│   ├── php_errors.log    # تمامی لاگ‌های خطای PHP در این فایل متمرکز می‌شوند
│   └── mini_app_errors.log # خطاهای ارسالی از مینی‌اپ کلاینت
├── mini-app/             # کلاینت فرانت‌اند مینی‌اپ تلگرام (HTML/JS/CSS)
├── payment/              # ماژول پرداخت‌های برنامه
│   ├── ZarinpalPaymentHandler.php  # درگاه پرداخت زرین‌پال
│   └── StarPaymentHandler.php      # درگاه پرداخت ستاره تلگرام (Telegram Stars)
├── public/               # نقطه ورود عمومی ربات تلگرام
│   ├── bot.php           # وب‌هوک ربات تلگرام (Webhook Entrypoint)
│   └── diagnose.php      # اسکریپت تشخیصی و عیب‌یابی سیستمی مستقل (جدید)
└── composer.json         # مدیریت وابستگی‌های پروژه (PSR-4 Autoloading)
```

---

## ۲. سیستم مدیریت خطا و لاگ متمرکز (Centralized Logging)

پیش از این، خطاهای برنامه در قالب فایل‌های مجزای `error_log` در پوشه‌های مختلف پروژه مانند `api/` یا `cronjobs/` به صورت پراکنده ذخیره می‌شدند. اکنون سیستم لاگینگ به صورت زیر یکپارچه و متمرکز شده است:

### الف) تنظیم متمرکز خطاهای PHP
در کلاس پیکربندی [AppConfig.php](file:///d:/Rambot/todo/config/AppConfig.php)، تنظیمات سراسری مفسر PHP اعمال شده تا تمامی پیام‌های هشدار، خطا و عملکردهای تابع استاندارد `error_log()` به صورت خودکار به پوشه متمرکز `log/` هدایت شوند:
```php
ini_set('log_errors', '1');
ini_set('error_log', dirname(__DIR__) . '/log/php_errors.log');
```
این کار موجب می‌شود تمام خطاهای زمان اجرا در سراسر وب‌سرویس‌ها به فایل متمرکز `log/php_errors.log` منتقل و پوشه‌های دیگر تمیز بمانند.

### ب) لاگ خطاهای مینی‌اپ کلاینت
اسکریپت فرانت‌اند مینی‌اپ خطاها را به صورت متمرکز به فایل [log_error.php](file:///d:/Rambot/todo/api/log_error.php) ارسال می‌کند. این اسکریپت نیز به‌روزرسانی شده تا خروجی لاگ را در مسیر یکپارچه زیر ثبت نماید:
`log/mini_app_errors.log`

---

## ۳. به‌روزرسانی متدهای جدید تلگرام (Telegram Bot API v7+)

پروژه به طور کامل با تغییرات و استانداردهای جدید تلگرام تطبیق داده شده است:

### الف) جایگزینی پارامتر منسوخ شده پیش‌نمایش لینک‌ها
در متدهای قبلی تلگرام، از پارامتر `disable_web_page_preview` استفاده می‌شد که اکنون منسوخ (Deprecated) شده است. این پارامتر در تمامی فایل‌های کلیدی از جمله:
- [Logger.php](file:///d:/Rambot/todo/classes/Logger.php)
- [cron_reports.php](file:///d:/Rambot/todo/cronjobs/cron_reports.php)
- [BotHandler.php](file:///d:/Rambot/todo/classes/BotHandler.php)
- [register_collection.php](file:///d:/Rambot/todo/api/register_collection.php)

با پارامتر ساختاریافته و مدرن `link_preview_options` به شرح زیر جایگزین گردید:
```php
"link_preview_options" => ["is_disabled" => true]
```

### ب) سیستم پرداخت با ستاره تلگرام (Telegram Stars)
برای پشتیبانی از خرید دارایی‌های دیجیتال و خدمات درون‌برنامه‌ای با استفاده از ستاره تلگرام، کلاس [StarPaymentHandler.php](file:///d:/Rambot/todo/payment/StarPaymentHandler.php) پیاده‌سازی شد. ویژگی‌های مهم متدهای جدید Stars شامل موارد زیر است:
1. استفاده از واحد پولی ستاره با کد `'XTR'`.
2. خالی گذاشتن فیلد `provider_token` به عنوان نشان‌دهنده پرداخت مستقیم از درگاه Stars تلگرام.
3. استفاده از متد استاندارد `sendInvoice` جهت صدور فاکتور ستاره برای کاربر.
4. پاسخ‌دهی به درخواست پیش‌خرید کاربر با متد `answerPreCheckoutQuery` قبل از نهایی شدن پرداخت.

---

## ۴. تجزیه کلاس عظیم BotHandler (Decomposition via Traits)

به دلیل حجم بسیار بالای فایل اصلی کلاس `BotHandler` (بیش از ۱۲,۰۰۰ خط کد)، این کلاس به صورت ماژولار و با استفاده از مکانیسم ویژگی‌ها (Traits) در PHP تفکیک شد. این کار بدون ایجاد هیچ‌گونه شکست در سازگاری کدهای قبلی (Backward Compatibility) صورت گرفت.

### الف) Traitهای جدید ایجاد شده:
1. **[CallbackHandler.php](file:///d:/Rambot/todo/classes/CallbackHandler.php)**: حاوی متد `handleCallbackQuery` برای مدیریت و مسیریابی رویدادها به ساب‌هندلرهای مربوطه.
2. **پوشه [Handler](file:///d:/Rambot/todo/classes/Handler)**:
   - **[SprintCallbackHandler.php](file:///d:/Rambot/todo/classes/Handler/SprintCallbackHandler.php)**: پردازش رویدادهای اسپرینت.
   - **[EventCallbackHandler.php](file:///d:/Rambot/todo/classes/Handler/EventCallbackHandler.php)**: پردازش رویدادهای مناسبت‌ها.
   - **[DocumentCallbackHandler.php](file:///d:/Rambot/todo/classes/Handler/DocumentCallbackHandler.php)**: پردازش بارگذاری فایل‌ها و تنظیم مدارک مجموعه.
   - **[RegistrationCallbackHandler.php](file:///d:/Rambot/todo/classes/Handler/RegistrationCallbackHandler.php)**: پردازش ثبت‌نام پرسنل و شرکت‌ها.
   - **[ProjectCallbackHandler.php](file:///d:/Rambot/todo/classes/Handler/ProjectCallbackHandler.php)**: پردازش عملیات پروژه، تسک و نمایش کارکردها.
   - **[GeneralCallbackHandler.php](file:///d:/Rambot/todo/classes/Handler/GeneralCallbackHandler.php)**: پردازش پیام‌های عمومی و ناوبری پیش‌فرض.
3. **[RequestHandler.php](file:///d:/Rambot/todo/classes/RequestHandler.php)**: حاوی متد `handleRequest` جهت پردازش پیام‌های متنی، دستورات اسلش و وضعیت‌های متنی کاربران.
4. **[LocationHandler.php](file:///d:/Rambot/todo/classes/LocationHandler.php)**: حاوی متد `handleLocation` برای دریافت موقعیت‌های مکانی کاربران.

### ب) نحوه بارگذاری در کلاس اصلی:
در فایل [BotHandler.php](file:///d:/Rambot/todo/classes/BotHandler.php)، این ویژگی‌ها ضمیمه و به صورت زیر فراخوانی می‌شوند:
```php
require_once __DIR__ . '/CallbackHandler.php';
require_once __DIR__ . '/RequestHandler.php';
require_once __DIR__ . '/LocationHandler.php';

class BotHandler
{
    use Functions;
    use CallbackHandler;
    use RequestHandler;
    use LocationHandler;
    
    // ...
}
```

---

## ۵. رفع هشدارهای فضای نام (Namespace Warnings Prevention)

در کدهای PHP نام‌گذاری شده (Namespaced)، استفاده از توابع و کلاس‌های پیش‌فرض PHP (مانند `Throwable`, `Exception`, `DateTime`, `DateTimeZone`) بدون وارد کردن آن‌ها یا بدون پیشوند `\`، باعث می‌شود محیط توسعه آن‌ها را در فضای نام محلی (به عنوان مثال `Bot\Throwable`) جستجو کند که منجر به خطاهای زرد و عدم شناسایی کلاس‌ها می‌شد.

برای حل این موضوع در تمام فایل‌های جدید و تقسیم‌شده، ایمپورت‌های زیر در بالای فایل‌ها به صورت صریح قرار گرفت:
```php
namespace Bot;

use Throwable;
use Exception;
use DateTime;
use DateTimeZone;
```
این امر باعث افزایش وضوح کد و از بین رفتن تمام هشدارهای محیط توسعه (IDE Warnings) شده است.

---

## ۶. سیستم تشخیصی و عیب‌یابی مستقل (System Diagnostics Dashboard)

برای عیب‌یابی سریع مشکلات هاست، پایگاه‌داده، دسترسی‌های فایل/پوشه و وضعیت اتصال وبهوک تلگرام، ابزار [diagnose.php](file:///d:/Rambot/todo/public/diagnose.php) در پوشه عمومی پروژه توسعه داده شده است.

### وظایف و بخش‌های اصلی ابزار تشخیصی:
1. **تست پایگاه‌داده (Database Ping)**:
   اتصال به پایگاه‌داده را بر اساس مشخصات ثبت شده در فایل `.env` بررسی کرده و سرعت پاسخ‌دهی را محاسبه می‌کند.
2. **بررسی قابلیت نوشتن فایل‌ها و پوشه‌ها (FileSystem Check)**:
   تک‌تک پوشه‌ها و فایل‌های حیاتی پروژه (مانند پوشه لاگ، فایل‌های وضعیت موقت و پوشه روت) را بررسی کرده و در صورت نبود دسترسی نوشتن، به صورت شفاف گزارش می‌دهد.
3. **بررسی اتصال به API تلگرام (Telegram API Ping)**:
   با ارسال متد `getMe` به تلگرام، بررسی می‌کند که آیا هاست شما در برقراری ارتباط با وب‌سرویس تلگرام مسدود شده است یا خیر.
4. **بررسی وضعیت وبهوک تلگرام (Telegram Webhook Info)**:
   آدرس وبهوک فعلی تلگرام، تعداد درخواست‌های معلق و آخرین خطاهای وبهوک ربات را نشان می‌دهد.
5. **تنظیم خودکار وبهوک ربات (Auto Webhook Setter)**:
   با استفاده از آدرس فعلی دامنه، آدرس وب‌هوک را به طور خودکار شناسایی کرده و دکمه‌ای جهت ثبت سریع وبهوک بر روی `bot.php` ارائه می‌دهد تا نیازی به اجرای دستی وبهوک نباشد.

---

## ۷. الزامات و استانداردهای نوین تلگرام (Telegram Bot API 9.4+ / 10.1+)

در توسعه و بروزرسانی‌های بعدی پروژه، رعایت قوانین و متدهای جدید نسخه ۹.۴ به بالا تلگرام الزامی است:

### الف) محافظت از اطلاعات حساس با Spoiler
اطلاعات مهم و حساس کاربران (مانند گذرواژه‌های موقت یا رمزهای تولید شده) در خروجی پیام‌های ربات باید در داخل تگ اسپویلر تلگرام قرار داده شوند تا به صورت پیش‌فرض مخفی بمانند.
- **فرمت HTML:**
  ```html
  <tg-spoiler>رمز عبور شما</tg-spoiler>
  ```

### ب) رنگ‌بندی و هویت بصری دکمه‌های شیشه‌ای (Inline Buttons)
از تلگرام نسخه ۹.۴، ربات‌ها می‌توانند مستقیماً از طریق فیلد `style` رنگ دکمه‌های شیشه‌ای را مشخص کنند. استایل‌های مجاز عبارتند از:
- `primary`: رنگ آبی تیره (مخصوص دکمه‌های اصلی و اقدامات معمولی)
- `success`: رنگ سبز (مخصوص دکمه‌های تایید، روشن کردن یا پیوستن)
- `danger`: رنگ قرمز (مخصوص دکمه‌های لغو، انصراف، خاموش کردن و حذف)

### ج) استفاده از ایموجی‌های سفارشی (Custom Emojis)
برای دکمه‌های شیشه‌ای می‌توان شناسه ایموجی سفارشی را در فیلد `icon_custom_emoji_id` ارسال کرد. 
* **قانون مهم:** در صورت قرار دادن ایموجی سفارشی روی دکمه شیشه‌ای، **نباید** از ایموجی معمولی در متن دکمه استفاده کنید.
* تمامی نگاشت‌ها و شناسه‌های ایموجی‌ها به همراه نحوه استفاده از کلاس کمکی `Bot\ButtonHelper` در سند [telegram_buttons.md](file:///d:/Rambot/todo/telegram_buttons.md) ثبت شده است.

### د) اصلاح ساختار لینک‌های تلگرام (Telegram Start Links)
در زمان ساخت لینک‌های عمیق (`t.me/bot?start=xxx`)، مطمئن شوید که متغیر سراسری پیوند ربات (`BOT_LINK`) از پسوند اضافه پاکسازی شده باشد تا لینک‌ها به فرمت غلط `?start=?start=xxx` تبدیل نشوند. برای این کار از ریجکس زیر در PHP استفاده می‌شود:
```php
$cleanBotLink = preg_replace('/[?&]start=$/', '', $botLink);
```