دمج قارئات RFID مع خريطة داخلية: دليل عملي خطوة بخطوة

تعمل تقنية RFID منذ سنوات بجدّ في المتاجر والمستودعات، ومع ذلك ما زالت معظم الفرق تقرؤها سجلَّ أحداث يتدفق بلا توقف أو شبكةً من العدّادات. لا هذا ولا ذاك يخبرك أي بوابة على رصيف التحميل صمتت، أو ما إذا كانت قارئات السلالم المتحركة في الطابق الثاني تلتقط أي شيء أصلًا. يضع هذا الدليل كل قارئ على المخطط بدلًا من ذلك، ويتّبع منشأة تجريبية حقيقية في Spatial Map، فكل لقطة شاشة أدناه يمكنك إعادة إنتاجها.

المثال هو Retail Mart Store، متجر من ثلاثة طوابق (Ground وLevel 1 وLevel 2) في مساحة العمل التجريبية Production Corp. يضم 85 قارئًا ثابتًا: 66 على الأبواب والبوابات بين الأقسام، و9 عند أبواب المصاعد، و9 عند طرفي السلالم المتحركة، وواحدًا على الدرج. كل قارئ علامة على الخريطة تحمل اسمه، مثل «RFID-G-02 · Office ↔ Receiving / Loading Docks». ويحتفظ جدول واحد، Retail Mart · RFID Reader Reads، بصف واحد لكل قارئ.

Retail Mart Store في المحرر — علامات القارئات عند البوابات والمصاعد والسلالم المتحركة

ترسل قارئات UHF الثابتة قراءاتها عبر برمجيات وسيطة طرفية: إما واجهة LLRP في القارئ نفسه، أو حزمة SDK من الشركة المصنعة تعمل على جهاز صغير بجانبه. هذه البرمجيات بارعة في قراءة الوسوم، لكن لا شيء مفيدًا لديها لتقوله للخريطة. لذلك تضيف قطعة صغيرة بينهما: وسيط ترحيل تملكه أنت. يستمع إلى البرمجيات الوسيطة، ويجمع القراءات لكل قارئ، ويكتب النتيجة كل بضع ثوانٍ في جدول على Spatial Map عبر واجهة الكتابة الخاصة بالجدول. وتقرأ الخريطة والتقرير من هذا الجدول.

لماذا التجميع بدلًا من تمرير كل قراءة؟ ترى البوابة المزدحمة مئات القراءات في الدقيقة، وكثير منها الوسم نفسه التقطه هوائيان. لا تستطيع الخريطة عرض ذلك بشكل مفيد، كما أن واجهة الجداول محدودة لكل مفتاح. صف واحد لكل قارئ — قراءات اليوم والساعة الأخيرة والوسوم الفريدة وأعداد الدخول والخروج وآخر وسم وآخر SKU والحالة — هو بالضبط ما يحتويه جدول العرض التجريبي، وما يريد مشرف الوردية رؤيته. وإن احتجت إلى موقع كل وسم، فالنمط نفسه يعمل بصف لكل وسم عند آخر قارئ رآه؛ راجع تتبّع الأصول داخل المباني في الوقت الفعلي.

1. 1
   أنشئ الجدول

   انتقل إلى Tables → Create new table، وسمِّه (يستخدم العرض التجريبي «Retail Mart · RFID Reader Reads»)، واختر النوع RFID tag. الأعمدة القياسية المقترحة مجرد نقطة بداية: أعد تسميتها أو غيّر نوعها أو احذفها لتطابق ما سيرسله وسيط الترحيل.

2. 2
   صف واحد لكل قارئ

   أضف حقلًا نصيًا `reader_id` مع Required وUnique، ثم `reader_name` و`floor` و`reader_type` و`status`، والعدّادات الصحيحة (`reads_today` و`reads_last_hour` و`unique_tags_today` و`in_count_today` و`out_count_today` و`alerts_today`)، و`last_read_at` بنوع تاريخ ووقت، و`last_tag_epc` و`last_sku` و`last_direction` و`rssi_dbm` و`firmware` و`elevation_m`. تُتحقَّق كل عملية كتابة وفق هذا المخطط.

3. 3
   أنشئ مفتاحًا

   في تبويب API & access للجدول، اكتب اسمًا للمفتاح وانقر Create key. يبدأ المفتاح بـ `sgv_tbl_` ويظهر مرة واحدة فقط، فاحفظه مباشرة في أسرار وسيط الترحيل. المفتاح يكتب في هذا الجدول وحده؛ أعطِ كل وسيط مفتاحه الخاص لتتمكن من إلغاء أحدها دون تعطيل البقية. يمكن لدوري Owner وAdmin إنشاء المفاتيح.

