tutor answers step by step in plain text, islands finish, and the audit's money and login holes are closed

Tutor (prompt tutor-v3-stepwise-plain): plain text instead of LaTeX/markdown,
with rag/services/mathtext.py converting whatever still slips through; full
step-by-step solutions with a check before the final answer; three tones by
grade; the last 6 messages of the conversation go to the model and follow-ups
are no longer served from another user's cache; book solutions the checker
disputes are kept out of the context; a questionId gives the tutor the
practice question and the student's wrong answer. /api/health reports when
the AI credit runs out. rag_model_benchmark compares chat models on verified
book problems (run on the server; credit ran out mid-run).

Map: only lessons that have questions count toward finishing an island,
lessonIds[0] / nextLessonId is always the next lesson to play, and a finished
island stays finished. The Seyar characters (sigma/delta/pi) are seeded.

Audit fixes, each reproduced before fixing:
- the plan is stored on the order, so paying a monthly order after starting
  a yearly checkout no longer grants a year
- opening checkout no longer demotes an active subscription; renewals extend
  from the current expiry; expired subscriptions are not reported active
- one discount code per order and only before the gateway; a 100% code
  completes the purchase; lost Zarinpal confirmations are re-verified
- the unused /api/payment/webhook "mark paid" endpoint is removed
- XP counts only answers recorded on the server
- 6-digit OTP, each code dies after 5 wrong guesses; POST /api/auth/logout
- a guest who signs up keeps their account and progress (test phones excluded)
- affiliate commission on the first real payment; guests excluded
- parents with several children no longer get a 500
- SQLite runs transactions IMMEDIATE, since it ignores select_for_update
- admin login is rate-limited; display names drop phone numbers and links;
  userQuestion is capped at 2000 characters
- server-side heart enforcement exists behind HEARTS_ENFORCED (off until the
  frontend handles 403 no_hearts)

Not done on purpose: rotating the server's secret key and moving to Postgres.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

payment/services.py

@@ -25,13 +25,17 @@ class IdempotencyKeyConflict(APIException):
 
 
 def _ensure_idempotent_match(order: Order, *, user_id: int, amount: int, currency: str,
-                              subscription_id: int | None) -> None:
+                              subscription_id: int | None, plan_id: int | None = None) -> None:
     if order.user_id != user_id:
         raise IdempotencyKeyConflict(
             'این Idempotency-Key متعلق به کاربر دیگری است و نمی‌تواند استفاده شود.'
         )
-    if (order.amount != amount or order.currency != currency
-            or order.subscription_id != subscription_id):
+    # مبلغ فقط برای سفارشی که هنوز تخفیف نگرفته مقایسه می‌شود؛ بعد از کدِ
+    # تخفیف، مبلغِ سفارش عمداً کمتر از قیمتِ پلن است.
+    discounted = order.amount < amount and order.status == 'pending'
+    if ((order.amount != amount and not discounted) or order.currency != currency
+            or order.subscription_id != subscription_id
+            or (plan_id is not None and order.plan_id not in (None, plan_id))):
         raise IdempotencyKeyConflict(
             'این Idempotency-Key قبلاً با پارامترهای متفاوتی استفاده شده است.'
         )
@@ -52,7 +56,8 @@ def call_payment_gateway(order: Order) -> str:
 
 def create_order(*, user_id: int, amount: int, currency: str = 'IRT',
                   subscription_id: int | None = None, idempotency_key: str | None = None,
-                  provider: str = 'gateway', bazaar_product_sku: str = ''):
+                  provider: str = 'gateway', bazaar_product_sku: str = '',
+                  plan_id: int | None = None):
     """
     ساخت سفارش با پشتیبانی از Idempotency-Key: اگر سفارشی با همین کلید قبلاً
     ساخته شده باشد، همان رکورد برگردانده می‌شود (نه رکورد تکراری)، فقط اگر
@@ -65,7 +70,7 @@ def create_order(*, user_id: int, amount: int, currency: str = 'IRT',
     if existing is not None:
         _ensure_idempotent_match(
             existing, user_id=user_id, amount=amount, currency=currency,
-            subscription_id=subscription_id,
+            subscription_id=subscription_id, plan_id=plan_id,
         )
         payment_url = None if existing.provider == 'bazaar' else call_payment_gateway(existing)
         return existing, payment_url
@@ -75,6 +80,7 @@ def create_order(*, user_id: int, amount: int, currency: str = 'IRT',
             order = Order.objects.create(
                 user_id=user_id,
                 subscription_id=subscription_id,
+                plan_id=plan_id,
                 amount=amount,
                 currency=currency,
                 status='pending',
@@ -89,7 +95,7 @@ def create_order(*, user_id: int, amount: int, currency: str = 'IRT',
             raise
         _ensure_idempotent_match(
             order, user_id=user_id, amount=amount, currency=currency,
-            subscription_id=subscription_id,
+            subscription_id=subscription_id, plan_id=plan_id,
         )
 
     # برای provider='bazaar' هیچ paymentUrlی وجود ندارد: کلاینت اندروید مستقیماً
@@ -101,7 +107,7 @@ def create_order(*, user_id: int, amount: int, currency: str = 'IRT',
 def apply_order_payment_result(*, order: Order, gateway: str, gateway_ref_id: str,
                                 new_status: str, event: str) -> bool:
     """
