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

# Dropbox Entities 集合

`dropboxEntities` 為 Dropbox 同步在專案與某位使用者的 Dropbox 之間複製過的每個檔案保存一份文件，另外還有短期存在的 tombstone。此集合屬於 Dropbox 同步：third-party-datastore（`services/third-party-datastore/app/js/StateManager.mjs`）寫入並讀取它，`dropbox` web 模組（`services/web/modules/dropbox/app/src/DropboxHandler.mjs`）清除它。沒有 Mongoose schema。

#### 欄位

| 欄位 | 型別 | 意義 | 來源 |
| - | - | - | - |
| `_id` | ObjectId | 插入時由驅動程式設定。 | `StateManager.mjs:46,97` |
| `overleaf.userId` | ObjectId | 其 Dropbox 中有該檔案的使用者。每份文件都會設定。 | `StateManager.mjs:48,98` |
| `overleaf.projectId` | ObjectId | doc 或檔案所屬的專案。已知時設定；tombstone 沒有此欄位。 | `StateManager.mjs:49-51` |
| `overleaf.id` | ObjectId | doc 或檔案在專案 `rootFolder` 中的 `_id`。已知時設定。 | `StateManager.mjs:52` |
| `overleaf.type` | String | `doc` 或 `file`。目前的程式碼會寫入但不會讀取它。 | `StateManager.mjs:53`；值來自 `services/web/app/src/Features/ThirdPartyDataStore/TpdsUpdateSender.mjs:35,96` 與 `UpdateMerger.mjs:104,119` |
| `dropbox.id` | String | Dropbox 檔案中繼資料中該檔案的 `id`。tombstone 上不設定。 | `StateManager.mjs:56` |
| `dropbox.pathLower` | String | 檔案在 Dropbox 中的路徑，小寫且不含結尾斜線。檔案或其專案資料夾移動時會更新。 | `StateManager.mjs:14-16,57,91,99` |
| `dropbox.rev` | String | 上次同步時的 Dropbox 修訂版本。下一次上傳會帶上它，因此在 Dropbox 中已變更的檔案不會被覆寫。 | `StateManager.mjs:58`、`JobProcessor.mjs:114-122` |
| `dropbox.contentHash` | String | 上次同步時的 Dropbox 內容雜湊。清單中雜湊相同的檔案會被略過，因為那是我們自己的上傳或已套用過。 | `StateManager.mjs:59`、`PullManager.mjs:147-149` |
| `tombstone` | Boolean | `true` 標記 third-party-datastore 自己在 Dropbox 中刪除或移走的路徑。當 Dropbox 回報這次刪除時，不會將其套用到專案。 | `StateManager.mjs:100`、`PullManager.mjs:189-192` |
| `createdAt` | Date | 僅 tombstone：建立時間。完成的 pull 會移除在其開始之前建立的 tombstone。 | `StateManager.mjs:101,115-121` |

tombstone 只有 `overleaf.userId`、`dropbox.pathLower`、`tombstone` 與 `createdAt`（`StateManager.mjs:96-103`）。

#### 誰寫入

| 程式碼 | 作用 |
| - | - |
| `services/third-party-datastore/app/js/StateManager.mjs:35-62`（`recordEntity`） | 刪除該使用者具有相同 `dropbox.id`、`dropbox.pathLower` 或 `overleaf.id` 的文件，然後插入新狀態。 |
| `services/third-party-datastore/app/js/JobProcessor.mjs:102-134`（`addEntity`） | 從 Overleaf 上傳到 Dropbox 後記錄 doc 或檔案（`:125-133`）。 |
| `services/third-party-datastore/app/js/PullManager.mjs:142-177`（`applyFile`） | web 將 Dropbox 檔案套用到專案後記錄該檔案（`:168-176`）。 |
| `StateManager.mjs:80-94`（`moveEntities`） | 改寫被移動路徑下的 `dropbox.pathLower`：專案重新命名（`JobProcessor.mjs:195`）以及檔案或資料夾移動（`JobProcessor.mjs:239`）。 |
| `StateManager.mjs:96-103`（`addTombstone`） | 在 Dropbox 中刪除（`JobProcessor.mjs:153`）、專案重新命名（`:202`）或移動（`:240`）之後。 |
| `StateManager.mjs:72-78`（`removeEntities`） | 刪除某路徑及其下的項目（tombstone 除外）：在從 Overleaf 刪除（`JobProcessor.mjs:152`）或在 Dropbox 中刪除（`PullManager.mjs:206`）之後。 |
| `StateManager.mjs:115-121`（`clearTombstones`） | 在 pull 結束時（`PullManager.mjs:31,69`）。 |
| `StateManager.mjs:186-190`（`removeUserState`），由 `services/third-party-datastore/app/js/QueueWorker.mjs:43` 呼叫 | third-party-datastore 解除一個無法再使用之帳戶的連結時，刪除該使用者的所有文件。 |
| `DropboxHandler.mjs:142-146`（`removeUserState`） | 在連結時（`:125`）、解除連結時（`:183`）以及已刪除使用者到期時（`services/web/modules/dropbox/index.mjs:62-64`）刪除該使用者的所有文件。 |
| `DropboxHandler.mjs:150-154`（`removeProjectState`） | 已刪除專案到期時刪除該專案的文件（`index.mjs:54-56`）。 |

#### 誰讀取

| 程式碼 | 作用 |
| - | - |
| `StateManager.mjs:64-70`（`findEntityByPath`） | 在上傳前取得 `dropbox.rev`（`JobProcessor.mjs:114`），在套用 Dropbox 檔案前取得 `dropbox.contentHash`（`PullManager.mjs:147`）。 |
| `StateManager.mjs:106-112`（`findTombstone`） | 在該路徑或其某個上層路徑上檢查回報的刪除（`PullManager.mjs:189`）。 |
| `StateManager.mjs:160-175`（`getSyncedPaths`） | 游標重設後列出已同步檔案的路徑，使清單中缺少的檔案被視為已刪除（`PullManager.mjs:74-85`）。 |

#### 索引

| 名稱 | 鍵 | 選項 | 遷移 |
| - | - | - | - |
| `_id_` | `_id: 1` | | default |
| `overleaf_userId_1_overleaf_projectId_1` | `overleaf.userId: 1, overleaf.projectId: 1` | | `tools/migrations/20250130104049_create_dropboxEntities_userId_projectId_index.mjs` |

`20220811111800_create_dropboxEntities_index.mjs` 與 `20220825160708_recreate_dropboxEntities.mjs` 只帶有 `saas` 標籤，因此 CE 既沒有它們在 `(overleaf.userId, dropbox.id)` 與 `(overleaf.userId, overleaf.id)` 上的唯一索引，也沒有它們在 `dropbox.pathLower` 上的雜湊索引。

#### 說明

* 唯一性僅來自 `recordEntity` 中每次插入前的刪除（`StateManager.mjs:38-45`）。`StateManager.mjs:3-11` 的註解提到唯一索引；CE 沒有這些索引。
* 依使用者與路徑的查詢（`findEntityByPath`、`findTombstone`、`removeEntities`）只對 `overleaf.userId` 使用索引。


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