> ## 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.

# Project Invites 集合

`projectInvites` 儲存專案擁有者從共用對話框寄出的邀請。一份文件對應寄往一個電子郵件地址的一份邀請。邀請被接受或撤銷時，文件會被刪除；邀請過期時，Mongo 也會將其刪除。Schema 位於 `services/web/app/src/models/ProjectInvite.mjs`，由 `services/web/app/src/Features/Collaborators/CollaboratorsInviteHandler.mjs` 寫入。

邀請不會讓任何人成為成員。成員儲存在專案的 `*_refs` 陣列中，見 [Projects 集合](https://ayakaleaf-pro.mintlify.site/zh-TW/dev/data-model/projects-collection.md)。

#### 欄位

| 欄位 | 型別 | 含義 | 來源 |
| - | - | - | - |
| `_id` | ObjectId | 邀請 id。既有使用者的邀請通知使用鍵 `project-invite-<_id>`（`services/web/app/src/Features/Notifications/NotificationsBuilder.mjs:102`）。 | `ProjectInvite.mjs:14` |
| `email` | String | 邀請寄往的地址。為某位使用者撤銷邀請時，會將它與該使用者已確認的電子郵件比對（`CollaboratorsInviteHandler.mjs:103-116`）。共用連結邀請不設定此欄位。 | `ProjectInvite.mjs:16`, `CollaboratorsInviteHandler.mjs:84` |
| `tokenHmac` | String | 邀請連結中權杖的 HMAC-SHA256（金鑰 `overleaf-token-invite`）。明文權杖只出現在郵件與通知中；查詢時會對 URL 中的權杖做雜湊，再與此欄位比對。 | `ProjectInvite.mjs:18`, `services/web/app/src/Features/Collaborators/CollaboratorsInviteHelper.mjs:11-15`, `CollaboratorsInviteHandler.mjs:82,256` |
| `encryptedToken` | String | 僅限共用連結邀請：以 `Settings.projectInviteEncryptorOptions` 加密的權杖，讓擁有者能再次查看連結（`services/web/app/src/Features/Collaborators/CollaboratorsInviteController.mjs:606-611`）。 | `ProjectInvite.mjs:17`, `CollaboratorsInviteHelper.mjs:30-47`, `CollaboratorsInviteHandler.mjs:255-258` |
| `sendingUserId` | ObjectId | 寄出邀請的使用者。接受邀請時，它會作為新增新成員的使用者傳遞下去（`CollaboratorsInviteHandler.mjs:199-205`）。共用連結邀請不設定此欄位。 | `ProjectInvite.mjs:19`, `CollaboratorsInviteHandler.mjs:86` |
| `projectId` | ObjectId | 邀請所屬的專案。 | `ProjectInvite.mjs:20`, `CollaboratorsInviteHandler.mjs:87` |
| `privileges` | String or Boolean | 受邀者獲得的權限：`readOnly`、`readAndWrite` 或 `review`（`services/web/app/src/Features/Authorization/PrivilegeLevels.mjs:6-12`）。共用連結邀請也可能為 `false`，表示沒有存取權限。 | `ProjectInvite.mjs:21-25`, `CollaboratorsInviteHandler.mjs:88` |
| `createdAt` | Date | 儲存邀請時由 schema 預設值設定。 | `ProjectInvite.mjs:26` |
| `expires` | Date | Schema 預設值：建立後 30 天。TTL 索引會在此時間之後約 10 秒刪除邀請。共用連結邀請為 `null`，永不過期。 | `ProjectInvite.mjs:6-12,27-31`, `CollaboratorsInviteHandler.mjs:264` |
| `reusable` | Boolean | 郵件邀請為 `false`，接受後即被刪除（`CollaboratorsInviteHandler.mjs:207-220`）。共用連結邀請為 `true`，會一直保留。 | `ProjectInvite.mjs:32`, `CollaboratorsInviteHandler.mjs:89,263` |
| `subscriptionId` | ObjectId | 僅限共用連結邀請：其成員可以接受該連結的團體訂閱（`CollaboratorsInviteController.mjs:490-501`）。 | `ProjectInvite.mjs:33`, `CollaboratorsInviteHandler.mjs:262` |

#### 寫入方

| 程式碼 | 作用 |
| - | - |
| `CollaboratorsInviteHandler.mjs:76-101` (`inviteToProject`) | 建立郵件邀請，然後寄出郵件，並為既有使用者發送通知。由 `POST /project/:Project_id/invite` 呼叫（`services/web/app/src/Features/Collaborators/CollaboratorsRouter.mjs:114-125`）。 |
| `CollaboratorsInviteHandler.mjs:118-133` (`revokeInvite`) | 刪除一份邀請，並將其通知標記為已讀。由 `DELETE /project/:Project_id/invite/:invite_id` 呼叫（`CollaboratorsRouter.mjs:154-159`）。 |
| `CollaboratorsInviteHandler.mjs:135-153` (`generateNewInvite`) | 重新寄送：刪除邀請並以新權杖建立一份新邀請（`CollaboratorsRouter.mjs:161-169`）。 |
| `CollaboratorsInviteHandler.mjs:103-116` (`revokeInviteForUser`) | 當使用者透過連結共用權杖加入（`services/web/app/src/Features/TokenAccess/TokenAccessController.mjs:396-401`），或在存取請求後獲得存取權限時（`services/web/app/src/Features/Collaborators/CollaboratorsController.mjs:503-513`），刪除寄往該使用者某個已確認電子郵件的邀請。 |
| `CollaboratorsInviteHandler.mjs:155-221` (`acceptInvite`) | 將使用者加入專案，然後刪除邀請，除非邀請為 `reusable`。 |
| `CollaboratorsInviteHandler.mjs:249-269` (`createSharingLinkInvite`), `CollaboratorsInviteController.mjs:689-724` (`updateSharingLink`) | 建立或更新專案唯一的可重複使用共用連結邀請。這些路由需要 split test `sharing-updates-new-link`（`CollaboratorsRouter.mjs:134-152`），而它不在 `splitTestOverrides` 中（`services/web/config/settings.defaults.js:1371-1383`）。因此在設定該 split test 之前，它們會回傳 403。 |

#### 讀取方

| 程式碼 | 作用 |
| - | - |
| `services/web/app/src/Features/Collaborators/CollaboratorsInviteGetter.mjs:6-19` (`getAllInvites`) | 為共用對話框列出待處理的郵件邀請（`GET /project/:Project_id/invites`，`CollaboratorsRouter.mjs:127-132`）。略過可重複使用的邀請。 |
| `CollaboratorsInviteGetter.mjs:21-29` (`getEditInviteCount`) | 計算不是 `readOnly` 的待處理郵件邀請。`services/web/app/src/Features/Subscription/LimitationsManager.mjs:61-70` 在檢查協作者上限時會把它們計入編輯者。 |
| `CollaboratorsInviteGetter.mjs:31-44` (`getInviteByToken`) | 依 URL 中權杖的雜湊尋找邀請，用於邀請頁面與接受邀請（`CollaboratorsInviteController.mjs:353,481`）。 |
| `CollaboratorsInviteGetter.mjs:46-70` | 尋找專案的共用連結邀請。 |

#### 索引

| 名稱 | 鍵 | 選項 | 遷移 |
| - | - | - | - |
| `expires_1` | `{ expires: 1 }` | TTL，`expireAfterSeconds: 10` | `20190912145023_create_projectInvites_indexes.mjs` |
| `projectId_1` | `{ projectId: 1 }` | | `20190912145023_create_projectInvites_indexes.mjs` |
| `tokenHmac_1` | `{ tokenHmac: 1 }` | | `20240524135408_add_token_hmac_project_invite_tokens.mjs` |

遷移位於 `tools/migrations/`。Schema 也宣告了 `expires` 上的 TTL 索引，但 Mongoose 的 `autoIndex` 已關閉（`services/web/app/src/infrastructure/Mongoose.mjs:7`），因此由遷移建立該索引。

#### 備註

* 如果接受 `readAndWrite` 或 `review` 邀請時專案已沒有空餘的編輯者名額，使用者會以唯讀身分加入，並列在專案的 `pendingEditor_refs` 或 `pendingReviewer_refs` 中（`CollaboratorsInviteHandler.mjs:162-205`）。
* 舊版邀請把明文權杖存放在 `token` 欄位中。遷移 `20240524135408_add_token_hmac_project_invite_tokens.mjs` 新增了 `tokenHmac`，`20240531082910_remove_project_invite_tokens.mjs` 移除了 `token`。
* 沒有任何程式碼會刪除已刪除專案的邀請；它們會一直保留，直到被 TTL 索引移除。


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