-    منطق مشترکِ «نتیجه‌ی پرداخت رسید»، هم برای PaymentWebhookView و هم
+    منطق مشترکِ «نتیجه‌ی پرداخت رسید»، هم برای ZarinpalCallbackView و هم
     BazaarVerifyPurchaseView استفاده می‌شود.
 
     idempotent: اگر Transaction مشابه (order/status/gateway_ref_id) از قبل
@@ -167,7 +173,10 @@ def apply_order_payment_result(*, order: Order, gateway: str, gateway_ref_id: st
         if newly_paid:
             if order.subscription_id:
                 from subscription.services import activate_subscription
-                activate_subscription(order.subscription_id)
+                activate_subscription(order.subscription_id, plan_id=order.plan_id)
+            # پورسانتِ معرف فقط روی پرداختِ واقعی (نه ثبت‌نام، نه مهمان).
+            from affiliate.services import record_paid_order
+            record_paid_order(order)
 
             from notifications.services import notify
             notify(
@@ -178,3 +187,44 @@ def apply_order_payment_result(*, order: Order, gateway: str, gateway_ref_id: st
             )
 
     return newly_paid
+
+
+def reconcile_pending_order(order: Order) -> bool:
+    """
+    سفارشی که کاربر در درگاه پرداخت کرده ولی تأییدش نرسیده (مثلاً زرین‌پال
+    هنگامِ کال‌بک جواب نداد) را دوباره با verify می‌سنجد. پیش‌تر چنین سفارشی
+    برای همیشه pending می‌ماند: پولِ دانش‌آموز گرفته شده بود و اشتراکی در کار نبود.
+
+    فقط به سمتِ paid می‌برد، هرگز failed نمی‌کند: کاربری که هنوز در صفحه‌ی
+    درگاه است نباید سفارشش زیرِ پایش باطل شود. هر سفارش حداکثر دقیقه‌ای یک بار
+    سنجیده می‌شود. خروجی: True اگر همین فراخوانی سفارش را paid کرد.
+    """
+    from django.core.cache import cache
+
+    from . import zarinpal
+
+    if order.provider != 'gateway' or order.status != 'pending' or not order.gateway_authority:
+        return False
+    if not cache.add(f'payment:reconcile:{order.id}', 1, 60):
+        return False
+    try:
+        result = zarinpal.verify_payment(
+            authority=order.gateway_authority, amount=order.amount, currency=order.currency,
+        )
+    except Exception:  # noqa: BLE001 — درگاه در دسترس نیست؛ دفعه‌ی بعد
+        return False
+    if not result.is_valid:
+        return False
+    return apply_order_payment_result(
+        order=order, gateway='zarinpal', gateway_ref_id=result.ref_id,
+        new_status='paid', event='zarinpal_reconcile',
+    )
+
+
+def reconcile_user_orders(user_id: int) -> None:
+    """سفارش‌های pendingِ اخیرِ یک کاربر؛ از صفحه‌ی وضعیتِ اشتراک صدا زده می‌شود."""
+    since = timezone.now() - timezone.timedelta(days=2)
+    for order in Order.objects.filter(
+        user_id=user_id, status='pending', provider='gateway', created_at__gte=since,
+    ).exclude(gateway_authority='')[:3]:
+        reconcile_pending_order(order)