> ## 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 History Sync State 集合

`projectHistorySyncState` 中每个经过重新同步的项目一个文档：当前或最近一次重新同步的状态。重新同步是指 project-history 根据 web 和 docstore 中保存的内容重建项目历史。该集合归 project-history 所有，没有 Mongoose schema；代码是 `services/project-history/app/js/SyncManager.js` 中的 `SyncState` 类及其辅助函数。

#### 字段

| 字段 | 类型 | 含义 | 来源 |
| - | - | - | - |
| `_id` | ObjectId | 由 upsert 创建。 | `SyncManager.js:233-237` |
| `project_id` | ObjectId | 项目。 | `SyncManager.js:233-237` |
| `resyncProjectStructure` | Boolean | project-history 正在等待 web 发来项目结构（文件树）时为 `true`。 | `SyncManager.js:457`, `536-543` |
| `resyncDocContents` | Array of String | 仍在等待其内容的 doc 的路径。 | `SyncManager.js:458`, `482`, `545-546` |
| `origin` | Object | 谁请求了重新同步，例如默认值 `{ kind: 'history-resync' }`。 | `SyncManager.js:150`, `459` |
| `hardResync` | Boolean | 硬重新同步时为 `true`，它会先丢弃排队的更新和旧的同步状态。 | `SyncManager.js:81-100`, `152`, `460` |
| `recoverCorruptedFiles` | Boolean | 重新同步请求的选项（`HttpController.js:963-964`）。在硬重新同步中，历史内容损坏的 doc 会被移除，然后从 docstore 重新添加（`SyncManager.js:942-951`）。 | `SyncManager.js:153`, `461` |
| `history` | Array of Object | 最近 100 个状态，最新的在前，每个为 `{ syncState, timestamp }`；`syncState` 包含上面的五个字段。 | `SyncManager.js:41`, `202-208` |
| `lastUpdated` | Date | 最后一次写入的时间。 | `SyncManager.js:209` |
| `resyncCount` | Number | 已启动的重新同步次数。 | `SyncManager.js:215` |
| `resyncPendingSince` | Date | 正在运行的重新同步的开始时间；完成时移除。 | `SyncManager.js:217`, `224-225` |
| `expiresAt` | Date | 重新同步完成后设为 90 天后，运行期间移除。TTL 索引会在该时间删除文档。 | `SyncManager.js:42`, `216`, `221-223` |
| `stuckClearCount` | Number | 卡住的重新同步被清除并重启的次数；重新同步完成时移除。 | `SyncManager.js:261`, `226` |
| `lastStuckClearAt` | Date | 最近一次此类清除的时间。 | `SyncManager.js:262`, `227` |
| `lastStuckDocPaths` | Array of String | 最近一次清除时仍待处理的 doc 路径。 | `SyncManager.js:262`, `228` |

#### 写入方

| 代码 | 作用 |
| - | - |
| `services/project-history/app/js/SyncManager.js:195-249` | `setResyncState`：upsert 状态。在重新同步开始时（`SyncManager.js:163`）以及 project-history 处理重新同步更新期间（`services/project-history/app/js/UpdatesProcessor.js:637`, `784`）调用。 |
| `SyncManager.js:257-266` | `_recordStuckClearInSyncState`：统计被清除的卡住的重新同步。 |
| `SyncManager.js:251-255` | `clearResyncState`：删除文档，发生在硬重新同步开始时（`SyncManager.js:87`）、project-history 的 `DELETE /project/:project_id` 上（`services/project-history/app/js/HttpController.js:1363-1396`），以及仅结构的重新同步需要重新开始时（`SyncManager.js:705-716`）。 |
| `SyncManager.js:273-289` | `clearResyncStateIfAllAfter`：删除历史全部晚于某个日期的已完成状态。`app/js` 中没有任何代码调用它。 |
| `SyncManager.js:171-181` | `cloneResyncState`：把状态复制到另一个项目，用于 project-history 的 `POST /project/:project_id/clone`（`HttpController.js:57`, `124`），web 中没有任何代码调用它。 |

重新同步由 project-history 的 `POST /project/:project_id/resync`（`HttpController.js:950-994`）、重试 cron 任务（`services/project-history/app/js/RetryManager.js:156-179`, `server-ce/config/crontab-history`），以及 project-history 在处理更新需要时自行启动（`UpdatesProcessor.js:75`, `224`）。

#### 读取方

| 代码 | 作用 |
| - | - |
| `SyncManager.js:187-193` | `getResyncState`：加载状态。用于在启动新的重新同步前判断是否已有一个正在运行（`SyncManager.js:106-149`），在其运行期间跳过普通更新（`SyncManager.js:291-300`），以及在刷写后报告正在运行的重新同步（`UpdatesProcessor.js:463-466`）。 |
| `HttpController.js:533-545` | `GET /project/:project_id/resync-pending`：重新同步是否正在运行或卡住。 |
| `HttpController.js:563-585` | `GET /project/:project_id/debug-info`：同步状态以及失败记录。 |

#### 索引

| 名称 | 键 | 选项 | 迁移 |
| - | - | - | - |
| `project_id_1` | `{ project_id: 1 }` | | `tools/migrations/20190912145021_create_projectHistorySyncState_indexes.mjs` |
| `expiresAt_1` | `{ expiresAt: 1 }` | TTL，`expireAfterSeconds: 0` | `tools/migrations/20190912145021_create_projectHistorySyncState_indexes.mjs` |

#### 说明

* 只要 `resyncProjectStructure` 为 `true` 或 `resyncDocContents` 不为空，重新同步就处于运行中（`SyncManager.js:565-567`）。超过 4 小时视为卡住，清除 5 次后视为永久卡住（`SyncManager.js:43-44`, `569-585`）。
* 重新同步完成时，project-history 还会在项目上设置 `overleaf.history.lastResyncedAt`（`SyncManager.js:239-248`）。


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