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