> ## 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 schema。

#### 字段

| 字段 | 类型 | 含义 | 来源 |
| - | - | - | - |
| `_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.