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

# Tokens 集合

`tokens` 儲存一次性權杖：連結中讓使用者設定密碼的那段密鑰。一份文件對應一個權杖。它沒有 Mongoose 模型；web 透過 `services/web/app/src/Features/Security/OneTimeTokenHandler.mjs` 使用原生驅動程式寫入該集合。

#### 欄位

| 欄位 | 型別 | 含義 | 來源 |
| - | - | - | - |
| `_id` | ObjectId | 文件 id。 | `OneTimeTokenHandler.mjs:40` |
| `use` | String | 權杖的用途，見下方的[用途](#uses)。每次查詢都依它篩選。 | `OneTimeTokenHandler.mjs:41` |
| `token` | String | 連結中的密鑰：32 個隨機位元組，表示為 64 個十六進位字元，按原樣儲存。 | `OneTimeTokenHandler.mjs:38,42` |
| `data` | Object | 權杖所代表的內容，在使用權杖時回傳。 | `OneTimeTokenHandler.mjs:43` |
| `data.user_id` | String | 使用者 id，所有呼叫端都以字串寫入。 | `services/web/app/src/Features/PasswordReset/PasswordResetHandler.mjs:27`, `services/web/app/src/Features/User/UserRegistrationHandler.mjs:117`, `services/web/modules/admin-tools/app/src/AdminUserManager.mjs:79` |
| `data.email` | String | 建立權杖時使用者的電子郵件。重設密碼時依這個主要電子郵件尋找使用者（`PasswordResetHandler.mjs:66-70`）。 | 同 `data.user_id` |
| `createdAt` | Date | 建立時間。TTL 索引在 90 天後刪除該權杖。 | `OneTimeTokenHandler.mjs:36,44` |
| `expiresAt` | Date | `createdAt` 加上 `expiresIn` 秒：預設 1 小時，啟用連結為 1 週。過了這個時間，查詢會忽略該權杖。 | `OneTimeTokenHandler.mjs:35-37,45` |
| `peekCount` | Number | 權杖被查看但未使用的次數。每次 `peekValueFromToken` 加 1；達到 4（`MAX_PEEKS`）後權杖失效。 | `OneTimeTokenHandler.mjs:8-31,107` |
| `usedAt` | Date | 權杖被使用或作廢的時間。查詢會忽略帶有此欄位的權杖。 | `OneTimeTokenHandler.mjs:51-104` |

#### 用途

| `use` | 功能 | 有效期 | 程式碼 |
| - | - | - | - |
| `password` | 從「忘記密碼」頁面寄出的密碼重設郵件 | 1 小時 | `PasswordResetHandler.mjs:14-42` |
| `password` | 啟用連結：先以隨機密碼建立帳戶，再寄出設定密碼的連結。用於公開註冊（`services/web/modules/login-register/app/src/RegisterController.mjs:65`）、`user-activate` 的管理員註冊頁面（`services/web/modules/user-activate/app/src/UserActivateController.mjs:27-30`）以及 `create-user` 指令碼（`services/web/modules/server-ce-scripts/scripts/create-user.mjs:21`） | 1 週 | `UserRegistrationHandler.mjs:97-130` |
| `password` | 從管理面板（模組 `admin-tools`）寄出的啟用或密碼重設連結 | 1 週（啟用），1 小時（重設） | `AdminUserManager.mjs:76-103,196-206` |
| `email_confirmation` | 電子郵件確認連結。只會被讀取：本儲存庫已不再建立此類權杖，因為確認電子郵件現在改為寄送 6 位數驗證碼（`services/web/app/src/Features/User/UserEmailsConfirmationHandler.mjs:15-35`） | | `UserEmailsConfirmationHandler.mjs:12,37-66` |

#### 寫入方

| 程式碼 | 作用 |
| - | - |
| `OneTimeTokenHandler.mjs:34-49` (`getNewToken`) | 插入權杖。呼叫端：`PasswordResetHandler.mjs:28`、`UserRegistrationHandler.mjs:115-119`、`AdminUserManager.mjs:77-81`。 |
| `OneTimeTokenHandler.mjs:8-32` (`peekValueFromToken`) | 回傳有效權杖的 `data`，並將 `peekCount` 加 1。在開啟密碼重設頁面時（`services/web/app/src/Features/PasswordReset/PasswordResetController.mjs:195-208`）、設定新密碼時再次（`PasswordResetHandler.mjs:94-96`），以及確認電子郵件時（`UserEmailsConfirmationHandler.mjs:38-41`）使用。 |
| `OneTimeTokenHandler.mjs:75-88` (`expireToken`) | 為單一權杖設定 `usedAt`：在設定新密碼後（`PasswordResetHandler.mjs:44-48,119`）或確認電子郵件後（`UserEmailsConfirmationHandler.mjs:65`）。 |
| `OneTimeTokenHandler.mjs:90-104` (`expireAllTokensForUser`) | 當使用者在設定中變更密碼（`services/web/app/src/Features/User/UserController.mjs:146-149`）或管理員在管理面板中設定密碼（`AdminUserManager.mjs:479-488`）時，為該使用者所有未使用的 `password` 權杖設定 `usedAt`。 |

#### 讀取方

| 程式碼 | 作用 |
| - | - |
| `PasswordResetHandler.mjs:50-70,94-119` | 由重設或啟用權杖找到使用者，然後設定密碼。`user-activate` 的啟用頁面只是把權杖傳給這個表單。 |
| `UserEmailsConfirmationHandler.mjs:37-66` | 透過已登入使用者的 `email_confirmation` 權杖確認電子郵件。 |
| `AdminUserManager.mjs:213-223` (module `admin-tools`) | 尋找使用者未使用的啟用權杖，以便在管理面板中再次顯示啟用連結。直接讀取 `db.tokens`。 |

#### 索引

| 名稱 | 鍵 | 選項 | 遷移 |
| - | - | - | - |
| `token_1_use_1` | `{ token: 1, use: 1 }` | 唯一 | `20190912145031_create_tokens_indexes.mjs` |
| `createdAt_1` | `{ createdAt: 1 }` | TTL，`expireAfterSeconds: 7776000`（90 天） | `20210407085118_token-expiry-with-ttl-index.mjs` |
| `data.user_id_1` | `{ "data.user_id": 1 }` | | `20231113173237_tokens_user_id_index.mjs` |

遷移位於 `tools/migrations/`。

#### 備註

* 已使用或已過期的權杖不會立即刪除：它會帶著 `usedAt` 或已過去的 `expiresAt` 保留下來，直到 TTL 索引在 `createdAt` 之後 90 天將其移除。
* `OneTimeTokenHandler` 還有 `getValueFromTokenAndExpire`（`OneTimeTokenHandler.mjs:51-73`），但沒有程式碼呼叫它。


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