تاريخ المشروع

نسخة العمل والتاريخ

سجلات SQLite الخاصة بالتطبيق هي نسخة عمل المشروع الحالية. @cadcamfun/vcs يخزن النقط والأشجار والالتزامات والمراجع المتوافقة مع Git من خلال الواجهة الخلفية للكائن المحقون؛ يستمر السايدكار في الحفاظ على الواجهة الخلفية في SQLite. تعمل عمليات السجل محليًا بدون حساب Git القابل للتنفيذ أو حساب GitHub.

يلتقط الالتزام لقطات للمشروع وموارد التصميم/التصنيع ذات الصلة به. تشير الفروع إلى الالتزامات، بينما يحدد HEAD الفرع المسحوب. تتواجد جداول إصدار الموارد مع هذا المحفوظات على مستوى المشروع؛ نسخة الرسم والتزام المشروع لهما نطاقات مختلفة.

الالتزام وسير العمل فرع

1. يقرأ GET /api/projects/:id/vcs/status لرؤية الفرع الحالي، HEAD، والمسارات المتغيرة.
2. إنشاء فرع مع POST /vcs/branches، ثم التحقق من ذلك مع POST /vcs/checkout. ترتبط مسارات الفروع هنا ببادئة واجهة برمجة التطبيقات (API) الخاصة بالمشروع.
3. تحرير موارد المشروع والالتزام بها POST /vcs/commit ورسالة غير فارغة.
4. فحص GET /vcs/log و GET /vcs/diff. يدعم السجل المراجعة والحد والمسار الاختياري المتعقب.
5. افتح طلب سحب المشروع، وراجع تغييراته الهيكلية، ثم ادمجه بعد حل المراجعات أو التعارضات المحظورة.

إن الخروج والاستعادة والعمليات التي تحرك فرع العمل ترفض نسخة عمل قذرة عند الاقتضاء. تسجل عملية الاستعادة التزامًا جديدًا يمثل المحتوى السابق، ويقتصر اختياريًا على المسارات المحددة. إنه يحافظ على التاريخ اللاحق بدلاً من إعادة كتابته.

محتويات اللقطة

project.json
drawings/<id>.json
components/<id>.json
toolpaths/<id>.json
materials/<id>.json
tools/<id>.json
machine-configs/<id>.json
costs/<id>.json
.cadcamfun/workflows/<name>.yml

يبقي ملف JSON واحد لكل كيان التغييرات غير ذات الصلة منفصلة. تتضمن اللقطة عناصر المكتبة المشار إليها بواسطة مسارات الأدوات وتقديرات تكلفة الإنتاج حتى تتمكن بيانات التصنيع المستعادة من الاحتفاظ بتبعياتها. تقتصر معرفات الكيانات المستخدمة كأسماء ملفات على الأحرف الآمنة والأرقام والشرطات السفلية والواصلات، بحد أقصى 128 من الأحرف.

يتم فرز مفاتيح JSON بشكل متكرر وتستخدم الملفات طباعة جميلة مستقرة مع سطر جديد نهائي. المصفوفات تحتفظ بترتيبها. يمكن أن تنتقل الملفات النصية الإضافية باستخدام لقطة على مستوى الحزمة؛ تقبل نقطة نهاية الالتزام العامة الملفات الإضافية فقط ضمن .cadcamfun/workflows/ باستخدام اسم ملف YAML آمن.

تستخدم الكائنات بايت تنسيق الكائن السائب الخاص بـ git للبايت، لذا تتطابق معرفات الكائنات مع تلك المحسوبة بواسطة git. إدخالات الشجرة هي إما ملفات (mode 100644) أو الدلائل (الوضع 40000). يسجل توقيع الالتزام الاسم والبريد الإلكتروني ووقت Unix بالثواني و +hhmm/-hhmm إزاحة. يتم تخزين الفروع تحت refs/heads/، والفرع الافتراضي للمشروع هو main (packages/vcs/src/object.ts, repository.ts).

فرق ودمج الدلالات

يحسب المستودع قاعدة الدمج، ويتعامل مع الجوانب غير المتغيرة مباشرة، وينفذ عمليات دمج هيكلية ثلاثية الاتجاهات لـ JSON المتغيرة. يمكن دمج تعديلات خصائص الكائن المستقلة دون تعارض. يتم الإبلاغ عن التعديلات المتزامنة غير المتوافقة على نفس العدد أو المصفوفة من خلال مؤشرات JSON؛ لا يتم دمج المصفوفات عنصرًا تلو الآخر.

