ربط قارئ ZKTeco بتطبيق Flutter عبر Python Agent محلي، وتشخيص تهيئة pythonnet وفصل مصادقة الجهاز عن واجهة الحضور.
localhost يتبع الجهاز الذي ينفذ الطلب
عنوان localhost في Flutter على الهاتف يشير إلى الهاتف، لا حاسوب قارئ USB. صمم مكان تشغيل الواجهة والوكيل بوضوح؛ إذا تغير الجهاز أو استُعمل محاكي فإن عنوان الاتصال والصلاحيات تختلف. نجاح طلب status لا يثبت توافق جميع قارئات ZKTeco؛ يلزم SDK وتعريفات ونظام تشغيل وبنية معالج تلائم الطراز المحدد.
تهيئة runtime وحماية دورة المسح
pythonnet.load يسبق import clr عند اختيار runtime صراحة، لكن netfx ليس خيارًا عامًا لكل الأنظمة. وثق runtime ونسخة Python وSDK التي اختبرتها. اربط كل مسح بمعرف عملية وصلاحية قصيرة لمنع تكرار الحضور، وأوقف polling عند إغلاق الشاشة. لا تعرض API الشبكة للعامة ولا تضع قوالب البصمة في سجلات التشخيص. نجاح المطابقة يجب أن يمر بصلاحيات الخادم قبل اعتماد إجراء مالي.
خطوات التطبيق والشرح
حل مشكلة ربط جهاز البصمة ZKTeco مع Flutter بدون مكتبة جاهزة
واحدة من المشاكل الحقيقية اللي ممكن تقف قدام أي Flutter Developer هي التعامل مع Hardware مباشر — خصوصًا أجهزة زي قارئ البصمة. في المقال ده هحكيلك تجربة عملية في حل مشكلة ربط جهاز بصمة ZKTeco ZK8500R مع تطبيق Flutter POS، بدون أي مكتبة جاهزة.
المشكلة
كان المطلوب في نظام POS مبني بـ Flutter إن الموظفين يسجلوا حضور وانصراف باستخدام البصمة، مش بكلمة سر ولا PIN. لكن أول challenge ظهر كان:
- لم تتوفر في بيئة هذه التجربة حزمة مناسبة لهذا القارئ
- Flutter مش مصمم للتعامل المباشر مع Hardware
- pub.dev مفيهوش أي حلول مناسبة
وده كان معناه إن الحل التقليدي مش موجود.
الفكرة الأساسية للحل
بدل ما ننتظر مكتبة تظهر، تم بناء حل كامل من الصفر باستخدام فكرة بسيطة:
Flutter ↔ REST API ↔ Python Agent ↔ Fingerprint Device
يعني بدل ما Flutter يتكلم مع الجهاز مباشرة، يتكلم مع API محلي.
⚙️ المعمارية (Architecture)
تم بناء Python Agent بيشتغل محليًا على الجهاز، وبيعمل:
- التواصل مع جهاز ZKTeco باستخدام pyzkfp
- تشغيل REST API على port 9201
- إدارة قراءة ومطابقة البصمات
API Endpoints
/connect
→ فتح الاتصال بالجهاز وتشغيل background polling
/load_templates
→ تحميل بصمات الموظفين من Firebase إلى الذاكرة
/status
→ معرفة هل في بصمة حالياً (Polling كل 500ms)
/identify
→ مطابقة البصمة مع المستخدمين وإرجاع user_id
/clear_pending
→ مسح البصمة السابقة قبل أي scan جديد
التكامل مع Flutter
تم استخدام مكتبة Dio لإرسال HTTP Requests:
final response = await dio.get('http://localhost:9201/status');
Flutter بيتعامل مع الـ agent كأنه backend عادي جدًا.
Flow النظام
1. تسجيل الحضور (Check-in)
- الموظف يسجل بصمته
- الأدمن يوافق ببصمته
- يتم تسجيل العملية في Firestore
2. تسجيل الانصراف (Check-out)
- نفس الفلو السابق
3. العمليات المالية
- أي تعديل مالي يحتاج بصمة الأدمن
UI Component
تم بناء Widget موحد:
FingerprintDialog
ويحتوي على حالات:
- Waiting
- Scanning
- Success
- Failed
مع دعم:
- Animations
- Auto Retry
- Reusable في أكثر من مكان
المشكلة التقنية الأصعب
أثناء استخدام pyzkfp ظهر الخطأ:
RuntimeError: Initialize clr before importing
السبب كان إن pythonnet 3.x غيّر طريقة التهيئة.
الحل
إضافة سطر واحد قبل import clr:
import pythonnet
pythonnet.load('netfx')
import clr
سطر واحد حل مشكلة debugging استمرت لساعات.
النتيجة
- النظام شغال في بيئة production
- تسجيل حضور وانصراف بالبصمة بدون Keyboard
- تكامل كامل بين Flutter + Python + Hardware
المميزات
- حل قابل للتوسعة لأي جهاز Hardware
- فصل واضح بين Flutter و Hardware Layer
- سهولة الصيانة والتطوير
العيوب
- الحاجة لتشغيل Agent محلي
- تعقيد أعلى في البداية
- إدارة Deployment للـ Python service
الخلاصة
عدم وجود مكتبة مش نهاية الطريق. أحيانًا ده معناه إنك تبني حل أفضل — ويمكن كمان يكون أساس لمنتج أو مكتبة يستخدمها غيرك.
مصادر مفيدة
مزيد من المقالات من موقعنا : كيف تجعل واجهات تطبيقاتك في Flutter متجاوبة مع جميع الشاشات باستخدام MediaQuery و GridView
مزيد من المقالات : مراقبة حالة الاتصال بالإنترنت باستخدام Flutter وDart
مرجع للتنفيذ
راجع التوثيق الخاص بهذا الموضوع وطابق إعداداته مع إصدار أدوات مشروعك. اختبر السلوك المستهدف وحالة الفشل قبل إدماج المثال في تطبيق منشور.






