خطة ربط أجهزة البصمة — Moon ERP HR

تاريخ: 2026-04-09 | الحالة: مطلوب تنفيذ Backend + Frontend

1. المخطط العام (Flow)

أجهزة البصمة
ZKTeco × N → برنامج الفيرم وير
(يسحب من الأجهزة) → POST /api/hr/attendance/biometric → Moon ERP Backend
(يسجل الحضور) → HR Attendance
(الفرونت إند)

2. الـ API المطلوبة من الباك إند Backend — أحمد

2.1 Endpoint رئيسي: استقبال بيانات البصمة

POST /api/hr/attendance/biometric

Headers:
  X-API-Key: {مفتاح أمان يتحدد في .env}
  Content-Type: application/json

Body:
{
  "device": {
    "name": "ZK-Main-Entrance",    // اسم الجهاز
    "ip": "192.168.1.50",          // IP الجهاز (اختياري)
    "port": 4370                   // Port (اختياري)
  },
  "records": [
    {
      "user_id": "1",              // رقم الموظف في جهاز البصمة (string)
      "user_name": "Ahmed Mohamed", // اسم الموظف (اختياري — للمرجع)
      "timestamp": "2026-04-09 08:05:00",  // التاريخ والوقت
      "status": 0,                 // 0 = حضور، 1 = انصراف
      "punch": 0                   // نفس status (بعض الأجهزة)
    }
  ]
}

Response:
{
  "success": true,
  "processed": 5,
  "check_ins": 3,
  "check_outs": 2,
  "skipped": 0,
  "errors": [
    { "user_id": "999", "error": "Employee not found" }
  ]
}

2.2 المنطق المطلوب (Business Logic)

لكل record في الـ request:

ابحث عن الموظف بـ biometric_id = user_id (من جدول الـ mapping)
لو مش لاقيه → جرب بـ employee_number = user_id
لو مش لاقيه → سجل في errors وكمّل
لو status == 0 (حضور):
- لو مفيش attendance record للموظف في التاريخ ده → أعمل check-in جديد
- لو فيه record وعنده check_in بالفعل → skip (مكرر)
- سجل check_in_source = 'biometric'
لو status == 1 (انصراف):
- لو فيه attendance record مفتوح (check_in موجود، check_out فاضي) → أعمل check-out
- لو مفيش record مفتوح → skip
- سجل check_out_source = 'biometric'
- احسب worked_hours, overtime_hours, late_minutes
Duplicate detection: نفس employee_id + date + check_in time مش يتكرر
سجل اسم الجهاز في ملاحظات أو حقل device_name

2.3 جداول قاعدة البيانات المطلوبة

جدول 1: `biometric_devices` — أجهزة البصمة

العمود	النوع	الشرح
id	bigint PK	المعرف
name	varchar(100)	اسم الجهاز (ZK-Main-Entrance)
ip_address	varchar(45)	IP الجهاز
port	int	Port (default 4370)
location	varchar(255)	موقع الجهاز (المدخل الرئيسي)
branch_id	FK → branches	الفرع
is_active	boolean	فعّال/معطل
last_sync_at	timestamp	آخر مزامنة
company_id	FK	الشركة (multi-tenant)
created_at / updated_at	timestamps

جدول 2: `biometric_employee_mappings` — ربط رقم البصمة بالموظف

العمود	النوع	الشرح
id	bigint PK	المعرف
employee_id	FK → employees	الموظف في HR
biometric_id	varchar(50)	رقم الموظف في جهاز البصمة
device_id	FK → biometric_devices (nullable)	الجهاز (لو مخصص لجهاز معين)
company_id	FK
created_at / updated_at	timestamps

Unique constraint: (biometric_id, company_id) — نفس الرقم مش يتكرر في نفس الشركة

جدول 3: `biometric_sync_logs` — سجل المزامنات

العمود	النوع	الشرح
id	bigint PK
device_name	varchar(100)	اسم الجهاز اللي بعت
records_received	int	عدد السجلات المستلمة
check_ins	int	عدد تسجيلات الحضور
check_outs	int	عدد تسجيلات الانصراف
skipped	int	عدد المتخطاة (مكررة)
errors	json	تفاصيل الأخطاء
synced_at	timestamp	وقت المزامنة
company_id	FK

