> ## 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 Chunks 集合

`projectHistoryChunks` 中每個歷史 chunk 一個文件，chunk 是一個專案歷史中的一段連續版本。Mongo 只保存 chunk 的中繼資料；chunk 本身（一個快照加上其後的變更）是 chunks bucket 中經 gzip 壓縮的 JSON 物件。沒有 Mongoose schema：history-v1 在 `services/history-v1/storage/lib/chunk_store/mongo.js` 中寫入此集合，它用於所有 24 個十六進位字元的歷史 id，CE 中正是如此（`services/history-v1/storage/lib/chunk_store/index.js:644-652`）。

#### 欄位

| 欄位 | 型別 | 含義 | 來源 |
| - | - | - | - |
| `_id` | ObjectId | Chunk id。它也是 bucket 中 chunk 物件的名稱（請參閱備註）。 | `mongo.js:183-185` |
| `projectId` | ObjectId | 專案的歷史 id，即 `projects.overleaf.history.id` 中的值。在 CE 中，web 以專案本身的 `_id` 建立歷史（`services/web/app/src/Features/History/HistoryManager.mjs:51-55`）。 | `mongo.js:186` |
| `startVersion` | Number | chunk 中第一個變更之前的專案版本。 | `mongo.js:187` |
| `endVersion` | Number | chunk 中最後一個變更之後的專案版本。 | `mongo.js:188` |
| `endTimestamp` | Date | chunk 中最後一個變更的時間；chunk 沒有變更時為 `null`，例如新專案的第一個 chunk（`libraries/overleaf-editor-core/lib/chunk.js:146-149`）。 | `mongo.js:189` |
| `state` | String | `pending`、`active`、`closed` 或 `deleted`，請參閱備註。 | `mongo.js:190`, `343`, `378`, `409` |
| `updatedAt` | Date | 在插入、啟用與刪除時設定。關閉 chunk 不會改變它。 | `mongo.js:191`, `343`, `409`, `434`, `450` |

#### 寫入方

| 程式碼 | 作用 |
| - | - |
| `services/history-v1/storage/lib/chunk_store/mongo.js:179-194` | `insertPendingChunk`：在上傳 chunk 物件之前插入一筆 `pending` 記錄（`chunk_store/index.js:394-410`）。 |
| `mongo.js:331-359` | `activateChunk`：上傳完成後從 `pending` 變為 `active`。這裡出現重複鍵表示已有另一個 chunk 從該版本開始。 |
| `mongo.js:371-388` | `closeChunk`：有新 chunk 接在其後時從 `active` 變為 `closed`（`confirmCreate`，`mongo.js:206-227`）。 |
| `mongo.js:402-419` | `deleteActiveChunk`：被起始版本相同的更長 chunk 取代時從 `active` 變為 `deleted`（`confirmUpdate`，`mongo.js:295-321`）。 |
| `mongo.js:428-452` | `deleteChunk` 與 `deleteProjectChunks`：把 chunk 標記為 `deleted`。後者在 history-v1 的 `DELETE /projects/:project_id` 上執行（`services/history-v1/api/controllers/projects.js:361-373`）。 |
| `mongo.js:144-174` | `clone`：把一個專案的記錄複製到新的歷史 id 下，用於 history-v1 的 `POST /projects/:project_id/clone`。Web 有此路由的用戶端（`HistoryManager.mjs:63-72`），但 web 中沒有任何程式碼呼叫它。 |
| `mongo.js:497-502` | `deleteOldChunks`：移除舊的 `deleted` 與 `pending` 記錄。只由 `services/history-v1/storage/tasks/delete_old_chunks.js` 執行。 |

新 chunk 來自 project-history，它把排隊中的編輯傳送到 history-v1 的 `POST /projects/:project_id/legacy_changes`（`services/history-v1/api/routes/project_import.js:29-31`）；history-v1 接著呼叫 `chunkStore.update` 或 `chunkStore.create`（`services/history-v1/storage/lib/persist_changes.js:215`, `229`）。新專案的第一個 chunk 來自 `chunkStore.initializeProject`（`chunk_store/index.js:54-80`）。

