> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# مجموعة الإشعارات (Notifications)

`notifications` تحفظ الإشعارات التي تظهر أعلى لوحة مشاريع المستخدم. كل مستند هو إشعار واحد لمستخدم واحد، ويُعرَّف بقيمة `key`. خدمة `notifications` وحدها تتعامل مع المجموعة (`services/notifications/app/js/Notifications.js`)؛ أما `web` و`third-party-datastore` فيستدعيان واجهة HTTP الخاصة بها. لا يوجد مخطط Mongoose.

#### الحقول

| الحقل | النوع | المعنى | المصدر |
| - | - | - | - |
| `_id` | ObjectId | معرّف الإشعار. يعلّم `web` الإشعار كمقروء بهذا المعرّف. | `Notifications.js:58-65` |
| `user_id` | ObjectId | المستخدم الذي يرى الإشعار. | `Notifications.js:26` |
| `key` | String | يعرّف الإشعار، مثل `project-invite-<inviteId>`. تُبقي عملية upsert مستندًا واحدًا لكل `user_id` و`key`؛ ولا يوجد فهرس فريد. | `Notifications.js:27`, `:51-55` |
| `templateKey` | String | الإشعار الذي تعرضه الواجهة الأمامية. يُزال عند قراءة الإشعار أو تجاهله؛ ويبقى المستند. | `Notifications.js:29`, `:63`, `:72`, `:78` |
| `messageOpts` | Object | قيم نص الإشعار، بحسب `templateKey` (لدعوة مشروع: `userName` و`projectName` و`projectId` و`token`). يُزال عندما يتجاهل المستخدم الإشعار بمعرّفه. | `Notifications.js:28`, `:63` |
| `expires` | Date | اختياري. يحذف فهرس TTL المستند بعد هذا الوقت. | `Notifications.js:35-50` |

#### من يكتب فيها

| الشيفرة | ما الذي تفعله |
| - | - |
| `Notifications.js:20-56` (`addNotification`) | `POST /user/:user_id` (`services/notifications/app.ts:29`). تُجري upsert حسب `user_id` + `key`. إذا كان هناك مستند بهذا المفتاح، فلا يُكتب مجددًا إلا عندما يرسل المستدعي `forceCreate`. |
| `Notifications.js:58-65` (`removeNotificationId`) | `DELETE /user/:user_id/notification/:notification_id` (`app.ts:31-34`): تزيل `templateKey` و`messageOpts`. |
| `Notifications.js:67-80` | `DELETE /user/:user_id` و `DELETE /key/:key` (`app.ts:35-36`): تزيلان `templateKey` حسب المفتاح. |
| `Notifications.js:87-100` | `DELETE /key/:key/bulk` (`app.ts:38-41`) تحذف الإشعارات غير المقروءة ذات المفتاح؛ وتحذف `deleteNotificationByKeyOnly` مستندًا واحدًا حسب المفتاح. |
| `services/web/app/src/Features/Notifications/NotificationsHandler.mjs:33-66` | جانب `web` من `addNotification`. يرسل `forceCreate: true` ما لم يمرّر المستدعي `false`. |
| `services/third-party-datastore/app/js/QueueWorker.mjs:46-58` | مزامنة Dropbox لدينا: عندما تفصل حساب Dropbox، ترسل إشعار `dropbox-unlinked` مباشرةً. |

الإشعارات التي ينشئها CE ووحداتنا:

| `key` | `templateKey` | موضع الإنشاء |
| - | - | - |
| `project-invite-<inviteId>` | `notification_project_invite`, تنتهي صلاحيته مع الدعوة | `services/web/app/src/Features/Collaborators/CollaboratorsInviteHandler.mjs:40-42`, يُبنى في `services/web/app/src/Features/Notifications/NotificationsBuilder.mjs:100-122`. فقط عندما يكون البريد المدعو تابعًا لمستخدم موجود. |
| `tpdsFileLimit-<userId>` | `notification_tpds_file_limit` | `services/web/app/src/Features/ThirdPartyDataStore/TpdsController.mjs:118-124` (تحديث من Dropbox سيتجاوز بالمشروع حد عدد الملفات), `NotificationsBuilder.mjs:175-195` |
| `dropboxDuplicateProjectNames-<userId>` | `notification_dropbox_duplicate_project_names` | `services/web/app/src/Features/ThirdPartyDataStore/TpdsUpdateHandler.mjs:160-169`, `NotificationsBuilder.mjs:10-30` |
| `dropbox-unlinked` | `dropbox_unlinked_because_access_denied`, `dropbox_unlinked_because_full` أو `dropbox_unlinked_because_suspended` | `services/third-party-datastore/app/js/QueueWorker.mjs:20-25`, `:46-58` (مزامنة Dropbox لدينا) |

يبني `NotificationsBuilder.mjs` أيضًا مفاتيح لدعوات المجموعات وانتماءات المؤسسات والاشتراكات ومشاريع التصحيح القديمة. توجد مستدعياتها في شيفرة الاشتراكات والمؤسسات، ولا يعمل فحص مشاريع التصحيح القديمة إلا عند `isSaas` (`services/web/app/src/Features/Project/ProjectListController.mjs:234-236`).

#### من يقرأ منها

| الشيفرة | ما الذي تفعله |
| - | - |
| `Notifications.js:4-10` (`getUserNotifications`) | `GET /user/:user_id` (`app.ts:30`). تُعيد فقط مستندات المستخدم التي ما زال فيها `templateKey`. |
| `services/web/app/src/Features/Project/ProjectListController.mjs:367` | تحمّل الإشعارات للوحة المشاريع. |
| `services/web/app/src/Features/Notifications/NotificationsController.mjs` | `GET /notifications`, `DELETE /notifications/:notificationId` و `GET /user/notification/:notificationId` (`services/web/app/src/router.mjs:922-937`). |
| `services/web/modules/dropbox/app/src/DropboxHandler.mjs:128-131` | وحدة Dropbox لدينا: عندما يربط المستخدم Dropbox مجددًا، تعلّم `dropbox-unlinked` و`dropboxDuplicateProjectNames-<userId>` كمقروءين. |

#### الفهارس

| الاسم | المفاتيح | الخيارات | الترحيل |
| - | - | - | - |
| `expires_1` | `{ expires: 1 }` | TTL, `expireAfterSeconds: 10` | `tools/migrations/20190912145014_create_notifications_indexes.mjs` |
| `key_1` | `{ key: 1 }` | | نفسه |
| `user_id_1` | `{ user_id: 1 }` | | نفسه |

#### ملاحظات

* الإشعار المقروء لا يُحذف: يختفي `templateKey` فقط. ولأن المستند ما زال يحتفظ بالمفتاح، فإن استدعاء `addNotification` لاحقًا للمفتاح نفسه دون `forceCreate` لا يفعل شيئًا (`Notifications.js:21-24`).
* تعمل مسارات `/key/:key` على المفتاح وحده، عبر جميع المستخدمين (`Notifications.js:76-100`).
* إذا لم يكن لدى `web` القيمة `apis.notifications.url`، فإنه لا ينشئ إشعارات ولا يقرؤها (`NotificationsHandler.mjs:17`، `:41`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.