IPPanel Edge Pattern Queue Sender

ماژول ساده پایتون برای ارسال انبوه پیامک الگویی روی IPPanel Edge با صف تک‌کارگر، همزمانی کنترل‌شده، ریترای خودکار و گزارش فارسی شیک.

مناسب برای ارسال هزاران پیامک — بدون دردسر rate limit و با خروجی خوانا.

---

✨ ویژگی‌ها

• صف تک‌کارگر: callهای همزمان رو به ترتیب اجرا می‌کنه.
• همزمانی کنترل‌شده با ThreadPoolExecutor (تنظیم max_workers).
• ریترای خودکار روی خطاهای 429 و 5xx + بک‌آف.
• گزارش فارسی با ایموجی و آمار دقیق: موفق/ناموفق، کدهای وضعیت، نمونه خطاها.

---

🧩 پیش‌نیازها

• Python 3.9+
• کتابخانه requests

نصب:

pip install requests

---

📦 نحوه استفاده

فایل ippanel_edge_queue.py رو تو پوشه پروژه‌تون کپی کنید.

بعدش:

from ippanel_edge_queue import send_bulk

AUTH = "توکن_احراز_هویت_شما"
FROM = "+983000505"
CODE = "کد_الگو"

recipients = ["+989123456789", "+989123456780"]
params = {"code": "اول", "saat": "20"}

result = send_bulk(
    token=AUTH,
    from_number=FROM,
    pattern_code=CODE,
    recipients=recipients,
    params=params,
    max_workers=12,   # پیشنهاد: 8-16 — اگر 429 گرفتی کم کن
    max_retries=3,
    timeout_sec=15,
)

print(result.to_persian_summary())

📊 خروجی نمونه:

📊 گزارش ارسال پیامک الگو (Edge)
⏱️ مدت اجرا: 3.6 ثانیه
👥 تعداد کل گیرندگان: 2000
✅ موفق: 1988
❌ ناموفق: 12
🔢 آمار بر اساس کد وضعیت:
  ✅ 200: 1988
  ❌ 429: 8
  ❌ 422: 4
🧾 نمونه خطاها (حداکثر ۵ مورد):
  • +98912XXXXXXX → 429: {...}
  • +98913XXXXXXX → 422: {...}

---

⚙️ پارامترهای send_bulk

• token: رشته احراز هویت (همونی که تو cURL استفاده می‌کنی — معمولاً بدون Bearer)
• from_number: شماره فرستنده (مثلاً +983000505)
• pattern_code: کد الگوی ثبت‌شده
• recipients: لیست شماره‌ها به فرمت E.164
• params: دیکشنری پارامترهای الگو — کلیدها باید دقیقاً مثل فیلدهای الگو باشن
• api_url (اختیاری): پیش‌فرض https://edge.ippanel.com/v1/api/send
• max_workers: تعداد threadهای موازی — پیشنهاد 8-16
• max_retries: تعداد تلاش مجدد در صورت خطا — پیش‌فرض 3
• timeout_sec: تایم‌اوت هر درخواست — پیش‌فرض 15

---

📥 خروجی (SendResult)

شیء برگشتی شامل:

• ok_count, fail_count, total
• per_status: دیکشنری تعداد بر اساس کد وضعیت
• details: لیست کامل نتایج هر گیرنده
• duration_sec: زمان اجرا

و مهم‌تر از همه:

result.to_persian_summary()  # ← گزارش فارسی زیبا!

⚠️ توجه: در Edge، هر درخواست فقط یک گیرنده می‌پذیره — ماژول خودش برای هر شماره یه درخواست جدا می‌زنه.

---

⚠️ نکات مهم

• اگر 429 می‌گیری → max_workers رو کم کن (مثلاً 8 یا 10).
• کلیدهای params باید دقیقاً با فیلدهای الگو یکی باشن — وگرنه 422 می‌گیری.
• توکن رو هاردکد نکن! از متغیر محیطی استفاده کن.

---

❓ سوالات متداول

Q: هر گیرنده پارامتر متفاوت داره؟
A: فعلاً پشتیبانی نمی‌شه. لیست رو بشکن و چندبار send_bulk رو با paramsهای مختلف صدا بزن.

Q: نیاز به Bearer دارم؟
A: نه — همون رشته خامی که تو cURL کار می‌کنه رو بده.

---