v1.29: حالة «تمت المعالجة» تصل إلى التصدير وواجهة API

أصدرت FormFlow الإصدار v1.29.0 بتاريخ 2026-10-02، وهو يُخرج حالة «تمت المعالجة» من صندوق الوارد. حتى الآن كان وسم الإرسال بأنه «تمت المعالجة» مرئيًا داخل FormFlow فقط. ابتداءً من هذا الإصدار، تسجّل ملفات التصدير بصيغ CSV وExcel وJSON وقت حدوث ذلك، وتعيد واجهة API للإدارة الوقت نفسه ويمكنها التصفية بحسبه.

ما الذي تغيّر

• تضيف ملفات التصدير بصيغتي CSV وExcel عمود «تمت المعالجة». رأس هذا العمود في الملف هو _handled_at، ويُكتب بالطريقة نفسها التي تُكتب بها أعمدة تفاصيل الإرسال الأخرى (مثل _id).

• تحمل ملفات التصدير بصيغة JSON مفتاح handled_at في كل إرسال.

• تعيد واجهة API للإدارة الحقل handled_at في كل إرسال، في القائمة وفي الإرسال المفرد.

• تقبل قائمة الإرسالات القيمة handled=true أو handled=false، لجلب الإرسالات التي تمت معالجتها فقط أو المفتوحة فقط.

• يعرض منتقي التصدير هذا العمود، فيمكنك إلغاء تحديده.

ما الذي يسجّله الوقت

القيمة هي اللحظة التي وسم فيها الفريق الإرسال بأنه «تمت المعالجة»، بصيغة ختم زمني ISO 8601 مثل 2026-10-02T09:30:00+00:00. ساعة تطبيق FormFlow مضبوطة على UTC، ولذلك تكون الإزاحة +00:00. الحالة تخص الفريق لا عضوًا بعينه: لا يوجد شخص مُسنَد إليه الإرسال، ويحمل التصدير وقتًا لا شخصًا.

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

في منتقي التصدير

في CSV وExcel يعرض منتقي التصدير الأعمدة التي يمكنك تضمينها. التصدير الذي اخترت فيه كل الأعمدة يحتوي الآن على عمود «تمت المعالجة». ألغِ تحديده فيحتفظ الملف بالتخطيط الذي كان لديك سابقًا، وهذا مهم إذا كانت أداة أخرى تقرأ الملف بحسب الموضع. ومع ذلك فقراءة الملف بحسب اسم الرأس أكثر أمانًا.

لا يظهر المنتقي لـ JSON. يتضمن تصدير JSON دائمًا الحقل handled_at، وقيمته null ما دام الإرسال مفتوحًا. التصدير الموضوع في الطابور نسخة لحظية، لذا لا تتغير الملفات التي نزّلتها قبل v1.29.0، ويعكس أي تصدير جديد الحالة وقت وضعه في الطابور.

ما تعرضه واجهة API

في واجهة API للإدارة، يتضمن الإرسال الذي تمت معالجته الحقل handled_at بصيغة الختم الزمني نفسها. أما الإرسال المفتوح فيُحذف منه المفتاح كليًا، كما يُحذف read_at أصلًا ما دام الإرسال غير مقروء. وهذا يختلف عن تصدير JSON الذي يُبقي المفتاح ويضع قيمته null، ولذلك ينبغي لمن يتعامل مع الاثنين أن يعدّ غياب المفتاح وقيمة null أمرًا واحدًا.

في القائمة، يعيد handled=true الإرسالات التي لها وقت معالجة فقط، ويعيد handled=false المفتوحة فقط. وإذا تركت المعامل فستحصل على الاثنين. ويمكن دمجه مع مرشّحَي is_spam وunread الموجودين ومع البحث q.

أين يفتقر إلى الدقة

• هو وقت لا سجلّ. يُصدَّر آخر وقت معالجة فقط، فلا يمكنك أن ترى أن إرسالًا أُعيد فتحه.

• لا يذكر أحدًا بالاسم. لا تستخدم العمود للمقارنة بين الأعضاء.

• «تمت المعالجة» تعني أنه جرى التعامل مع الإرسال، ولا تعني بالضرورة أنه رُدّ عليه. يمكن معالجة إرسال دون أن يكتب أحد إلى المُرسِل.

• ليس مقياسًا لزمن الاستجابة بمفرده. يمكنك حساب الفارق بين وقت الاستلام ووقت المعالجة، لكنه يشمل كل سبب أبقى الإرسال مفتوحًا، وإعادة الفتح تعيد ضبطه.

• لا يعيد كتابة أي شيء صُدِّر مسبقًا.

يشرح هذا المقال الإصدار. يبقى إدخال «سجل التغييرات» الخاص بـ v1.29.0 هو السجل الرسمي لما صدر.