تتضمن اختلافات الكيانات المسار ونوع المورد والمعرف والاسم عند توفرها وحالة الإضافة/التعديل/الحذف وتغييرات الخصائص مع القيم السابقة/اللاحقة. تستخدم الملفات غير JSON سلوك التعارض على مستوى الملف. يؤدي دمج المستودعات مع التعارضات إلى إرجاع مساراتها ومؤشراتها دون كتابة التزام مدمج.

سحب الطلبات والأذونات

طلبات سحب المشروع مباشرة على /api/projects/:id/pulls. فتح واحد يسجل العنوان والنص والرأس والقاعدة ونوع المؤلف. تتضمن الاستجابات التفصيلية طلب السحب والمراجعات والتغييرات. دعم المراجعات comment, approve، و request-changes، مع مسار اختياري ومؤشر خاصية.

يتحكم أحدث حكم بعدم التعليق لكل مراجع في كتلة تغييرات الطلب. يتم رفض الدمج أثناء تغيير أي طلب من هذا القبيل. ولا يتطلب التنفيذ موافقة إيجابية في حالة عدم وجود حكم بالمنع. تستخدم اختلافات طلب السحب المدمجة التزام الدمج المسجل بحيث لا تغير حركة الفرع اللاحقة سجل المراجعة هذا.

تتطلب قراءة السجل والالتزام والتفرع وفتح طلبات السحب والمراجعة الوصول إلى المشروع. تتطلب عمليات نقل نسخة العمل وصيانة الفرع المشترك المالك أو مسؤول/مدير المؤسسة كما يفرضه المعالج. العمليات القذرة أو المتضاربة ترجع 409؛ ترجع الإجراءات المحمية 403؛ المراجع أو الموارد المفقودة تُرجع 404؛ العمليات الأخرى غير الصالحة ترجع 400.

لا يمكن لممثل الذكاء الاصطناعي الالتزام أو الاستعادة أو الاندماج main. يستخدم المساعد فرع الاقتراح ويفتح طلب سحب ليقوم الشخص بمراجعته. تحدد سجلات التدقيق والإخطار التغييرات التي أنشأها المساعد.

مرآة جيثب اختيارية

GET و PUT /api/projects/:id/vcs/remote قراءة أو تعيين owner/repo مرآة جيثب؛ null يفصله. استخدام الدفع والسحب POST /vcs/push و /vcs/pull، مع رمز GitHub الخاص بالمستخدم x-github-token لتلك المكالمة.

يقوم Push بنقل الكائنات التي يمكن الوصول إليها وتحديث الفرع البعيد دون الكتابة فوق الالتزامات البعيدة غير المسحوبة. يؤدي السحب إلى جلب الفرع البعيد ودمجه محليًا، مع رفض نسخة العمل القذرة. تؤدي تعديلات JSON المتباينة غير المتوافقة إلى إرجاع التعارضات بدلاً من استبدال المحتوى المحلي بصمت.

يستخدم النقل السايدكار عمليات كائن/مرجع GitHub REST. يتم توفير رمز GitHub لكل طلب ولا يتم تخزينه كبيانات مشروع. طلب السحب المحلي هو سجل مراجعة التطبيق؛ إنه ليس طلب سحب GitHub تلقائيًا.

لقطات والترميم

snapshotToFiles تحويل لقطة المشروع إلى محتويات الملف الأساسي؛ filesToSnapshot يعيد بناء قوائم المجال. ProjectVcsRepo يقرأ موارد قاعدة البيانات الحالية ويطبق اللقطات المستعادة. يمكن أن تؤدي استعادة المشروع بالكامل إلى تغيير العديد من الجداول ذات الصلة، لذا راجع اختلافاتها وامسح نسخة العمل قبل تبديل السجل.

واجهات برمجة تطبيقات النقل والكائنات

تقوم حزمة VCS بتصدير تشفير الكائنات وقراءتها، Repositoryومحولات المتجر ومساعدات JSON والدمج الأساسية وتحويل اللقطة واختلافات الكيانات ومزامنة GitHub وواجهات النقل. يمكن للاختبارات إدخال واجهة خلفية لكائن في الذاكرة أو نقل مزيف بدلاً من الوصول إلى مستودع المستخدم.

مداخل التنفيذ

packages/vcs/src/repository.ts يمتلك الالتزامات والمراجع والاجتياز والاستعادة والدمج؛ json.ts تمتلك الدمج الهيكلي. snapshot.ts يحدد الموارد المتعقبة؛ diff.ts يصف تغييرات الكيان؛ github.ts و transport.ts تنفيذ النسخ المتطابق. السايدكار project-vcs.ts ويضيف سياسة الفاعل والمثابرة، في حين http/vcs.ts لوازم تصريح النقل والأحداث.

