مرجع واجهة برمجة التطبيقات

ملخص

السايدكار هي تأثير واحد HttpApi. كل نقطة نهاية مكتوبة HttpApiEndpoint مع أجسام الطلب والاستجابة التي تم التحقق منها في المخطط، لذلك يأتي هذا المرجع ومجموعة SDK التي تم إنشاؤها والخادم قيد التشغيل من نفس الإعلان في packages/api.

عنوان URL الأساسي

لا توجد واجهة برمجة تطبيقات CADCAMFUN مستضافة. السايدكار تعمل على جهازك، وتربط 127.0.0.1 على منفذ يختاره نظام التشغيل (يستمع إلى المنفذ 0)، ويتحقق من المنفذ الخاص به /api/health، وعندها فقط يطبع سطر JSON واحدًا على stdout. عنوان URL الأساسي هو http://127.0.0.1:<port> من ذلك الخط.

export CADCAMFUN_TOKEN=dev-token
CADCAMFUN_DATA_DIR=$(mktemp -d) \
CADCAMFUN_MIGRATIONS_DIR=$PWD/packages/db/drizzle \
CADCAMFUN_AI_OFFLINE=true \
  bun --no-env-file apps/sidecar/src/main.ts
# stdout: {"event":"ready","port":46709}
export CADCAMFUN_URL=http://127.0.0.1:46709

المصادقة

يعلن العقد عن مخطط أمني واحد، bearer (HTTP Bearer). 324 من 325 من العمليات تتطلب ذلك؛ فقط GET /api/health عام.

curl -s "$CADCAMFUN_URL/api/health"
curl -s "$CADCAMFUN_URL/api/projects" -H "Authorization: Bearer $CADCAMFUN_TOKEN"

الاتفاقيات

• JSON داخل، JSON خارج. الهيئات هي application/json ما لم تنص البطاقة على خلاف ذلك: تحميلان متعددا الأجزاء، وخطاف ويب واحد بثماني بتات، وتمهيد JavaScript، وتنزيل مضغوط، وملف مكون إضافي ثنائي، وتدفقين للأحداث.
• معرفات العملية منقطة. projects.get, vcs.commit: علامة المجموعة، النقطة، اسم الطريقة المستخدمة من قبل العملاء الذين تم إنشاؤهم.
• يتم كتابة الأخطاء. يتم الإعلان عن حالات الفشل لكل نقطة نهاية وتحمل أ _tag; قم بتشغيله بدلاً من تحليل الرسائل. عبر العقد، تم الإعلان عن 401 في العمليات 269، و500 في 264 و400 في 206.
• مراسي التشغيل مستقرة. كل بطاقة قابلة للربط كما #op-<method>-<path>، على سبيل المثال /docs/api/projects#op-get-api-projects-id.

جاري

curl -N "$CADCAMFUN_URL/api/projects/$PROJECT_ID/events" \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN"

العملاء

@cadcamfun/api/sdk يتم إنشاؤه من نفس العقد: كل معرف عملية أدناه هو طريقة مكتوبة CadCam.make(...)، مع أخذ إدخال ثابت واحد لمعلمات المسار وحقول النص. يتم إنشاء 259 من العمليات 325؛ تظهر كل بطاقة مكالمتها بالضبط.

import { CadCam } from "@cadcamfun/api/sdk"

