52 lines
9.6 KiB
Markdown
52 lines
9.6 KiB
Markdown
# اطلاع‌رسانی فیش مشتری
|
||
|
||
پس از ثبت موفق فیش مشتری، اپ `payments` اعلان‌ها را در صف `NotificationJob` قرار می‌دهد. ثبت از حساب مشتری، لینک کوتاه پرداخت و «ثبت فیش برای مشتری» در پنل کارشناس همگی پشتیبانی می‌شوند. ثبت دستی کارشناس نیز با همان تنظیمات به مدیران فعال پیامک می‌فرستد و تصویر فیش را به همان گروه بله ارسال می‌کند؛ اطلاعات پیام مربوط به مشتری و واریزکننده است. تصویر هر نسخه مستقل است؛ گزینه «اطلاع‌رسانی فیش اصلاح‌شده مشتری» تعیین می‌کند نسخه‌های اصلاحی نیز، چه توسط مشتری و چه کارشناس مجاز ثبت شوند، اعلان داشته باشند.
|
||
|
||
این اصلاح migration یا تنظیمات جداگانه نمی‌خواهد. برای اعمال آن، سرور برنامه و Worker موجود `process_notifications` را با نسخه جدید کد بازراه‌اندازی کنید. اعلان‌های مربوط به ثبت‌های قبلی که صفی برای آن‌ها ساخته نشده، به‌صورت خودکار ارسال نمی‌شوند.
|
||
|
||
## راه‌اندازی
|
||
|
||
۱. migration `payments.0007_receipt_alerts` را اجرا کنید. هر دو کانال در شروع خاموش‌اند و بدون تنظیمات هیچ اعلانی ساخته نمی‌شود.
|
||
|
||
۲. در Django Admin، بخش پرداخت‌ها، «تنظیمات اطلاع‌رسانی فیش مشتری» را باز کنید:
|
||
|
||
`/x5admin/payments/paymentreceiptalertconfiguration/`
|
||
|
||
- بله: توکن ربات، شناسه گروه و متن همراه تصویر را وارد و کانال را فعال کنید. ربات باید مجوز ارسال به گروه داشته باشد. این توکن از `BALE_BOT_TOKEN` مربوط به تیکت‌ها مستقل است.
|
||
- پیامک: کانال را فعال کنید، متن پیامک را تنظیم کنید و در جدول همان صفحه مدیران دریافت‌کننده را با نام و شماره موبایل اضافه کنید. هر مدیر گزینه فعال مستقل دارد. شماره‌ها با قالب موبایل فعلی پروژه یکسان‌سازی می‌شوند و شماره تکراری پذیرفته نمی‌شود. درگاه پیامک فعلی پروژه استفاده می‌شود.
|
||
- برای حفظ توکن ذخیره‌شده، فیلد توکن را خالی بگذارید. برای تعویض، توکن تازه وارد کنید. برای حذف، ابتدا بله را خاموش و گزینه پاک‌کردن توکن را انتخاب کنید. مقدار توکن در HTML فرم و ممیزی پرداخت درج نمی‌شود؛ توکن در دیتابیس تنظیمات نگهداری می‌شود و دسترسی دیتابیس/نسخه پشتیبان باید محدود باشد.
|
||
|
||
۳. Worker موجود `process_notifications` باید با نسخه جدید کد اجرا شود و به storage تصاویر فیش دسترسی داشته باشد. در محیط تولید از محیط مجازی همان سرور استفاده کنید. اجرای Worker قبلی را پس از انتشار بازراه‌اندازی کنید؛ Worker جدید جداگانه لازم نیست.
|
||
|
||
مجوز مدیریت تنظیمات و مدیران: `payments.manage_receipt_alerts`. مدیرعامل یا superuser فعال با حساب STAFF نیز مطابق سیاست فعلی پرداخت دسترسی دارد.
|
||
|
||
## متن و سابقه
|
||
|
||
تگ‌های متن: `{amount_rial}` (ریال)، `{customer_name}`، `{customer_mobile}`، `{received_at}` (تاریخ و ساعت شمسی)، `{paid_date}` (تاریخ واریز شمسی)، `{receipt_number}`، `{revision_version}`، `{receipt_link}` و `{manager_name}`. تگ `{customer_name}` شامل نام مشتری و نام واریزکننده ثبت‌شده روی نسخه فیش است؛ اگر این دو نام یکسان باشند، فقط یک بار نوشته می‌شود. اگر نام مشتری خالی باشد، نام واریزکننده نمایش داده می‌شود. در قالب سفارشی بدون این تگ نیز هویت مشتری/واریزکننده به متن اضافه می‌شود. نام‌ها با قواعد یکسان‌سازی فارسی مقایسه می‌شوند. قالب‌بندی اضافی یا دسترسی به ویژگی‌های شیء در تگ‌ها پذیرفته نمی‌شود.
|
||
|
||
## نام واریزکننده و رد فیش
|
||
|
||
فیلد «نام واریزکننده» در تمام مسیرهای ثبت و اصلاح فیش اجباری است. نام پروفایل مشتری (و در نبود آن، نام حساب کاربری) پیش‌فرض فرم است و قابل تغییر می‌ماند؛ ثبت این نام، پروفایل مشتری را تغییر نمی‌دهد. هر نسخه نام مستقل دارد. migration `payments.0008_paymentreceiptrevision_depositor_name` برای نسخه‌های قدیمی مقدار خالی می‌گذارد، چون نام واقعی واریزکننده قابل بازسازی نیست؛ پنل این وضعیت را مشخص می‌کند و هنگام اصلاح، ثبت نام الزامی است.
|
||
|
||
پس از رد فیش توسط تأییدکننده مجاز، یک پیامک مشتری با رویداد `PAYMENT_RECEIPT_REJECTED` در صف موجود ثبت می‌شود. پیش از ثبت، صفحه بررسی هشدار می‌دهد که دلیل رد برای مشتری ارسال می‌شود و تأیید کارشناس را با نمایش متن دلیل می‌گیرد. درخواست HTTP بدون تأیید پذیرفته نمی‌شود. پیامک شامل دلیل کامل و لینک کوتاه مشاهده و اصلاح فیش است؛ کلید یکتای چرخه بررسی جلوی ساخت پیامک تکراری را می‌گیرد. ثبت تصمیم و صف در یک تراکنش انجام می‌شود و ارسال شبکه‌ای در Worker است.
|
||
|
||
migrationهای `notifications.0019` و `notifications.0020` رویداد و قالب عمومی قابل ویرایش آن را اضافه می‌کنند. تگ `{rejection_reason}` متن دلیل است؛ اگر قالب سفارشی آن را حذف کند، دلیل همچنان به انتهای پیام اضافه می‌شود. پس از انتشار، migrationها را اجرا و Worker موجود را بازراه‌اندازی کنید.
|
||
|
||
بله فایل خصوصی را مستقیماً همراه متن دریافت می‌کند؛ آدرس عمومی تصویر ایجاد نمی‌شود. لینک پیش‌فرض متن به جزئیات محافظت‌شده کارشناسان است. PNG/JPEG به‌صورت تصویر و دیگر فرمت‌های مجاز فیش به‌صورت فایل تصویری ارسال می‌شوند.
|
||
|
||
صفحه سوابق:
|
||
|
||
`/x5admin/payments/paymentreceiptalert/`
|
||
|
||
برای هر نسخه و مقصد، سابقه مستقل شامل گیرنده، متن، کانال، تعداد تلاش، خطای آخر و نتیجه دریافت پیامک وجود دارد. پذیرش سرویس پیامک با رسیدن به گوشی متفاوت است؛ نتیجه دریافت از استعلام Worker و قابلیت درگاه می‌آید. سوابق فقط خواندنی‌اند.
|
||
|
||
## رفتار هنگام خطا و تغییر تنظیمات
|
||
|
||
- ثبت فیش هیچ درخواست شبکه‌ای برای اعلان انجام نمی‌دهد. ساخت صف در همان تراکنش است؛ rollback ثبت فیش، صف آن را نیز حذف می‌کند. nonce و کلید یکتای نسخه/کانال/گیرنده جلوی ساخت اعلان تکراری را می‌گیرند.
|
||
- خرابی صف یک مقصد با savepoint جدا مدیریت می‌شود؛ مقصدهای دیگر و ثبت فیش ادامه پیدا می‌کنند. اگر خواندن تنظیمات یا ساخت صف ممکن نباشد، خطای بدون اطلاعات محرمانه در لاگ ثبت می‌شود؛ چنین خطایی صف قابل تلاش مجدد ایجاد نمی‌کند.
|
||
- خطای شبکه/درگاه/فایل در Worker به خطای اعلان تبدیل می‌شود. تلاش مجدد از سیاست محدود فعلی پیامک و بله پیروی می‌کند و ثبت یا بررسی فیش را تغییر نمی‌دهد. خطای یک اعلان پردازش مقصدهای دیگر را متوقف نمی‌کند.
|
||
- خاموش‌کردن کانال یا مدیر، یا تغییر شماره/شناسه گروه، اعلان‌های قبلی ارسال‌نشده آن مقصد را لغو می‌کند. توکن جدید برای تلاش‌های بعدی خوانده می‌شود. متن و اطلاعات مشتری/گیرنده مربوط به زمان ثبت نسخه حفظ می‌شوند؛ تغییر متن، پیام‌های جدید را تغییر می‌دهد.
|
||
- همانند صف فعلی پروژه، اگر سرویس پیام را بپذیرد ولی پاسخ شبکه گم شود، تلاش بعدی ممکن است ارسال بیرونی را تکرار کند؛ سرویس بیرونی تضمین exactly-once ندارد.
|
||
|
||
تست‌ها در `tests/test_payment_receipt_alerts.py` تمام ارسال‌ها را mock می‌کنند و به گروه یا موبایل واقعی پیام نمی‌فرستند.
|