مراجعة واستعادة تغيير المشروع

فصل الموارد المحفوظة عن التاريخ الملتزم به

يؤدي حفظ مشروع أو رسم أو مسار أداة إلى تحديث نسخة عمل SQLite. يؤدي إنشاء التزام مشروع إلى أخذ لقطات موارد العمل إلى كائنات متوافقة مع Git ونقل مرجع الفرع الحالي. هذه عمليات منفصلة: يمكن أن يكون الرسم المحفوظ متاحًا، ويمكن أن يظل البرنامج الملتزم محليًا دون أي مرآة بعيدة.

تقوم خدمة محفوظات السايدكار بإنشاء ملف JSON أساسي واحد لكل مورد. تتضمن الشجرة project.json والرسومات والمكونات ومسارات الأدوات والمواد/الأدوات/تكوينات الماكينة المرجعية وتكاليف الإنتاج. سير العمل YAML والنصوص الأخرى غير المتعلقة بالكيان موجودة في شجرة المستودع، بدلاً من سجلات الرسم العادية. لا يتطلب التغيير إلى كيان واحد التعامل مع قاعدة البيانات بأكملها باعتبارها فرقًا ثنائيًا غير شفاف.

اختر مشروعًا يمكن التخلص منه أو مقصودًا قبل اتباع الأمثلة المتحولة. تعيين PROJECT_ID إلى معرفه الحقيقي واستخدم عنوان URL/حامل التطبيق الحالي للاتصال. يتم توثيق تاريخ المشروع ونقاط نهاية سير العمل في ملف مرجع API التاريخ; تستخدم عمليات كتابة البيانات التعريفية للمشروع واجهة برمجة تطبيقات المشاريع.

تستخدم الكائنات تنسيق الكائنات السائبة الدقيق للبايت الخاص بـ git، لذا فإن معرفات الالتزام والشجرة تتطابق مع ما git يحسب لنفس المحتوى. مراجع الفروع تعيش تحت refs/heads/، والفرع الافتراضي هو main.

فحص الهوية وحالة العمل

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

curl --fail-with-body \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN" \
  "$CADCAMFUN_URL/api/projects/$PROJECT_ID/vcs/status"

تقوم الاستجابة بتسمية الفرع والرأس الفارغ والمسارات القذرة. القذرة تعني أن ملفات الموارد الحالية تختلف عن HEAD. تعتبر القائمة غير الفارغة بمثابة معلومات مراجعة مفيدة، وليست فشلاً في التخزين. قبل نقل نسخة العمل، قرر ما إذا كانت هذه التغييرات تنتمي إلى التزام أو يجب استعادتها/تجاهلها عمدًا.

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

قم بإنشاء خط أساس أو سجل التعديلات المقصودة

يتطلب الالتزام رسالة غير فارغة ويلتقط الموارد الحالية المدعومة بقاعدة البيانات. قم بمراجعة المسارات القذرة أولاً: لا تقوم واجهة برمجة التطبيقات (API) بتنظيم ملفات الكيانات الفردية. يضيف حقل الملفات الاختيارية تعريفات سير العمل الآمنة، الموضحة لاحقًا؛ ولا يحدد تعديلات الرسم المراد تضمينها.

curl --fail-with-body \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"message":"Record baseline blank"}' \
  "$CADCAMFUN_URL/api/projects/$PROJECT_ID/vcs/commit"

الاستجابة هي سجل التزام 201 بمعرف الكائن، ومعرفات الأصل، والرسالة، ومعلومات المؤلف. قم بتسجيل معرف الكائن (OID) الخاص به لإجراء مقارنة أو استعادة لاحقًا. يتم رفض الشجرة غير المتغيرة باستخدام NothingToCommit بدلاً من تصنيع مراجعة أخرى من نفس المحتوى.

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

إنشاء والتحقق من الاقتراح

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

curl --fail-with-body \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN" -H "Content-Type: application/json" \
  --data '{"name":"proposal/blank-label"}' \
  "$CADCAMFUN_URL/api/projects/$PROJECT_ID/vcs/branches"

curl --fail-with-body \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN" -H "Content-Type: application/json" \
  --data '{"branch":"proposal/blank-label"}' \
  "$CADCAMFUN_URL/api/projects/$PROJECT_ID/vcs/checkout"