4. 4
   انسخ عنوان URL الأساسي

   يعرض التبويب نفسه النقاط الـ 12 مع أمثلة curl جاهزة للنسخ. في بيئة الإنتاج يكون الأساس `https://app.spatialmap.io/api/v1/public/tables`؛ المفتاح هو ما يحدد الجدول، لذلك لا يوجد معرّف جدول في المسار.

Create new table — اختر النوع ثم شكّل الحقول

وسيط الترحيل بضع عشرات من الأسطر بأي لغة يفضّلها فريقك. اشترك في أحداث القراءة من البرمجيات الوسيطة (تقارير LLRP أو دالة الاستدعاء في SDK)، واحتفظ بعدّاد صغير في الذاكرة لكل قارئ، وأرسل وفق مؤقّت — كل 5 إلى 10 ثوانٍ كافٍ تمامًا — كل القارئات التي تغيّرت في استدعاء مجمّع واحد. استخدم معرّف القارئ بوصفه `entityKey` ليحدّث كل استدعاء الصف الموجود بدلًا من إضافة صف جديد.

curl -X POST https://app.spatialmap.io/api/v1/public/tables/rows/bulk \
  -H "Authorization: Bearer $SPATIALMAP_TABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      {
        "entityKey": "RFID-G-02",
        "payload": {
          "reader_id": "RFID-G-02",
          "reader_name": "RFID-G-02 · Office ↔ Receiving / Loading Docks",
          "floor": "Ground",
          "reader_type": "Gate",
          "status": "Active",
          "reads_today": 590,
          "reads_last_hour": 56,
          "unique_tags_today": 288,
          "in_count_today": 294,
          "out_count_today": 296,
          "last_read_at": "2026-10-08T09:25:12Z",
          "last_tag_epc": "E2801121130DB42AB66C7A7B",
          "last_sku": "SKU-339201 Frozen Peas 1kg",
          "last_direction": "Out",
          "alerts_today": 2,
          "elevation_m": 2.4
        }
      },
      {
        "entityKey": "RFID-L1-15",
        "payload": {
          "reader_id": "RFID-L1-15",
          "reader_name": "RFID-L1-15 · Escalator 2 top · L1",
          "floor": "Level 1",
          "reader_type": "Escalator",
          "status": "Idle",
          "reads_today": 525,
          "reads_last_hour": 29,
          "unique_tags_today": 220,
          "in_count_today": 261,
          "out_count_today": 264,
          "last_read_at": "2026-10-08T09:25:49Z",
          "last_tag_epc": "E280115AC002CF6117A1B75B",
          "last_sku": "SKU-509112 LED TV 55in",
          "last_direction": "Out",
          "alerts_today": 0,
          "elevation_m": 6.067
        }
      }
    ]
  }'

`POST /rows` و`POST /rows/bulk` عمليتا إدراج أو تحديث: تصبح الحمولة المرسلة الحالة الكاملة للصف، لذا أرسل الصف كاملًا دائمًا. ولتغيير حقل واحد — مثل وضع قارئ في حالة Offline عند انقطاع نبضه — استخدم `PATCH`، فهو يدمج التغيير مع الحمولة المخزّنة.

curl -X PATCH https://app.spatialmap.io/api/v1/public/tables/rows/RFID-G-01 \
  -H "Authorization: Bearer $SPATIALMAP_TABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"Offline"}'

• Pull from a REST API — في تبويب API & access للجدول، أدخل عنوان البرمجيات الوسيطة، وفاصلًا زمنيًا (30 ثانية حدًا أدنى في النموذج)، وحقل مفتاح الصف، ومسار JSON إلى العناصر، وأي ترويسات، وربط الحقول، ثم انقر Start polling. تشغّله عملية على الخادم مرة في الدقيقة تقريبًا، حتى لو لم تكن أي خريطة مفتوحة. وتقرأ كل عملية استعلام حتى 1,000 صف من استجابة لا تتجاوز 10 ميغابايت.
• Upload file — للمتاجر التي لا تصدّر سوى عدّادات يومية. أضف ملف CSV أو Excel أو JSON أو GeoJSON من Integrations → Add integration → Upload file، واستخدم Re-import لتصدير اليوم التالي.

خطوات الخريطة والتقرير أدناه لا تتغير أيًّا كانت طريقة وصول البيانات. مرجع الواجهة في Tables، ومثال كامل في Push rows with the table write API.