تعديل جدول `attendances` الحالي:

العمود الجديد	النوع	الشرح
check_in_source	enum('manual','web','biometric','bulk')	مصدر تسجيل الحضور
check_out_source	enum('manual','web','biometric','bulk')	مصدر تسجيل الانصراف
device_name	varchar(100) nullable	اسم جهاز البصمة

2.4 APIs إضافية مطلوبة

Method	Endpoint	الوظيفة
GET	/api/hr/biometric-devices	قائمة أجهزة البصمة
POST	/api/hr/biometric-devices	تسجيل جهاز جديد
PUT	/api/hr/biometric-devices/{id}	تعديل جهاز
DELETE	/api/hr/biometric-devices/{id}	حذف جهاز
GET	/api/hr/biometric-mappings	قائمة ربط الموظفين بأرقام البصمة
POST	/api/hr/biometric-mappings	ربط موظف برقم بصمة
PUT	/api/hr/biometric-mappings/{id}	تعديل الربط
DELETE	/api/hr/biometric-mappings/{id}	حذف الربط
POST	/api/hr/biometric-mappings/bulk	ربط مجموعة موظفين دفعة واحدة
GET	/api/hr/biometric-sync-logs	سجل المزامنات
POST	/api/hr/attendance/biometric	استقبال بيانات البصمة (الـ webhook)

3. الفرونت إند Frontend

3.1 شاشة إدارة أجهزة البصمة

Route: /hr/biometric-devices

جدول بأجهزة البصمة (اسم، IP، موقع، فرع، حالة، آخر مزامنة)
إضافة/تعديل/حذف جهاز
عرض حالة الاتصال (آخر مزامنة)

3.2 شاشة ربط الموظفين بأرقام البصمة

Route: /hr/biometric-mappings

جدول: اسم الموظف | رقم الموظف (ERP) | رقم البصمة | الجهاز
ربط يدوي: اختار موظف + أدخل رقم البصمة
ربط جماعي: لو أرقام البصمة = أرقام الموظفين → زر "ربط تلقائي"

3.3 تحسين شاشة الحضور

عمود جديد في الجدول: "المصدر" (يدوي / بصمة / ويب)
أيقونة بجانب كل record تبين المصدر (🖐️ = بصمة، 💻 = ويب، ✏️ = يدوي)
فلتر بالمصدر

3.4 شاشة سجل المزامنات

Route: /hr/biometric-logs

جدول: التاريخ | الجهاز | مستلم | حضور | انصراف | متخطى | أخطاء
تفاصيل الأخطاء (موظف مش موجود، مكرر، إلخ)

4. إعدادات الفيرم وير

اللي هيتحط في الفيرم وير:

Push URL: https://moon-erp.elbaset.com/api/hr/attendance/biometric
API Key:  {المفتاح اللي أحمد هيحدده في .env}
Method:   POST
Headers:  X-API-Key: {key}, Content-Type: application/json
Format:   نفس الـ format اللي فوق بالظبط

5. الأمان

API Key — الـ endpoint يقبل بس requests اللي فيها X-API-Key صحيح
Rate Limiting — حد أقصى 10 requests/minute لكل API key
IP Whitelist (اختياري) — يقبل بس من IPs معينة
HTTPS فقط — مفيش HTTP
Logging — كل request يتسجل في biometric_sync_logs

6. خطة التنفيذ

#	المهمة	المسؤول	الأولوية
1	جداول DB + Migration (devices, mappings, sync_logs, attendance columns)	أحمد	عاجل
2	`POST /attendance/biometric` — الـ webhook الرئيسي	أحمد	عاجل
3	CRUD APIs لأجهزة البصمة والـ mappings	أحمد	عالي
4	شاشة أجهزة البصمة + Mappings في الفرونت	حازم	عالي
5	تحديث شاشة الحضور (عمود المصدر)	حازم	متوسط
6	شاشة سجل المزامنات	حازم	متوسط
7	ربط الفيرم وير بالـ endpoint	مشترك	عالي
8	اختبار شامل مع أجهزة حقيقية	مشترك	عالي

7. Task #1483 — التاسك اللي اتبعتت لأحمد

التاسك موجودة على Support Platform — Task #1483

المطلوب تحديثها بالتفاصيل الكاملة من هذا المستند.