استيراد بيانات الحضور والانصراف من ماكينة البصمه

الوضع الطبيعي مع ستة فروع هو: سجل "إعدادات ماكينة الحضور" واحد لكل فرع، ونسخة من تطبيق attcron داخل كل فرع. كل نسخة من التطبيق مرتبطة بكود إعدادات واحد فقط، فلا تستطيع نسخة واحدة أن تخدم فرعين.

الاستثناء الوحيد: إذا كانت الماكينات الست تُغذّي برنامجاً أو قاعدة بيانات مركزية واحدة (مثل خادم ZkBioTime واحد لكل الشركة)، فيكفي حينها سجل إعدادات واحد ونسخة واحدة من التطبيق.

خطوات التجهيز

1. تأكد من الترخيص. التكامل الآلي مقيّد بإضافة منفصلة (humanresource-attendance-import-cron) غير ترخيص الرواتب الأساسي. إن لم تظهر شاشة "إعدادات ماكينة الحضور" فراجع مدير حسابك.

2. جهّز أكواد الموظفين. املأ حقل كود آلة الحضور والإنصراف (attendanceMachineCode) على كل موظف — راجع النقطة الأولى في قسم "أمور تخص حالة الفروع المتعددة" أدناه قبل توزيع الأكواد.

3. أنشئ ملف API Credentials في النظام واحتفظ بـ Client ID و Client Secret. يمكن استخدام نفس الملف لكل الفروع، أو ملف لكل فرع إن أردت تتبّعاً أدق.

4. أنشئ سجل إعدادات لكل فرع من: الرواتب ← حضور / إنصراف ← إعدادات ماكينة الحضور. أعطِ كل سجل كوداً يدل على فرعه (مثلاً ATT-JED, ATT-RUH)، وحدد:

   • نوع اتصال الماكينة: ZkBioTime أو SQLSERVER أو ACCESS، ثم املأ التبويبة المقابلة فقط.
   • Cron Expression: الصيغة هنا ستة حقول (الثواني أولاً)، فـ 0 5 * * * * تعني "كل ساعة عند الدقيقة الخامسة". أمثلة crontab.guru ذات الخمسة حقول لن تعمل.
   • لأنواع SQL Server و Access: استخدم زر إضافة الاستعلامات الافتراضية — يملأ الاستعلامين وجدول المطابقة (ثلاثة عشر سطراً) دفعة واحدة. انتبه لاختيار الزر المطابق لنوع الاتصال: زر Zk لنوعَي SQL Server و Access، وزر Zk Bio Time لنوع ZkBioTime.

5. جهّز المهمة المجدولة التي تحوّل البصمات الخام إلى مستند الحضور والانصراف. زر Create Task Schedule ينشئها معبّأة مسبقاً، لكن عدّل استعلام المستند فيها: هو يثبّت دفتر TAB وكود شركة 1.

6. ثبّت attcron داخل كل فرع على جهاز يرى الماكينة (JDK 21 + Apache Tomcat 10 بوضع Automatic)، وأدخل عند أول تشغيل عنوان الخادم و Client ID/Secret وكود سجل الإعدادات الخاص بذلك الفرع. لا يحتاج الفرع إلى IP ثابت — يكفي أن يصل إلى خادم النظام.

7. تحقق من التشغيل من تبويبة الإحصائيات في سجل الإعدادات: اخر وقت اتصال يخبرك إن كان التطبيق حياً، وصندوق الوارد يخبرك إن كانت هناك قراءات متعثرة.

أمور تخص حالة الفروع المتعددة تحديداً

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

• إن كانت الفروع شركات قانونية مختلفة، فستحتاج مهمة مجدولة منفصلة لكل شركة، لأن استعلام تهيئة المستند يحدد الدفتر والشركة بقيم ثابتة. أما إن كانت كلها شركة واحدة فيمكن لكل السجلات الستة أن تشير إلى نفس المهمة.

• بعثر مواعيد الـ cron قليلاً بين الفروع (الدقيقة 5، 10، 15…) بدلاً من أن تصل الدفعات الست في نفس اللحظة.

• يمكنك معرفة مصدر كل بصمة: يُخزَّن مع كل قراءة الجهاز الطرفي (terminalSN) والمنطقة (areaAlias) إن كانا ضمن جدول المطابقة.

• إعادة الجمع آمنة. القراءة المكررة (نفس الإعداد ونفس الموظف ونفس وقت البصمة) تُتجاوَز، فزر Read For Period في التطبيق لا ينتج تكراراً — استخدمه لتعويض فترة توقفت فيها ماكينة أحد الفروع.

إن لم يكن تثبيت تطبيق في كل فرع ممكناً

• ربط مباشر بقاعدة البيانات: إن كانت بيانات الماكينات مجمّعة في SQL Server يستطيع خادم النظام الوصول إليه، يمكن الاستغناء عن التطبيق تماماً واستخدام Linked Server مع مهمة مجدولة تقرأ منه.
• الاستيراد اليدوي: إن كانت الماكينة لا تنتج سوى ملف مُصدَّر، فيُستورَد يدوياً في مستند الحضور والانصراف باستخدام صيغة استيراد تصف أعمدة ذلك الملف.

مراجع

• أجهزة البصمة — سجل إعدادات ماكينة الحضور بالكامل
• تطبيق attcron — التثبيت والتشغيل والأخطاء
• الربط مع ماكينات الحضور — بما فيه الربط المباشر عبر Linked Server
• معادلات الحضور والانصراف — لغة صيغ الاستيراد
• الحضور والانصراف — المستند الذي تستقر فيه البصمات