المعمارية¶

المستودع monorepo: تطبيق صفحة واحدة React 19 + Vite + TypeScript وواجهة Express تجمع خلاصات ثغرات عامة. لا يتصل SPA بـ NVD أو OSV مباشرة؛ كل حركة صادرة عبر الخادم لمركزة المفاتيح والتخزين المؤقت وحدود المعدل.

يربط هذا الفصل المجلدات بالمسؤوليات، يصف مسار الفحص والمراقبة عبر المعالجات، ويوجّه المكاملين إلى OpenAPI المقدّم وقت التشغيل.

طوبولوجيا عالية المستوى¶

flowchart LR
  classDef ui fill:#e9edf5,stroke:#00baba,color:#253343
  classDef api fill:#f3fcfc,stroke:#008c8c,color:#253343
  classDef ext fill:#fff7ed,stroke:#eda232,color:#253343

  Browser[SPA المتصفح]:::ui --> API[Express /api]:::api
  API --> NVD[NVD]:::ext
  API --> OSV[OSV]:::ext
  API --> GH[GitHub]:::ext
  API --> CISA[CISA KEV]:::ext
  API --> RSS[RSS]:::ext

شرح المخطط¶

يحفظ المتصفح المكدس واللغة وتبديلات المصادر في localStorage، ثم يستدعي POST /api/scan أو POST /api/watch. طبقة API تتحقق من JSON وتستدعي scanStack في server/services/scan.ts وتعيد الثغرات المدمجة. منطق المزوّد تحت server/services/؛ الإزالة المكررة في server/lib/merge.ts؛ إثراء الترجمة في server/services/enrich.ts.

مسار الطلب (فحص كامل)¶

server/routes/scan.ts يستقبل POST /scan.
server/handlers/scanHandlers.ts يحلّل الجسم عبر stackValidation.ts.
scanStack يحدّد المصادر المدمجة وRSS المخصصة المفعّلة.
تكتمل الجلبات المتوازية لكل أداة؛ تُدمج النتائج وترتّب.
يعمل enrichVulnsWithTranslations عند translate: true.
يعود JSON من نوع ScanResponse؛ يكتب persistLastScan في src/lib/scanCache.ts قيمة cve-radar:last-scan بمفتاح مكدس.

طبقة قاعدة البيانات (PostgreSQL اختياري)¶

عند تعيين DATABASE_URL، تُخزَّن بيانات وصفية للمسح في PostgreSQL عبر server/db/scanHistory.ts ومكدسات المستأجر عبر server/db/tenants.ts. ترحيلات SQL في server/db/migrations/*.sql وتُنفَّذ تلقائياً عند بدء pool.

تعريفات schema type-safe للترحيل التدريجي لـ ORM في server/db/schema.ts (Drizzle ORM). يعرّض server/db/drizzle.ts دالة getDb() مدعومة بـ pool مشترك pg. يستخدم persistence الخاص بـ tenant وscan-history (server/db/tenants.ts، server/db/scanHistory.ts) مُنشئات استعلام Drizzle؛ تُشغَّل migrations SQL في server/db/migrations/*.sql عند بدء pool.

خدمات الإشعارات¶

تستخدم تنبيهات المراقبة على الخادم server/services/notifications/NotificationService.ts. محولات القنوات (Slack، Discord، Telegram، SMTP، webhook عام) تقرأ متغيرات env الموثّقة في الإعداد. يفوّض server/services/alerts.ts إلى الخدمة للتوافق مع ALERT_WEBHOOK_URL.

طبقة العقد المشتركة¶

تعيش الأنواع وترتيب الخطورة في shared/ (shared/api/vulnerability.ts، shared/constants/severityOrder.ts). يستورد src/ وserver/ عبر @shared/*؛ يُعيد server/types.ts التصدير للتوافق العكسي. يُجمّع npm run build:server مجلد shared/ في dist-server/.

تخطيط طبقة API¶

الوحدة	الدور
`server/index.ts`	تطبيق Express، تركيب المسارات
`server/routes/health.ts`	`GET /health`
`server/routes/meta.ts`	`capabilities`، `sources`، `openapi.json`
`server/routes/scan.ts`	`scan`، `watch`، `scan/validate`
`server/routes/v1.ts`	نفس المعالجات تحت `/api/v1`
`server/routes/translateLocale.ts`	`POST /translate`
`server/handlers/scanHandlers.ts`	منطق فحص/مراقبة/تحقق مشترك
`server/openapi/spec.json`	عقد OpenAPI 3.1

تبقى المسارات القديمة تحت /api/*؛ يُفضّل للتكامل /api/v1/* (راجع مرجع API).

خريطة الواجهة الأمامية¶

المنطقة	المسار
الهيكل	`src/components/layout/AppShell.tsx`، `SubNav.tsx`، `SetupWizard.tsx`
التبويبات	`src/components/tabs/*`
ذاكرة مسح	`src/lib/scanCache.ts`
عميل API	`src/api/scan.ts`، `watch.ts`، `scanPayload.ts`
i18n	`src/i18n/messages/*.ts`
خطافات	`useVulnScan`، `useWatch`، `useVulnTranslations`، `useFontScale`
Middleware	`server/middleware/rateLimit.ts`، `scanTimeout.ts`

خدمات الخادم (الخلاصات)¶

المزوّد	الوحدة
NVD	`server/services/nvd.ts`
OSV	`server/services/osv.ts`
GitHub	`server/services/github.ts`
CISA KEV	`server/services/cisa.ts`
RSS	`server/services/rss.ts`
الترجمة	`server/services/translate.ts`

التخزين المؤقت والحدود¶

ذاكرة مؤقتة في العملية (server/lib/cache.ts) لـ XML لـ RSS وسلاسل الترجمة. تأخير NVD من server/lib/rateLimit.ts (تنسيق upstream). حدود معدل الطلبات للفحص/المراقبة في server/middleware/rateLimit.ts (سطلان منفصلان؛ validate معفى). تبقى نتائج الفحص على العميل في localStorage عبر scanCache.ts. القدرات في GET /api/capabilities تعكس حدود التحقق (50 أداة، 20 خلاصة مخصصة).

التالي: التنبيهات