التقاط إرسال سيئ قبل «إرسال» باستخدام الفحص المسبق

إن الإرسال المرفوض يكلّف الشيء الوحيد الذي لا يستطيع هذا المنتج استعادته: شخصًا كان في الصفحة ثم لم يعد. يحتفظ FormFlow بكل رفض كسجل يمكنك التصرف بشأنه، وتحسب إشارات صحة النموذج تلك الرفوض. والفحص المسبق هو الجزء الوحيد من هذا الحكم الذي يعمل قبل «إرسال». وقد جاء مع v1.0.0.

ما الذي يجيب عنه الفحص المسبق

أرسل POST إلى /api/v1/f/{token}/preflight مع الإجابات التي كان نموذجك سيرسلها، بصيغة JSON، ورمز النموذج العام في المسار. تعيد الوجهة الحكم الذي كانت وجهة الاستقبال ستُصدره على تلك الإجابات، دون أن تُصدره. مرّر ترويسة Origin الخاصة بالصفحة فيُفحص تمامًا كما تفحصه وجهة الإرسال. والعقد مكتوب في مرجع API.

للاستجابة أربعة مفاتيح: ok وerrors وchecked وpolicy. وerrors كائن مفاتيحه أسماء الحقول وقيمه قوائم جمل، ويبقى كائنًا حتى وهو فارغ كي يستطيع مستدعٍ مولَّد فهرسته. أما checked فيسمّي ما طُلب فعلًا — البنية وorigin والمخطط — مع غياب origin في الصفحة المستضافة، لأن الصفحة التي يقدّمها FormFlow لا تخضع لقائمة مصادرك المسموحة.

استدعه والشخص ما زال في الصفحة

طلب fetch واحد يكفي. هذا شكل الاستدعاء؛ اربطه بالحدث الذي تثق به صفحتك أصلًا، مثل مغادرة حقل.

const endpoint = 'https://formflow.digital/api/v1/f/YOUR_FORM_TOKEN/preflight'

async function preflight(answers) {
  const response = await fetch(endpoint, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
    body: JSON.stringify(answers),
  })

  // A 429 or an outage is not a verdict. Say nothing rather than something wrong.
  if (!response.ok) return null

  const { ok, errors, checked, policy } = await response.json()
  return ok ? [] : Object.entries(errors)
}

اعرض الجمل العائدة بجوار الحقل الذي تسمّيه كل واحدة. لا تُعِد صياغة القواعد في كودك: الغاية من الوجهة أن تكون الرسالة التي يقرؤها الشخص هي الرسالة التي كانت الوجهة ستستعملها، بلغة النموذج لا بلغة JavaScript عندك.

اقرأ الإجابة

مفتاحان في errors ليسا حقلين. origin يحمل رفض قائمة المصادر، وsubmission يحمل رفضًا يخص النموذج لا إجابةً بعينها، مثل نموذج مغلق. سجّل كتلة policy: فالنسخة والبصمة معًا تعرّفان السياسة التي استعملها الحكم تحديدًا، وهذا ما تحتاجه في اليوم الذي يتبع فيه نجاحٌ هنا رفضًا هناك.

ما الذي لا يسأل عنه

إنه يسأل فقط نصف القرار الذي هو دالة محضة في إعداد النموذج. لا يشغّل تقييم الإزعاج، ولا يطلب تحدّي Turnstile، ولا ينظر إلى حقول الملفات إطلاقًا — فالفحص المسبق لا يحمل بايتات، لذا لا تُفحص الصورة المعلنة ولا يُوعَد بها. ولا يخزّن صفًا، ولا يستهلك حصة، ولا يسلّم شيئًا.

لكنه داخل محدِّد المعدل. يشارك الفحص المسبق دلو token|IP ودلو الطلبات على مستوى الفريق مع وجهة الإرسال، لذا قد تعيد دفعةٌ 429 مع Retry-After. و429 غيابٌ للحكم لا رفض، وعلى الصفحة أن تبقى صامتة بدل أن تخترع خطأً.

أين موضعه

كل آلية أخرى يملكها FormFlow لإرسال مرفوض تعمل بعد أن يُرفض شخص: سجل الرفض، وإشارة الصحة، وسطح الرفض، وصندوق الاسترداد. وهذه هي الوحيدة التي تعمل قبله. استعملها كأول الحكمين لا كالحكم الوحيد.

• النجاح ليس وعدًا. الإرسال هو من يقرر، ويقرر من جديد بكل ما لم يسأل عنه الفحص المسبق.

• غيّر النموذج بين الاستدعاءين فيمكن أن تتغير الإجابة معه. نسخة السياسة في الاستجابة هي التي حكمت عليك.

• لا تُفحص حقول الملفات، فلا تقل لمُرسِل قط إن صورته قُبلت استنادًا إلى فحص مسبق.

• errors مفاتيحه أسماء الحقول، لكن origin وsubmission ليسا حقلين؛ اعرضهما في أعلى النموذج.

• أي شخص يحمل رمز النموذج العام يمكنه استدعاؤه. وهو لا يثبت شيئًا عن هوية المستدعي، وليس سرًّا.