يحتاج كل قارئ إلى علامة في موقعه الحقيقي: على باب، أو بجانب باب مصعد، أو أعلى السلم المتحرك أو أسفله. ضعها بأداة Marker على الطابق الصحيح، وأعطِ كل علامة الاسم نفسه تمامًا الذي يكتبه وسيط الترحيل في `reader_name`. هذا الاسم هو مفتاح الربط في الخطوة التالية، فانسخه بدلًا من إعادة كتابته. وفي متجر متعدد الطوابق، ابنِ الطوابق والمصاعد والسلالم المتحركة أولًا — يشرح Multi-floor store with escalators and lifts مخطط Retail Mart نفسه.

علامة محددة — اسمها هو ما يطابق عليه رابط البيانات

افتح المنشأة في المحرر وانقر Data links ثم New data link (ويمكن الوصول إليه أيضًا من قائمة Data ← Manage data links). يحمل رابط العرض التجريبي اسم RFID reader activity. هذه إعداداته قسمًا قسمًا:

1. 1
   Data source

   الجدول Retail Mart · RFID Reader Reads.

2. 2
   Display mode

   Pulsing zone activity — حلقة متحركة مع شارة عدّاد عند كل علامة قارئ. تعرض الشارة `reads_last_hour`، المختار حقلًا للتسمية في Connect fields.

3. 3
   Attach to shapes

   استهدف العلامات وطابِق عبر Attribute join: حقل الصف `reader_name` مقابل اسم العلامة.

4. 4
   Floor scope

   From record، مع `floor` حقلًا تُقرأ منه الطابق. يخزّن الجدول نصًا («Ground» و«Level 1» و«Level 2»)، لذلك تُربط كل قيمة بأحد طوابق المنشأة — فلا تنبض قارئات Level 2 إلا في Level 2.

5. 5
   Style rules

   ثلاث قواعد على `status`: Active بالبنفسجي، وIdle بالرمادي، وOffline بالأحمر. تُفحص القواعد من الأعلى إلى الأسفل، وتفوز أول قاعدة مطابقة.

6. 6
   Map tooltip

   تظهر عند التمرير وتعرض معرّف القارئ ونوعه وطابقه وحالته والعدّادات وآخر قراءة وآخر EPC وآخر SKU والاتجاه والإشارة والبرنامج الثابت؛ والنقر يفتح لوحة التفاصيل.

Which floors? — ‏From record أو Specific floors أو All floors

كل خيار مشروح في Source and render mode وStyle and rules.

احفظ الرابط وافتح المنشأة في Preview أو عبر رابط مشاركة. صارت كل علامة قارئ تنبض بعدّاد الساعة الأخيرة، ملوّنة حسب حالتها. عندما يكتب وسيط الترحيل، يُبلغ الخادم الخرائط المفتوحة فتعيد تحميل تلك الطبقة فورًا، مع تحديث كل 30 ثانية شبكةَ أمان. مرّر المؤشر فوق قارئ لترى التلميح، وانقر عليه لترى السجل الكامل وتاريخه.

Retail Mart Store في وضع Preview — القارئات ملوّنة حسب الحالة

ولمن لا يعمل في المحرر، يضم العرض التجريبي أيضًا تقريرًا بخريطة كاملة: Retail Mart · RFID Live Map. قائمة القارئات على اليسار، وخريطة المتجر الحية في الوسط، والأرقام تطفو فوقها: مؤشرات لعدد الصفوف وإجمالي قراءات اليوم وقراءات الساعة الأخيرة والوسوم الفريدة اليوم، ومخطط حلقي By status، ومخطط أعمدة Reads today by floor. وتضيّق المرشحات Floor وStatus وSearch كل شيء دفعة واحدة — اختر Offline لتحصل على قائمة الصيانة الصباحية. راجع Full-map reports.

Retail Mart · RFID Live Map — التقرير بخريطة كاملة

“أرسل إلى الخريطة الحالة لا الأحداث: صف واحد لكل قارئ يتحدّث كل بضع ثوانٍ يقرؤه مشرف الوردية بنظرة واحدة.”

يقترح العرض التجريبي بعض التوسعات الطبيعية. أضف قاعدة تنسيق على `alerts_today` (الحقل «Exit alerts today») لتبرز البوابات التي سُجّلت عليها تنبيهات خروج — فهي تغيّر لونًا على الخريطة وفي التقرير ولا ترسل إشعارًا. اجمع حالة القارئات مع مخزون الرفوف وحساسات سلسلة التبريد على الطوابق نفسها كما في حل متاجر التجزئة، أو ركّز على المخارج والبوابات مع حل مكافحة السرقة. ولتتبّع الأصول المتحركة بدلًا من القارئات الثابتة، اقرأ تتبّع الأصول داخل المباني في الوقت الفعلي.