انتقل إلى المحتوى

API — الموظفون والمهارات والشهادات

الغرض

الوصول للقراءة إلى ملفات الموظفين، وسطح المهارات الإنتاجي، والشهادات، ومجموعات الموظفين، وخط أنابيب الاستيراد المجمع عبر Excel الذي هو مسار الكتابة الوحيد للأشخاص والمهارات.

المصادقة والأدوار

Area Base Reads / writes
Employees /api/employees employee.view (read-only)
Skills (production) /api/skills skill.view / skill.edit
Certifications /api/employees/{id}/certifications certifications.read / certifications.manage
Employee groups /api/employee-groups employee_group.read / employee_group.write
Imports /api/imports imports.run

نقاط النهاية

Employees — /api/employees · employee.view · GET فقط

Method Path Purpose
GET /api/employees سرد الموظفين
GET /api/employees/my سجل الموظف الخاص بالمُستدعي
GET /api/employees/{id} تفصيل الموظف

Skills (production) — /api/skills

Method Path Purpose Gate
GET /api/skills سرد المهارات skill.view
GET /api/skills/{id}/employees الموظفون الحاملون لمهارة skill.view
GET / POST / DELETE /api/skills/{id}/certification-requirements … إدارة متطلبات الشهادة skill.view / skill.edit
PUT /api/skills/{id}/requires-certification تبديل اشتراط الشهادة skill.edit

Certifications

Method Path Purpose Gate
GET /api/certifications/expiring الشهادات المنتهية قريبًا certifications.read
GET /api/employees/me/certifications الشهادات الخاصة [Authorize]
GET / POST /api/employees/{id}/certifications سرد / إضافة شهادة manage
PUT /api/employees/{id}/certifications/{certId} (+ /status) تحديث شهادة / حالتها certifications.manage

Employee groups — /api/employee-groups · قراءة employee_group.read، كتابة employee_group.write: CRUD كامل إضافةً إلى GET/POST/DELETE …/{id}/members[/{employeeId}] للعضوية.

Imports — /api/imports · imports.run (SYS_ADMIN + HR_ADMIN + PLANNER)

Method Path Purpose
POST /api/imports/employees رفع .xlsx ← مهمة استيراد غير متزامنة
GET /api/imports/template · /export-current تنزيل قالب فارغ / البيانات الحالية
GET /api/imports/jobs · /jobs/{id} سرد / تفصيل المهام
GET /api/imports/jobs/{id}/error-report تنزيل ملف أخطاء كل صف بصيغة .xlsx
DELETE /api/imports/jobs/{id} إلغاء مهمة (SuperAdmin + imports.view_history)

الأشكال والأخطاء

يُتحقَّق من رفع الاستيراد تزامنيًا (≤10 MB، .xlsx، المخطط) ثم يُشغَّل كـ مهمة Hangfire أطلِقها-وانسَها (انظر المهام الخلفية)؛ والملف في الذاكرة فقط، ومُجزَّأ بـ SHA-256. ProblemDetails القياسي؛ وملف مكرر خلال 24 ساعة يُرجع 201 مع warning، لا حظرًا.

المزالق

  • الموظفون والمهارات عبر الاستيراد فقط / للقراءة فقط عبر الـ API. لا توجد نقطة نهاية إنشاء/تحرير موظف (Employees هي GET فقط) — يدخل الأشخاص عبر استيراد Excel أو البذرة (الورقة 03). أما CRUD كتالوج المهارات فهو السطح الإداري (/api/admin/skills)، لا هذه المسارات الإنتاجية.
  • /api/skills (إنتاج) يتعايش مع /api/admin/skills (admin CRUD) — نمط التعايش.
  • لا مسح تلقائي لانتهاء صلاحية الشهادات — "المنتهية قريبًا" تُحسب عند القراءة؛ ولا توجد مهمة مجدولة (الورقة 04؛ انظر التشخيصات للإطلاق اليدوي).
  • إلغاء الاستيراد يحتاج SuperAdmin + imports.view_history، ويلغي تعاونيًا بين الصفوف.

ذات صلة