> ## 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 API。沒有 Mongoose 結構描述。

#### 欄位

| 欄位 | 型別 | 意義 | 來源 |
| - | - | - | - |
| `_id` | ObjectId | 通知 id。`web` 透過此 id 將通知標示為已讀。 | `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`）。使用者依 id 關閉通知時移除。 | `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`). 依 `user_id` + `key` 執行 upsert。如果該 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`): 依 key 移除 `templateKey`。 |
| `Notifications.js:87-100` | `DELETE /key/:key/bulk` (`app.ts:38-41`) 刪除帶有某個 key 的未讀通知；`deleteNotificationByKeyOnly` 依 key 刪除一份文件。 |
| `services/web/app/src/Features/Notifications/NotificationsHandler.mjs:33-66` | `addNotification` 的 `web` 端。除非呼叫端傳入 `false`，否則送出 `forceCreate: true`。 |
| `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` 也為群組邀請、機構隸屬、訂閱和舊除錯專案建構 key。它們的呼叫端位於訂閱和機構相關程式碼中，而舊除錯專案檢查只在 `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`。由於文件仍保留 key，之後對同一 key 不帶 `forceCreate` 的 `addNotification` 不會產生任何效果（`Notifications.js:21-24`）。
* `/key/: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.