للبدء في مكان آخر، قم بإضافة من المراجعة إلى إنشاء الفرع. يجب أن تكون الأسماء عبارة عن مراجع آمنة: يتم رفض الاجتياز، والشرطة المائلة المتكررة، وشرطة مائلة لاحقة/.lock، وأجزاء تعبير المرجع. تم أيضًا رفض إعادة استخدام اسم موجود.

بعد الخروج، احفظ تغييرات المشروع المقصودة من خلال واجهات برمجة تطبيقات الموارد الخاصة بهم. للحصول على عرض توضيحي صغير، قم بتحديث البيانات التعريفية للمشروع باستخدام PUT /api/projects/:id واسم جديد، ثم قم بتنفيذها. يتغير الفرق الناتج إلى project.json؛ لا يعني تغييرًا هندسيًا. في مراجعة الجزء الحقيقي، احفظ الرسم وأي مسارات أدوات تم تجديدها قبل الالتزام.

اقرأ التغييرات الدقيقة قيد المراجعة

GET /vcs/log يدعم المراجعة والحد والمسار الاختياري المتعقب. GET /vcs/diff يتطلب ويقبل اختياريًا من. استخدم معرفات الكائنات الصريحة لإجراء مقارنة قابلة للتكرار. قم بتشفير أسماء الفروع ومسارات JSON كقيم استعلام بدلاً من ربط علامات الترقيم التي لم يتم إلغاؤها في عناوين URL.

curl --fail-with-body --get \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN" \
  --data-urlencode "from=main" \
  --data-urlencode "to=proposal/blank-label" \
  "$CADCAMFUN_URL/api/projects/$PROJECT_ID/vcs/diff"

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

قم بمراجعة أدلة التصنيع كجزء من سجل مسار الأدوات: مطابقة رمز G وهوية القطعة الأثرية أكثر أهمية من اسم ملف مألوف. يلتقط التزام المشروع البيانات المحفوظة؛ ولا يقوم بتشغيل طلب تصنيع أصلي مفقود فقط لأن الشجرة تحتوي على نص NC.

إجراء الشيكات القابلة للتنفيذ مع المشروع

تقتصر الملفات الإضافية لنقطة النهاية للالتزام العام على .cadcamfun/workflows/<safe-name>.yml أو يمل. فهو يقبل القيم النصية، وليس تصحيحات نظام الملفات التعسفية. لا يمكنك استخدام هذا الحقل لاستبدال رسم JSON أو كتابة نصوص shell أو حذف ملف عن طريق إرسال null.

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

name: Review checks
on:
  manual: true
  pullRequest:
    branches: [main]
jobs:
  inspect:
    steps:
      - id: structure
        uses: project/validate
      - uses: project/require-gcode
      - uses: cam/sequence
      - id: replay
        uses: cam/verify

لتنفيذه من برنامج نصي، أنشئ نص JSON باستخدام مُسلسِل بدلاً من الهروب اليدوي من YAML:

const body = {
  message: "Add committed review checks",
  files: { ".cadcamfun/workflows/review.yml": await Bun.file("review.yml").text() }
}
const encoded = JSON.stringify(body)

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

إرسال الشيكات وتفسير أدلتها

POST /api/projects/:id/actions/dispatch يقبل مرجعًا اختياريًا ويقوم بتشغيل كل سير عمل يدوي يطابق ذلك المرجع الملتزم. إنه ليس محدد اسم سير عمل واحد. اقرأ التعريفات عند الإجراءات/سير العمل والنتائج المستمرة عند الإجراءات/التشغيل. تقوم الخدمة بإرجاع أحدث 50 تشغيل بشكل افتراضي.

يسجل التشغيل سير العمل، والمشغل، والمرجع، وSHA، والطوابع الزمنية، والحالة، والأحداث. الوظائف تتبع مستويات التبعية؛ يمكن تشغيل الوظائف المستقلة بشكل متزامن، بينما تكون الخطوات داخل الوظيفة متسلسلة. معرفات الاستخدامات غير المعروفة تفشل قبل التنفيذ. قيمة if هي النجاح أو الفشل أو دائمًا ليست تعبيرًا تعسفيًا. تتخطى التبعية الفاشلة وظيفتها النهائية بالكامل.

