اقرأ الإرسالات برمز مميّز النطاق لواجهة الإدارة

واجهة الإدارة هي جانب القراءة في FormFlow: خمسة مسارات GET، ورمز حامل واحد، ولا طريقة لكتابة أي شيء. إنها السطح الذي تستخدمه أدوات الفريق عندما تحتاج الإرسالات التي يحتفظ بها FormFlow فعلاً، لا نسخة في جدول بيانات.

اجعل الرمز ضيقاً بقدر المهمة

الرمز يخص الفريق لا الشخص. عند إنشائه تمنحه اسماً، وقدرة واحدة على الأقل — submissions:read أو refusals:read أو forms:read — واختيارياً قائمة نماذج، واختيارياً تاريخ انتهاء. لا يحتفظ FormFlow إلا بتجزئة، لذا يُعرض الرمز مرة واحدة عند الإنشاء ولا يُعرض بعدها. الإلغاء فوري؛ والرمز المنتهي يحتفظ بصفه ويحرر مكانه.

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

القراءات الخمس

كل مسار يقع تحت /api/v1/manage ويُصادَق برمز حامل في ترويسة Authorization.

• GET /api/v1/manage/forms — بيانات النماذج. يتطلب forms:read.

• GET /api/v1/manage/submissions — صفحة من الإرسالات. يتطلب submissions:read.

• GET /api/v1/manage/submissions/{uuid} — إرسال واحد، بما فيه إشارات الإزعاج التي تغفلها القائمة.

• GET /api/v1/manage/refused-submissions — المرفوضات التي احتفظ بها سجل النموذج. يتطلب refusals:read.

• GET /api/v1/manage/attempts/{attemptId} — حياة محاولة واحدة مرتبة عبر السجلات التي دونتها.

جسم الإرسال مفهرس بأسماء الحقول ويُعاد كما أُرسل. معظم الحقول نصوص، وحقل الاختيار المتعدد قائمة، وحقل الملف مرجع باسمه المخزّن، والشبكة كائن مفهرس بتسمية الصف. ومسار الإرسال الواحد هو الوحيد الذي يعيد إشارات الإزعاج.

ترقيم بالمؤشر

مسارات القوائم تُجيب بـ data وmeta. يأخذ limit من 1 إلى 200 والافتراضي 50، والترتيب بـ created_at ثم id تنازلياً. يقول meta.has_more هل توجد صفحة أخرى، وmeta.next_cursor هو القيمة المعتمة التي تعيدها كـ cursor. لا توجد إزاحة، لأن المجموعة تتحرك أثناء قراءتك، والإزاحة ستتخطى صفوفاً أو تكررها بصمت.

cursor=""
while :; do
  page=$(curl -sS "https://formflow.digital/api/v1/manage/submissions?limit=100&cursor=$cursor" \
    -H "Authorization: Bearer $FORMFLOW_TOKEN")
  echo "$page" | jq -r '.data[] | [.uuid, .form_id, .created_at] | @tsv'
  cursor=$(echo "$page" | jq -r '.meta.next_cursor // empty')
  [ "$(echo "$page" | jq -r '.meta.has_more')" = "true" ] || break
done

المرشحات ضيقة عن قصد: form_id وsince وuntil وis_spam وunread وq. و q بحث بالرمز الدقيق على فهرس أعمى، لا بحث داخل النصوص، ولا يجيب إلا حيث فهرسة البحث مفعّلة.

اتبع مرفوضاً واحداً إلى محاولته

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

معرّف المحاولة ليس فريداً بذاته، لذا تُقيَّد السلسلة بنموذج واحد دائماً. وحين يوجد المعرّف على أكثر من نموذج، يكون الجواب 409 ويسمّيها، وتعيد الطلب مع form_uuid للاختيار.

أين يكون سطح القراءة فجّاً

ثلاثة حدود أخرى تستحق المعرفة قبل أن تبني عليه. تُفكّ تشفير الأجسام داخل FormFlow وتُعاد كما خُزّنت، فالرمز الذي يقرأ الإرسالات هو رمز يقرأ بيانات شخصية، ويستحق تخزينه العناية نفسها التي يستحقها الرمز. والصف الذي يتعذر فك تشفير جسمه يعود بـ payload_error قيمته payload_unavailable بينما تصل بقية الصفحة. ورموز الرد دقيقة: 401 لرمز غير صالح أو منتهٍ أو ملغى، و403 لقدرة ناقصة أو خطة غير متاحة، و404 حين يكون السجل خارج نطاق الرمز، و422 لمرشح أو مؤشر غير صالح، و429 مع Retry-After لحد المعدل.

العقد الكامل — كل معامل وشكل رد وخطأ — في /docs/api. وإدخال سجل التغييرات للإصدار v1.0.0 يسجل الواجهة كما صدرت: واجهة إدارة موثقة بجانب نقطة النهاية الوحيدة التي تستقبل الإرسالات.