نظام واتساب في ڤاريونس: الربط والأزرار والفلوهات والقوالب وتأكيد الطلبات

يُدار نظام واتساب من مسار /dashboard/whatsapp، وصفحته هي WhatsAppDashboardPage من features/dashboard-whatsapp مع مخزن Zustand useWhatsAppStore وخطاف useWhatsAppConnected الذي يحدد ظهور عمود واتساب في /dashboard/orders وأزرار الإرسال في CRM.

الأزرار الموجودة فعلياً في الصفحة: مربع قبول الشروط وسياسة الخصوصية (بوابة قبل الربط)، زر ربط واتساب Connect، زر إلغاء الربط Disconnect بتأكيد المتصفح و phoneNumberId واحد فقط، زر إعادة مزامنة الويبهوك Resync webhooks، زر التفاصيل Details الذي يفتح حوار تشخيص الهاتف وWABA والقوالب، وزر الإعدادات Settings الذي يفتح OrderConfirmationSettingsDialog (تفعيل تلقائي + لغة ar/en). وفي /dashboard/orders يظهر عمود تأكيد واتساب وشارة WhatsAppConfirmationBadge وزر إرسال رسالة فقط عندما يوجد حساب isConnected.

فلو الربط: تحميل الحسابات GET /api/whatsapp/accounts، ثم بوابات (الشروط + متغيرات NEXT_PUBLIC_FACEBOOK_APP_ID و NEXT_PUBLIC_WHATSAPP_CONFIG_ID + HTTPS)، ثم تحويل يدوي إلى dialog/oauth مع redirect_uri يساوي origin+pathname و state في sessionStorage، ثم رجوع Facebook بنفس الصفحة مع ?code=&state= ثم POST /api/whatsapp/callback الذي يبادل الكود عبر GET /oauth/access_token قبل dbConnect، ويكتشف WABA عبر debug_token و granular_scopes ثم phone_numbers، ثم upsert ب WhatsAppAccount بمفتاح merchantId+phoneNumberId، ثم POST /{waba-id}/subscribed_apps مع override_callback_uri اختياري، ثم محاولة نشر قالبي order_confirmation_ar و order_confirmation_en دون تعطيل الربط عند الفشل.

فلو تأكيد الطلب: عند إنشاء طلب من Checkout العام أو يدوياً من اللوحة يُرسل القالب المختار fire-and-forget بعد الحفظ. النص يُبنى من lib/whatsapp/order-confirmation-body.js بمصدر واحد، بخمسة متغيرات مرقمة، مع تعقيم (أسطر جديدة وعلامات تبويب تتحول لمسافات). كل إرسال ناجح ينشئ صف WhatsAppOrderConfirmation بمفتاح outboundMessageId الفريد (source تلقائي أو يدوي). رد العميل بزر يُطابق عبر message.context.id على نفس الصف: تأكيد يحفظ confirmed ويحمي حجوزات المخزون النشطة دون تغيير data.status، وتعديل يسجل edit_requested دون حركة مخزون، وإلغاء يحرر المخزون أولاً عبر cancelOrderAndReleaseStock ثم يغير data.status غير المنتهي إلى cancelled فقط عند نجاح التحرير. بعد كل claim ناجح يُرسل إقرار نصي مجاني مخصوم بـ acknowledgementMessageId. حالات التسليم sent/delivered/read/failed تُطبق monotonic و failed نهائي.

الإرسال اليدوي POST /api/whatsapp/send يقبل to و type text/template و customerId مع template.name ولغة، ومصدر باراميترات واحد: components بشكل Meta الكامل، أو bodyParameters المختصر، أو orderId لقوالب تأكيد الطلب فقط حيث يبني الخادم الخمس قيم من نفس الطلب داخل نفس المتجر. حوار CRM (WhatsAppSenderDialog) يعد {{n}} في نص القالب ويرسم حقلاً لكل متغير، ولقوالب تأكيد الطلب يمرر رقم الطلب تلقائياً من صف الطلب دون إعادة إدخال. الأرقام تُطبَّع إلى E.164 digits عبر toWhatsAppSendNumber (صفر محلي يتحول لكود الدولة الافتراضي 20) قبل Graph، والمطابقة تستخدم whatsAppPhoneMatchFilter لتوسيع الصيغ.

المتطلبات الصارمة: Facebook JS SDK من connect.facebook.net، وHTTPS إجباري (Facebook Login يرفض http)، وطريقة دفع صالحة على WABA في Meta Business Manager وإلا يقبل Graph بـ 200 accepted دون تسليم فعلي، مع إكمال العملة والمنطقة الزمنية والعنوان والتحقق التجاري، وتطبيق Meta يجب أن يكون Live/Published لوصول الويبهوك الحقيقي، ونافذة 24 ساعة للرسائل النصية الحرة تتطلب inbound حديث بـ lastInboundAt من webhook فقط (رسائل التاجر الصادرة لا تفتح النافذة).

الخدمات والملفات: lib/whatsapp/service.js و order-confirmation.js و template-parameters.js و phone.js و send-debug.js و diagnostic-log.js و access-token.js (تشفير AES) و account-details.js و button-actions.js و delivery-status.js و inbound-message.js و webhook-*.js، وواجهات pages/api/whatsapp (accounts و account-details و callback و disconnect و send و connect القديم و templates و order-confirmation-settings و subscribe-webhooks و webhook)، وواجهة الأدمن POST /api/admin/whatsapp/deploy-order-confirmation-template من /admin/whatsapp-templates. سجل النشاط ActivityEvent يسجل connect و disconnect و webhook_resync و message_sent وإعدادات التأكيد دون تخزين توكنات أو هواتف كاملة أو نصوص رسائل. التشخيص الموحد [whatsapp/flow] مع traceId يتبع كل إرسال عبر docker compose logs web.