قم بتفسير مخرجات CAM بعناية. cam/verify و cam/gcode فحص ملتزم Toolpath.data.request. قد يتم الإبلاغ عن الطلبات المفقودة، أو مسارات الأدوات غير المدعومة، أو NC المفقود في المخرجات التي تم تخطيها. التشغيل الناجح مع التحقق =0 ليس دليل تحقق. يتحقق المشروع/require-gcode من مسارات الأدوات الموجودة؛ يمكن للمشروع الذي لا يحتوي على مسارات أدوات أن يلبيه بشكل فارغ.

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

فتح الاقتراح ومراجعته ودمجه

افتح طلب سحب محلي بالعنوان والرأس والنص الاختياري والقاعدة (الرئيسية بشكل افتراضي). يجب أن يختلف الرأس والقاعدة، والقاعدة التي تحتوي على الرأس بالفعل ليس لديها ما يمكن دمجه. تتضمن الاستجابة رقمًا محليًا للمشروع تستخدمه نقاط نهاية المراجعة والدمج.

curl --fail-with-body \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN" -H "Content-Type: application/json" \
  --data '{"title":"Review blank label","head":"proposal/blank-label","base":"main","body":"Metadata change and committed checks."}' \
  "$CADCAMFUN_URL/api/projects/$PROJECT_ID/pulls"

GET /pulls/:number يُرجع الطلب والمراجعات والتغييرات. تقبل المراجعات التعليق أو الموافقة أو طلب التغييرات باستخدام مسار/مؤشر اختياري. يتحكم أحدث حكم بعدم التعليق لكل مراجع في كتلة تغييرات الطلب. تعليق لاحق لا يوضح ذلك. يجب على هذا المراجع تقديم حكم الموافقة المحدث. لا يشتمل التنفيذ على متطلبات عدد الموافقة الإيجابية عندما لا يبقى أي حكم بالحظر.

POST /pulls/:number/merge يتطلب وصول المشرف. لا يمكن للجهات الفاعلة في منظمة العفو الدولية الاندماج في الجهات الرئيسية. إذا تم سحب القاعدة، فستتطلب الخدمة نسخة عمل نظيفة وتطبق اللقطة المدمجة على قاعدة البيانات. إذا تم سحب فرع آخر، فإنه يقوم بتحديث المرجع الأساسي دون استبدال قاعدة البيانات العاملة الحالية. قد تؤدي عمليات الدمج إلى تقديم سريع أو إنشاء التزام دمج؛ فحص النسب بدلا من افتراض الوالدين.

تستخدم اختلافات طلب السحب المدمجة التزام الدمج المسجل، مع الحفاظ على عرض المراجعة بعد نقل المراجع. طلبات السحب المحلية هي سجلات مراجعة التطبيقات، وليست طلبات سحب GitHub تلقائيًا.

استعادة المحتوى دون إعادة كتابة التاريخ

POST /vcs/restore يأخذ مراجعة ومسارات اختيارية. فهو يتطلب وصول المشرف ونسخة عمل نظيفة، وينشئ التزامًا جديدًا يحتوي على المحتوى السابق. لا يقوم بإعادة تعيين الفرع للخلف ولا يمحو الالتزامات المتداخلة. تقوم الخدمة بعد ذلك بتطبيق الرأس الجديد على قاعدة بيانات العمل.

{
  "rev": "earlier-commit-oid",
  "paths": ["drawings/actual-drawing-id.json"]
}

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

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

مرآة التاريخ الملتزم واستعادة الصراعات

مرآة GitHub اختيارية. اضبط جهاز التحكم عن بعد على سلسلة المالك/الريبو باستخدام PUT /vcs/remote، أو null للفصل. استخدم الدفع والسحب رمز GitHub الخاص بالمستخدم في x-github-token لتلك المكالمة؛ لم يتم حفظه في مشروع JSON. مطلوب وصول المشرف لعمليات HTTP هذه.

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

HTTP 409 يعني عادةً الحالة القذرة أو تعارض الدمج؛ 403 يمكن أن يعني تقييدًا للمشرف أو للذكاء الاصطناعي الرئيسي؛ 404 يمكن أن يعني مشروعًا لا يمكن الوصول إليه أو مراجعة غير معروفة؛ يغطي 400 الأسماء غير الصالحة أو الرسائل الفارغة أو لا توجد تغييرات. يشير فشل قاعدة البيانات إلى خطأ في تخزين الخادم. احتفظ بمعرفات الكائنات (OIDs) ورسالة الفشل عند تشخيص عدم التطابق.