#### 讀取方

| 程式碼 | 作用 |
| - | - |
| `mongo.js:23-43` | `getLatestChunk`：專案最新的 `active` 或 `closed` chunk。 |
| `mongo.js:54-71` | `getChunkForVersion`：包含某個版本的 chunk。 |
| `mongo.js:77-103` | `getChunkForTimestamp`：某個時間點的目前 chunk。 |
| `mongo.js:108-137` | `getProjectChunkIds` 與 `getProjectChunks`：專案所有有效的 chunk。 |
| `mongo.js:457-492` | `getOldChunksBatch`：供清理工作使用的舊 `deleted` 與 `pending` 記錄。 |
| `services/history-v1/api/controllers/projects.js:115-265` | history-v1 的讀取路由（最新內容、某版本的內容、歷史、變更），它們透過 `chunk_store/index.js` 載入 chunk。 |

#### 索引

| 名稱 | 鍵 | 選項 | 遷移 |
| - | - | - | - |
| `projectId_1_startVersion_1_v2` | `{ projectId: 1, startVersion: 1 }` | unique，部分索引：`state` 為 `active`、`closed` | `tools/migrations/20250411200550_active_chunk_index_update.mjs`（取代 `20221122191857_project_history_chunks_indexes.mjs` 的 `projectId_1_startVersion_1`） |
| `deleted_updated_at` | `{ updatedAt: 1 }` | 部分索引：`state: 'deleted'` | `tools/migrations/20230428154643_history_chunks_garbage_collection_index.mjs`（取代 `state_1`） |
| `pending_updated_at` | `{ updatedAt: -1 }` | 部分索引：`state: 'pending'` | `tools/migrations/20230428154643_history_chunks_garbage_collection_index.mjs`（取代 `20230217205311_fix_deleted_history_chunks_index.mjs` 的 `state_pending`） |

#### 備註

* 狀態流程：`pending`（記錄已寫入，正在上傳）→ `active`（最新的 chunk，仍可延伸）→ `closed`（後面有較新的 chunk）或 `deleted`（被取代，或專案已刪除）。讀取只看 `active` 與 `closed`。
* chunk 物件是經 gzip 壓縮的 JSON（`services/history-v1/storage/lib/history_store.js:151-170`），位於鍵 `<project key>/<chunk id>`（`history_store.js:65-67`）。專案鍵是以零填補的歷史 id，反轉後依 3/3/其餘字元切分（`libraries/object-persistor/src/ProjectKey.js:8-15`）。bucket 是 `OVERLEAF_EDITOR_CHUNKS_BUCKET`（`services/history-v1/config/custom-environment-variables.json:53-56`）：開發環境中為 `/buckets/chunks`（`develop/docker-compose.yml:90`），使用 `S3_ENABLED=true` 時為 `overleaf-chunks`（`develop/s3/docker-compose.yml:51`）。
* 處於 `deleted` 或 `pending` 狀態的記錄及其 bucket 物件只會被 `delete_old_chunks.js` 移除（`yarn delete_old_chunks`，`services/history-v1/package.json:79`）。CE 映像檔沒有為此設定 cron 工作（`server-ce/config/crontab-history`, `server-ce/config/crontab-deletion`），因此在 CE 中它們會一直保留。
* 當 web 讓已刪除的專案過期時，會呼叫 history-v1 的 `DELETE /projects/:history_id`（`services/web/app/src/Features/Project/ProjectDeleter.mjs:385-391`, `HistoryManager.mjs:127-135`, `152-162`），從而把該專案的所有 chunk 標記為 `deleted`。
* 設定了 `backupStore` 時，確認 chunk 也會把 `overleaf.history.currentEndVersion`、`currentEndTimestamp`、`updatedAt` 與 `overleaf.backup.pendingChangeAt` 寫入專案（`mongo.js:232-262`）。CE 沒有設定 `backupStore`，所以 `mongo.js:238-240` 會提前返回。


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