عمليات التاريخ والأتمتة

يتم إصدار تعريفات سير العمل مع المشروع ويتم تشغيلها مقابل الملفات الملتزم بها. قد يؤدي الالتزام إلى تشغيل مسارات العمل هذه بعد تسجيل السجل؛ سير العمل الفاشل لا يتراجع عن الالتزام. حافظ على تميز عمليات حفظ الموارد المحلية، وعمليات تنفيذ المشروع، ونتائج سير العمل، والمزامنة عن بعد عند تشخيص حالة المشروع.

جرب المستودع بدون بيانات التطبيق

يتيح خط تخزين الكائنات تنفيذ تمرين التكامل وتفرعه بالكامل في الذاكرة. قم بتشغيل هذا داخل مساحة العمل التي تعتمد عليها @cadcamfun/vcs، مثل apps/sidecar. لا يمس قاعدة بيانات مشروع سطح المكتب.

import { Repository, memoryBackend, canonicalJson } from "@cadcamfun/vcs"

const repo = new Repository(memoryBackend())
const author = { name: "Workshop", email: "workshop@example.invalid", time: 0, tz: "+0000" }
repo.commit({ "project.json": canonicalJson({ name: "Blank", revision: 1 }) }, {
  message: "Initial blank", author
})
repo.createBranch("proposal/wider-blank")
repo.checkout("proposal/wider-blank")
repo.commit({ "project.json": canonicalJson({ name: "Blank", revision: 2 }) }, {
  message: "Record revised blank", author
})
console.log(repo.currentBranch()) // proposal/wider-blank
console.log(repo.log().length) // 2

Repository.commit يتلقى شجرة الملفات الكاملة لهذا الالتزام، وليس التصحيح. يقوم السايدكار ببناء هذه الشجرة من سجلات قاعدة البيانات العاملة والملفات النصية المحمولة. يجب أن يحافظ التكامل على مستوى الحزمة على الملفات التي ينوي الاحتفاظ بها. لا يطبق المثال الموجود في الذاكرة الملكية السايدكار أو سياسة ممثل الذكاء الاصطناعي؛ يتم فرضها بواسطة خدمة المشروع وطبقة HTTP.

مصدر: packages/vcs/src/store.ts, repository.ts، و apps/sidecar/src/services/project-vcs.ts.

المراجعة والاستعادة والمزامنة بشكل متعمد

تسجيل تغييرات نسخة العمل قبل تبديل الفروع. يتطلب التفرع الجديد التزام مصدر قابل للحل، لذا قم بتهيئة مشروع غير ملتزم بالتزامه الأول قبل التفرع. إنشاء فرع يؤدي فقط إلى إنشاء مرجع؛ الخروج عبارة عن عملية منفصلة تطبق لقطةها على قاعدة البيانات العاملة.

بالنسبة لطلب السحب، قارن الرأس بقاعدة الدمج الخاصة به وقم بمراجعة الاختلافات على مستوى الخاصية. لا يؤدي التعليق اللاحق إلى مسح حكم تغييرات الطلب السابق: يجب على المراجع إرسال حكم الموافقة اللاحق. يمكن للعلاقات العامة المدمجة التقديم السريع أو إنشاء التزام دمج وفقًا لأصل المستودع؛ افحص التزام الدمج المسجل بدلاً من افتراض عدد ثابت من الوالدين.

عند الدمج في القاعدة المسحوبة، تتطلب الخدمة نسخة عمل نظيفة وتطبق اللقطة الأساسية الجديدة. عند سحب فرع آخر، يقوم دمج التحديثات الأساسية للعلاقات العامة بتحديث مرجع هذا الفرع دون استبدال قاعدة البيانات العاملة الحالية. يقوم السحب اللاحق بتحميل تلك القاعدة المحدثة.

يعمل الدفع والسحب على مزامنة التاريخ الملتزم. لا يعد محتوى واجهة المستخدم غير المحفوظ وحالة قاعدة البيانات غير الملتزم بها لقطات عن بعد. الرفض عن بعد هو طلب جلب/دمج أولاً؛ إنها ليست تعليمات بالكتابة فوق الفرع البعيد.

مصدر: packages/vcs/src/repository.ts, github.ts، و apps/sidecar/src/services/project-vcs.ts.