const client = CadCam.make({
  baseUrl: process.env.CADCAMFUN_URL!,
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

const projects = await client.projects.list()
const created = await client.projects.create({ name: "Bracket" })

موارد

عمليات 325 في مجموعات 35، مرتبة حسب ما تخدمه.

جوهر

تصميم

تصنيع

موارد

ملحقات

الحسابات

مستند OpenAPI

تحميل /docs/api/openapi.json (اللقطة التي تم تسجيل الوصول إليها والتي يعرضها هذا الموقع) أو قم بإحضار المستند المباشر من سايدكار قيد التشغيل في /api/openapi.json. إعادة إنشاء اللقطة باستخدام bun run generate:api-reference في packages/web بعد تغيير نقطة النهاية.

العقد والخادم

@cadcamfun/api يحدد مخططات الطلب والاستجابة باستخدام Effect HttpApi. يقوم بتصدير الجذر Apiوسجلات المجال والأخطاء ذات العلامات والعملاء. يتم تشغيل معالجات الطلب وقرارات الترخيص واستعلامات قاعدة البيانات واستدعاءات الموفر في السايدكار. لا يؤدي استيراد المخطط إلى بدء تشغيل الخادم.

تنشر السايدكار عقدها المقدم في GET /api/openapi.json. استخدم هذا المستند قيد التشغيل لفحص الأساليب ومعلمات المسار والحمولات ورموز الحالة للتطبيق الذي تتصل به. يقوم الخادم بتجميع مجموعاته في apps/sidecar/src/layers.ts; يتم تجميع العقد المشترك في packages/api/src/index.ts.

المصادقة والهوية

تتطلب الطرق المحمية Authorization: Bearer <token>. يتلقى سطح المكتب رمزًا مميزًا جديدًا للتطبيق عند بدء تشغيل السايدكار. GET /api/health هو مسبار الصحة العامة؛ محلي /health و /version محمية. تتم مقارنة الرموز المميزة لحامل التطبيق بمقارنة آمنة للتوقيت.

اختياري x-session-token يحمل جلسة حساب JWT. يقبل الرمز المميز لحامله التطبيق المحلي؛ تختار الجلسة حساب التمثيل الخاص بها. تعود الجلسة الغائبة أو منتهية الصلاحية أو غير الصالحة أو المعزولة إلى ملف التعريف المحلي للتثبيت. يقوم معالجو الموارد بعد ذلك بالتحقق من الملكية أو الوصول إلى المؤسسة من خلال مساعدي ترخيص المستودع.

يعترف رمز الجسر ذو النطاق فقط GET /api/ai/actions و POST /api/ai/actions/invoke. ولا يمنح الوصول إلى مشروع CRUD أو إعدادات بيانات الاعتماد أو مسارات HTTP الأخرى. يتم فحص مشروعه ونطاق القراءة/الكتابة مرة أخرى بواسطة جسر الإجراء.

عائلات الموارد

• تصميم: المشاريع والرسومات والمكونات وإصدارات الرسم واستيراد/تصدير الكيان وتحليل CAD الدقيق وتصدير STEP وتحليل التجميع.
• تصنيع: مسارات الأدوات والإصدارات، والتعليقات، واقتراحات المولد، والتحليل، والتحقق من إعادة التشغيل، ووظائف التصنيع الأصلية، والمواد، والأدوات، وتكوينات الآلة، وعناصر المكتبة، وتكاليف الإنتاج.
• مساعد: مقدمو الخدمة، وبيانات الاعتماد، والنماذج، والجلسات، ودورات البث، وضوابط الجلسة، والإجراءات، وذاكرة المشروع، وسياق مساحة العمل، والنصائح عديمة الحالة.
• تعاون: الفروع، والالتزامات، والاختلافات، وطلبات السحب، والمراجعات، ومرايا GitHub، وملفات سير العمل وعمليات التشغيل، والأحداث المباشرة، والاقتران المصاحب.
• خدمات التطبيق: المستخدمون، والمصادقة، والمؤسسات، والإشعارات، والملفات، والمكونات الإضافية، والفوترة، والتحليلات، وقائمة الانتظار، وتكوين MCP، وتخزين قيمة المفتاح المحلي.

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

ردود الفعل والإخفاقات

يتم تعيين الأخطاء الشائعة ذات العلامات إلى HTTP 400 (BadRequest), 401 (Unauthorized), 403 (Forbidden), 404 (NotFound), 405 (MethodNotAllowed), 409 (Conflict)، و 500 (InternalError). تحمل مخططاتهم المعلنة مخططًا يمكن قراءته بواسطة الإنسان message. تستخدم بعض المجموعات مظروفًا به success: false, message، و errors; عدد صغير يستخدم error مجال.

يمكن أن تكون استجابات النجاح عبارة عن سجل أو مصفوفة أو قيمة فارغة أو مظروف. Envelope يشمل success, message، و data; EnvelopeOpt يجعل الرسالة اختيارية. تعلن نقاط نهاية الإنشاء بوضوح عن 201 حيثما كان ذلك مناسبًا. لا تستنتج النجاح من حقل JSON فقط دون التحقق من حالة HTTP ومخطط نقطة النهاية.

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

استخدم العميل المشترك

ApiClient.layer يأخذ أ baseUrl والتطبيق token. فهو يوفر وسيلة نقل الجلب والبرمجيات الوسيطة لترخيص العميل. وأساليبها مستمدة مباشرة من Api، لذلك يغطي هذا العميل أيضًا العمليات المحذوفة عن طريق إنشاء التعليمات البرمجية.

import { ApiClient } from "@cadcamfun/api"
import { Effect } from "effect"

const projects = Effect.gen(function* () {
  const api = yield* ApiClient
  return yield* api.projects.list()
}).pipe(Effect.provide(ApiClient.layer({ baseUrl, token })))

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

طلبات التصميم والتصنيع

استخدام عمليات المشروع /api/projects; تحتوي الرسومات ومسارات الأدوات على مجموعاتها الخاصة ومسارات التفاصيل. POST /api/toolpaths/generate ينتج G-code وبيانات البرنامج التي تم تحليلها والتحذيرات والإحصائيات من إعدادات المولد والهندسة. /suggest, /parse، و /verify كشف نصيحة المعلمة، وتفسير G-code، وإعادة عرض المخزون. لا تقوم هذه الحسابات بإنشاء مسار أدوات محفوظ.

POST /api/toolpaths/manufacture يقبل لقطة CAD تم إصدارها ويعيد نتيجة kernel مع NC، وتعيينات الأدوات، وقطع البيانات، والمطالبات، والمشكلات، ومستوى الإصدار. احفظ المستند الناتج بشكل منفصل من خلال عملية إنشاء مسار الأدوات أو تحديثه. يرى الاجهزة للتحقق من صحة الأدلة أثناء الثبات.

POST /api/cad/exact/analyze, /step، و /assembly قبول العناصر الصريحة أو معرف الرسم المخزن. تؤدي قراءة الرسم المخزن إلى تطبيق عمليات التحقق العادية من الوصول إلى الرسم للمتصل.

الجري والانتعاش

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

مخططات أحداث الذكاء الاصطناعي موجودة packages/api/src/ai-events.ts و packages/ai/src/events.ts. تستخدم الأحداث المباشرة العامة مجموعة الأحداث. تتطلب التنزيلات الثنائية واستجابات تمهيد مكون JavaScript الإضافي ونصوص خطاف الويب الأولية الموقعة معالجة النقل الخاصة بها.

قم بإدراج المسارات التي تستخدمها الصفحة التي تستخدم نتائجها page و limit معلمات الاستعلام. بالنسبة لتكوينات الجهاز page الإعدادات الافتراضية هي 1، limit الافتراضي هو 20 ويتم تثبيته على 1–100، وتحمل الاستجابة pagination مع page, limit, total، و totalPages (apps/sidecar/src/http/machine-configs.ts). تحقق من الصفحة المرجعية لكل مجموعة لمعرفة المعلمات التي تعلن عنها بالفعل.

حزم SDK التي تم إنشاؤها

@cadcamfun/httpapi-codegen يعكس مجموعات HttpApi في بيانات تعريف العملية والعملاء الذين تم إنشاؤها. يكتب منشئ واجهة برمجة التطبيقات Promise SDK إلى packages/api/src/sdk/generated وتأثير العملاء على packages/api/src/client/generated. يتم تصدير Promise SDK العام بتنسيق @cadcamfun/api/sdk.

bun run --filter @cadcamfun/api generate
bun run --filter @cadcamfun/api generate:check

كلا الهدفين اللذين تم إنشاؤهما يحذفان التحميل متعدد الأجزاء للملف الشخصي، وتثبيت البرنامج المساعد متعدد الأجزاء، وإنشاء MCP بمخططات نجاح متعددة، وتحديث MCP بمعرفات متصادمة، وإنشاء مسار أدوات المشروع بأسماء إدخال مكررة، وملف البرنامج المساعد الذي يعمل مع رؤوس الدفق. يحذف هدف Promise أيضًا خطافات الويب الأولية لـ Stripe، وJavaScript bootstrap الإضافي، وتنزيل الملفات الثنائية، وطلبات الإنشاء/الاقتراح الخاصة بالمولد. وهذه الإغفالات واضحة في packages/api/scripts/generate-clients.ts; استخدام العميل المتعاقد أو وسيلة النقل الخام المناسبة لتلك العمليات.

منظمة المصدر

groups/ يحتوي على عقود الموارد. تأتي الهندسة المشتركة ومخططات CAM من @cadcamfun/core; cad-exact.ts, cam-kernel.ts، و cam-program.ts وصف نتائج CAD/CAM الغنية والمستندات المحمولة. client.ts يبني عميل العقد، في حين يمتلك البرنامج النصي للجيل الأهداف التي تم إنشاؤها وقوائم الإغفال.

قواعد التكامل

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

مرجع الموارد

325 عمليات عير 232 مسارات و 35 مجموعات الموارد، مع 56 مخططات مسماة. تسرد كل صفحة مورد عملياتها وتظهر معلمات المسار/الاستعلام/الرأس المعلنة، والحقول المطلوبة والاختيارية، والقيم الخالية، وأنواع المحتوى، وحالات النجاح والخطأ، والمخططات الكاملة.

يتم إصدار البيانات من packages/api/src/index.ts، وهو نفس عقد HttpApi المؤلف الذي يستخدمه العملاء والسايدكار. تصف الصفحات العقد المفحوص؛ فحص الخادم قيد التشغيل /api/openapi.json إذا قمت بالاتصال بإصدار آخر.

تنزيل OpenAPI JSON · متابعة الطلبات مع الاستجابات الملتقطة

اصطلاحات الاتصال والطلب

يتم توفير واجهة برمجة التطبيقات (API) بواسطة السايدكار المحلية بدلاً من نقطة نهاية مستضافة ثابتة. تحصل Tauri على عنوان URL للاسترجاع المحدد ديناميكيًا ورمز الإطلاق المميز. تعلن السايدكار التي تم تشغيلها يدويًا عن منفذها في حدث جاهز لـ JSON. يتصل عميل الهاتف المحمول المقترن عبر بوابة HTTPS التي تم تكوينها بدلاً من ذلك.

curl --silent --show-error "$CADCAMFUN_URL/api/projects" \
  --header "Authorization: Bearer $CADCAMFUN_TOKEN"

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

الصيانة المرجعية التي تم إنشاؤها

packages/web/script/generate-api-reference.mjs يقرأ العقد المؤلف باستخدام تطبيق Effect المثبت لحزمة API ويكتب المرجع JSON. يستهلك عامل التوثيق المحتوى الذي تم إنشاؤه؛ ولا يقوم بتهيئة خادم التطبيق للرد على طلبات التوثيق.

bun run generate:api-reference
bun run check:api-reference
bun run check:docs-index

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

وصفات التكامل

ابدأ بـ طلبات HTTP التي تم التقاطها لنرى كيف يستجيب إنشاء المشروع، والتحقق من صحة الأعمال، ورفض حامله، والسجلات ذات الصلة، واستمرارية القيمة الأساسية. يستخدم تكامل العميل المكتوب لإعادة إنتاج تلك العمليات باستخدام Promise SDK أو عميل Effect والتعامل مع قنوات الفشل المميزة الخاصة بها.

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

العمليات لكل مجموعة موارد

يعلن العقد حاليًا عن 270 عمليات في 34 مجموعات، كلها تحت مجموعة واحدة bearer نظام أمان HTTP. العملية الوحيدة التي لا يوجد فيها ضمان لحاملها هي مسبار الصحة العامة. يتم حساب الجدول من مستند OpenAPI الذي تم إنشاؤه: العمليات لكل مجموعة، وطرق HTTP المستخدمة، وعدد المسارات المميزة، ومسار تمثيلي واحد.

رموز الحالة عبر العقد

إن حساب كل استجابة معلنة مرة واحدة لكل عملية يعطي هذه الصورة لما يجب أن يكون العميل جاهزًا لفك تشفيره:

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

{ "_tag": "NotFound", "message": "Project not found" }

{ "_tag": "EnvNotFound", "success": false, "message": "Material not found", "errors": null }

{ "_tag": "KeyedInternal", "error": "Failed to load components" }

مظاريف النجاح تعكس مظروف الخطأ: { success: true, message, data }، أين data ربما null. ال EnvelopeOpt يتجاهل البديل message عندما لم يقدم المعالج واحدة. قم بالتشغيل _tag وليس على حضور message أو error.

كيف تتم معالجة الطلب

1. يطابق جهاز التوجيه الطريقة والمسار. الطرق غير المعروفة لا تصل أبدًا إلى المعالج.
2. تقوم البرمجيات الوسيطة لحاملها بمقارنة الرمز المميز في وقت ثابت. يؤدي الرمز المفقود أو الخاطئ إلى إيقاف الطلب باستخدام 401 قبل أي فك تشفير.
3. يتم فك تشفير المسار والاستعلام والرؤوس والنص وفقًا لمخططات العملية. تصبح المشاكل الهيكلية 400 بدون تشغيل كود العمل.
4. يقوم المعالج بحل الحساب النشط، والتحقق من الملكية أو عضوية المؤسسة (403/404) وتشغيل الخدمة.
5. يتم ترميز النتيجة بمخطط النجاح المعلن، أو الفشل بمخطط الخطأ الموسوم وحالته.

الاستجابات التي ليست JSON

يرفض Promise SDK الذي تم إنشاؤه استجابة البث التي لا يكون نوع محتواها كذلك text/event-stream مع ClientError("UnsupportedContentType")، وحدث SSE واحد أكبر من 16 MiB مع SseEventTooLarge.

استدعاء API بدون عميل

type TaggedError = { _tag: string; message?: string; error?: string }

async function call<T>(base: string, token: string, method: string, path: string, body?: unknown): Promise<T> {
  const response = await fetch(new URL(path, base), {
    method,
    headers: {
      authorization: `Bearer ${token}`,
      ...(body === undefined ? {} : { "content-type": "application/json" }),
    },
    body: body === undefined ? undefined : JSON.stringify(body),
  })
  if (response.status === 204) return undefined as T
  const payload = await response.json()
  if (!response.ok) {
    const failure = payload as TaggedError
    throw new Error(`${response.status} ${failure._tag}: ${failure.message ?? failure.error}`)
  }
  return payload as T
}

const project = await call<{ id: string; name: string }>(
  process.env.CADCAMFUN_URL!, process.env.CADCAMFUN_TOKEN!,
  "POST", "/api/projects", { name: "Bracket" },
)

تفضيل العملاء الذين تم إنشاؤهم في TypeScript: فهم يعرفون حالة نجاح كل عملية وحالات الخطأ المعلنة، ويتعاملون مع أي شيء آخر على أنه UnexpectedStatus بدلا من التخمين.

في 3د