مصدر المصدر : packages/vcs/src/repository.ts, json.ts, snapshot.ts, github.ts; apps/sidecar/src/services/project-vcs.ts, repos/project-vcs-repo.ts، و http/vcs.ts; مخطط سير العمل/العداء في packages/workflow/src والسايدكار workflow-runner.ts/workflow-steps.ts.

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

1. افتح طلب سحب من فرع الميزة (يجب على ممثل الذكاء الاصطناعي استخدام ملف ai/* فرع) في main.
2. يقدم المراجعون comment, approve، أو request-changes، يتم تثبيته بشكل اختياري على ملف path وJSON pointer.
3. في وقت الدمج، تأخذ الخدمة أحدث حكم بعدم التعليق لكل مراجع. إذا كان أي منهم هو request-changes، فشل الدمج مع blocked: "طلب أحد المراجعين إجراء تغييرات".
4. إذا تم سحب الفرع الأساسي، فيجب أن تكون نسخة العمل الخاصة به نظيفة.
5. يتم الدمج ثلاثي الاتجاه لكل خاصية JSON. يتم إرجاع الصراعات بمساراتها ومؤشراتها، ولا يتم الالتزام بأي شيء.
6. سير العمل مع on.pullRequest مطابقة تشغيل الفرع الأساسي عند فتح طلب السحب، بحيث تكون نتائجها متاحة أثناء المراجعة.

استعادة الوصفات

// Bring back one drawing as it was three commits ago
const old = repo.log()[3].oid
repo.restorePaths(old, ["drawings/d1.json"], me, "Restore plate outline")

// Make the whole tree equal to an older commit (a new commit on top)
repo.revertTo(old, me)               // message defaults to "Restore <rev>"

// Who changed a toolpath, most recent first
repo.fileLog("toolpaths/op1.json").map((e) => e.message)

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

جلسة مراجعة كاملة، تم التقاطها

تم التقاط كل استجابة أدناه من سايدكار قيد التشغيل في مشروع جديد (تم اختصار المعرفات). المسارات نسبة إلى /api/projects/{id}/.

# fresh project with one drawing
GET  vcs/status
{"branch":"main","head":null,"dirty":["drawings/2f315a02-….json","project.json"]}

POST vcs/commit       {"message":"Baseline"}
{"oid":"8bdded63…","parents":[],"message":"Baseline\n","author":{"name":"Local user",…}}

POST vcs/branches     {"name":"thicker"}
{"current":"main","branches":{"main":"8bdded63…","thicker":"8bdded63…"}}

POST vcs/checkout     {"branch":"thicker"}
{"branch":"thicker","head":"8bdded63…","dirty":[]}

PUT  /api/drawings/{id}  {"name":"Plate 12mm"}
GET  vcs/status
{"branch":"thicker","head":"8bdded63…","dirty":["drawings/2f315a02-….json"]}

POST vcs/commit       {"message":"Rename plate"}
{"oid":"a6869011…","parents":["8bdded63…"],…}

GET  vcs/diff?from=main&to=thicker
[{"path":"drawings/2f315a02-….json","kind":"drawings","id":"2f315a02-…","name":"Plate 12mm",
  "status":"modified","changes":[
    {"pointer":"/name","before":"Plate","after":"Plate 12mm"},
    {"pointer":"/updatedAt","before":"…09:20.069Z","after":"…09:20.168Z"}]}]

POST pulls            {"title":"Thicker plate","head":"thicker","base":"main"}
{"number":1,"state":"open","authorKind":"user","mergeCommit":null,…}

POST pulls/1/reviews  {"verdict":"approve","body":"Looks good"}
{"verdict":"approve","body":"Looks good","path":null,"pointer":null,…}

POST pulls/1/merge
{"number":1,"state":"merged","mergeCommit":"a6869011…",…}

POST pulls/1/merge    (again)
{"_tag":"BadRequest","message":"Pull request is not open"}

حقول المراجعة والاستعلام

في 3د