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