> ## 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) من السجل التاريخي، وهو سلسلة من الإصدارات في السجل التاريخي لمشروع واحد. لا يحتفظ Mongo إلا بالبيانات الوصفية للجزء؛ أما الجزء نفسه (لقطة إضافةً إلى التغييرات بعدها) فهو كائن JSON مضغوط بـ gzip في حاوية الأجزاء. لا يوجد مخطط Mongoose: يكتب history-v1 المجموعة في `services/history-v1/storage/lib/chunk_store/mongo.js`، الذي يستخدمه لكل معرّف سجل مكوّن من 24 حرفًا سداسيًا عشريًا، كما في CE ‏(`services/history-v1/storage/lib/chunk_store/index.js:644-652`).

#### الحقول

| الحقل | النوع | المعنى | المصدر |
| - | - | - | - |
| `_id` | ObjectId | معرّف الجزء. وهو أيضًا اسم كائن الجزء في الحاوية (راجع الملاحظات). | `mongo.js:183-185` |
| `projectId` | ObjectId | معرّف السجل التاريخي للمشروع، وهو القيمة في `projects.overleaf.history.id`. في CE ينشئ web السجل بمعرّف `_id` الخاص بالمشروع نفسه (`services/web/app/src/Features/History/HistoryManager.mjs:51-55`). | `mongo.js:186` |
| `startVersion` | Number | إصدار المشروع قبل أول تغيير في الجزء. | `mongo.js:187` |
| `endVersion` | Number | إصدار المشروع بعد آخر تغيير في الجزء. | `mongo.js:188` |
| `endTimestamp` | Date | وقت آخر تغيير في الجزء؛ ‏`null` عندما لا يحتوي الجزء على تغييرات، مثل أول جزء في مشروع جديد (`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 | يُضبط عند الإدراج والتفعيل والحذف. إغلاق الجزء لا يغيّره. | `mongo.js:191`, `343`, `409`, `434`, `450` |

#### من يكتب فيها

| الشيفرة | ما تفعله |
| - | - |
| `services/history-v1/storage/lib/chunk_store/mongo.js:179-194` | ‏`insertPendingChunk`: تُدرج سجلًا بالحالة `pending` قبل رفع كائن الجزء (`chunk_store/index.js:394-410`). |
| `mongo.js:331-359` | ‏`activateChunk`: من `pending` إلى `active` بعد اكتمال الرفع. يعني تكرار المفتاح هنا أن جزءًا آخر يبدأ بالفعل عند ذلك الإصدار. |
| `mongo.js:371-388` | ‏`closeChunk`: من `active` إلى `closed` عندما يليه جزء جديد (`confirmCreate`، ‏`mongo.js:206-227`). |
| `mongo.js:402-419` | ‏`deleteActiveChunk`: من `active` إلى `deleted` عندما يحل محله جزء أطول له إصدار البداية نفسه (`confirmUpdate`، ‏`mongo.js:295-321`). |
| `mongo.js:428-452` | ‏`deleteChunk` و`deleteProjectChunks`: تضعان على الأجزاء علامة `deleted`. تعمل الثانية عند `DELETE /projects/:project_id` في history-v1 ‏(`services/history-v1/api/controllers/projects.js:361-373`). |
| `mongo.js:144-174` | ‏`clone`: تنسخ سجلات مشروع تحت معرّف سجل جديد، لـ `POST /projects/:project_id/clone` في history-v1. لدى web عميل لهذا المسار (`HistoryManager.mjs:63-72`)، لكن لا شيء في web يستدعيه. |
| `mongo.js:497-502` | ‏`deleteOldChunks`: تزيل السجلات القديمة بالحالتين `deleted` و`pending`. لا يشغّلها إلا `services/history-v1/storage/tasks/delete_old_chunks.js`. |

تأتي الأجزاء الجديدة من project-history، الذي يرسل التعديلات المنتظرة في الطابور إلى `POST /projects/:project_id/legacy_changes` في history-v1 ‏(`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`). يحصل المشروع الجديد على أول جزء له من `chunkStore.initializeProject` ‏(`chunk_store/index.js:54-80`).

#### من يقرأ منها

| الشيفرة | ما تفعله |
| - | - |
| `mongo.js:23-43` | ‏`getLatestChunk`: أحدث جزء بالحالة `active` أو `closed` في المشروع. |
| `mongo.js:54-71` | ‏`getChunkForVersion`: الجزء الذي يحتوي على إصدار معيّن. |
| `mongo.js:77-103` | ‏`getChunkForTimestamp`: الجزء الذي كان الحالي في وقت معيّن. |
| `mongo.js:108-137` | ‏`getProjectChunkIds` و`getProjectChunks`: جميع الأجزاء الحية في المشروع. |
| `mongo.js:457-492` | ‏`getOldChunksBatch`: السجلات القديمة بالحالتين `deleted` و`pending` لمهمة التنظيف. |
| `services/history-v1/api/controllers/projects.js:115-265` | مسارات القراءة في history-v1 (أحدث محتوى، المحتوى عند إصدار، السجل التاريخي، التغييرات)، التي تحمّل الأجزاء عبر `chunk_store/index.js`. |

#### الفهارس

| الاسم | المفاتيح | الخيارات | الترحيل |
| - | - | - | - |
| `projectId_1_startVersion_1_v2` | `{ projectId: 1, startVersion: 1 }` | unique، جزئي: `state` ضمن `active`، `closed` | `tools/migrations/20250411200550_active_chunk_index_update.mjs` (يحل محل `projectId_1_startVersion_1` من `20221122191857_project_history_chunks_indexes.mjs`) |
| `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` (يحل محل `state_pending` من `20230217205311_fix_deleted_history_chunks_index.mjs`) |

#### ملاحظات

* تسلسل الحالات: ‏`pending` (السجل مكتوب، والرفع جارٍ) → `active` (أحدث جزء، ويمكن توسيعه بعد) → `closed` (يليه جزء أحدث) أو `deleted` (استُبدل، أو حُذف المشروع). لا تنظر القراءات إلا إلى `active` و`closed`.
* كائن الجزء هو JSON مضغوط بـ gzip ‏(`services/history-v1/storage/lib/history_store.js:151-170`) عند المفتاح `<project key>/<chunk id>` ‏(`history_store.js:65-67`). مفتاح المشروع هو معرّف السجل مُكمَّلًا بالأصفار، معكوسًا ومقسّمًا إلى 3/3/بقية الأحرف (`libraries/object-persistor/src/ProjectKey.js:8-15`). الحاوية هي `OVERLEAF_EDITOR_CHUNKS_BUCKET` ‏(`services/history-v1/config/custom-environment-variables.json:53-56`): ‏`/buckets/chunks` في بيئة التطوير (`develop/docker-compose.yml:90`)، أو `overleaf-chunks` مع `S3_ENABLED=true` ‏(`develop/s3/docker-compose.yml:51`).
* لا يزيل السجلات بالحالة `deleted` أو `pending`، ولا كائناتها في الحاوية، إلا `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 مشروعًا محذوفًا، يستدعي `DELETE /projects/:history_id` في history-v1 ‏(`services/web/app/src/Features/Project/ProjectDeleter.mjs:385-391`, `HistoryManager.mjs:127-135`, `152-162`)، فتُوضع على جميع أجزاء المشروع علامة `deleted`.
* عند ضبط `backupStore`، يكتب تأكيد الجزء أيضًا `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.