التعافي من إخفاقات التاريخ

مصدر: packages/vcs/src/repository.ts, apps/sidecar/src/services/project-vcs.ts، و http/vcs.ts. ال مرجع واجهة برمجة التطبيقات يسرد مخططات الطلب والاستجابة الفعلية.

تخطيط المستودع

يتم تخزين المشروع في المستودع كملف JSON واحد لكل كيان. وبالتالي فإن تحرير الرسم لا يمس أبدًا ملف مسار الأدوات، ويتم قراءة التخطيط بشكل طبيعي على GitHub. snapshotToFiles يكتب هذا التخطيط من أ ProjectSnapshot، و filesToSnapshot يقرأها مرة أخرى.

الالتزام والتفرع والفرق والدمج في الكود

ال Repository يعمل الفصل على أي واجهة تخزين خلفية. يدعمها السايدكار باستخدام SQLite (الجداول GitObject و GitRef); memoryBackend() يستخدم للاختبارات والتجارب. المثال التالي كامل وتظهر نتائجه في التعليقات.

import { Repository, memoryBackend, snapshotToFiles, describeDiff } from "@cadcamfun/vcs"

const repo = new Repository(memoryBackend())
const me = { name: "Ada", email: "ada@example.com", time: 1767225600, tz: "+0100" }
const files = (width: number, height: number) => snapshotToFiles({
  project: { id: "p1", name: "Bracket" },
  drawings: [{ id: "d1", name: "Plate", width, height }],
  components: [], toolpaths: [],
})

const base = repo.commit(files(40, 25), { message: "base", author: me })
repo.currentBranch()                    // "main"

repo.createBranch("a"); repo.createBranch("b")
repo.checkout("a"); const a = repo.commit(files(50, 25), { message: "a: width 50", author: me })
repo.checkout("b"); repo.commit(files(40, 30), { message: "b: height 30", author: me })

describeDiff(repo, base, a)
// [{ path: "drawings/d1.json", kind: "drawings", id: "d1", name: "Plate",
//    status: "modified", changes: [{ pointer: "/width", before: 40, after: 50 }] }]

repo.mergeInto("a", "b", me)            // { kind: "merge", oid: "46e7…" }
// different properties of the same entity merge cleanly

repo.checkout("b"); repo.commit(files(60, 30), { message: "b: width 60", author: me })
repo.mergeInto("a", "b", me)
// { kind: "conflict", conflicts: [{ path: "drawings/d1.json", pointers: ["/width"] }] }

repo.createBranch("bad..name")          // throws: Invalid branch name bad..name
repo.commit(sameFilesAsHead, { message: "x", author: me })
// throws: No changes since the last commit   (unless allowEmpty: true)

تكون عمليات الدمج ثلاثية على مستوى خصائص JSON. عندما يقوم كلا الجانبين بتغيير خصائص مختلفة لكيان واحد، ينجح الدمج. عندما يقوم كلاهما بتغيير نفس الخاصية إلى قيم مختلفة، تكون النتيجة أ conflict يسرد مؤشرات RFC 6901 داخل كل ملف. تتم مقارنة المصفوفات ذات الطول المتساوي لكل فهرس، لذلك تظهر القمة المنقولة كتغيير واحد؛ تتم مقارنة صفائف ذات أطوال مختلفة ككل.

القواعد التي يفرضها التطبيق

تضيف خدمة محفوظات المشروع الخاصة بالسايدكار قواعد أعلى المستودع:

يتم احتساب فقط أحدث حكم بعدم التعليق لكل مراجع. المراجع الذي طلب التغييرات ووافق عليها لاحقًا لم يعد يحظر الدمج. يتم نشر عمليات التنفيذ وسحب الأحداث والمراجعات كأحداث مباشرة، وبالتالي يتم تحديث سطح المكتب والإصدار المصاحب دون الاقتراع.

كائن التزام حقيقي

{
  "oid": "44d2d03d23b27fbbc4b388e32e15dfb0f39fff87",
  "parents": [],
  "message": "First version\n",
  "author": { "name": "Local user", "email": "local@cadcamfun.local", "time": 1792037121 }
}

• oid هو معرف سداسي عشري مكون من 40 حرف لكائن الالتزام المخزن فيه GitObject.
• الالتزام الأول ليس له أهل؛ التزام الدمج له اثنان.
• يتم تخزين الرسالة بسطر جديد لاحق، كما يفعل Git.
• بدون x-session-token، المؤلف هو ملف التعريف المحلي للتثبيت. time في ثواني يونكس.

في 3د