الاتفاقيات الهندسية

هيكل المصدر

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

يتميز سطح المكتب بشاشات جماعية ومكونات ومتاجر ومساعدين ضمنها apps/desktop/src/features. تبقى محولات المسار في مكانها src/pages، أثناء وجود غلاف التطبيق وإعداد العميل src/app. تظل الهندسة الأساسية مستقلة عن حالة واجهة المستخدم والوصول إلى قاعدة البيانات.

وحدات الهندسة والإخراج

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

تمتلك منشورات G-code تحويل الإخراج الخاص بوحدة التحكم وتنسيق الأرقام. يكشف الباعث المشترك formatNumber، للتقريب إلى العدد العشري المطلوب، وتطبيع الصفر السالب، وتتبع الموضع المنبعث. قد يؤدي تنسيق الخلاصة إلى حذف جزء كسري للقيم المتكاملة. استخدم الباعث بدلاً من تنسيق الكلمات المتحركة بشكل مستقل في كل متصل.

حافظ على تميز أدلة النموذج وهندسة العرض التقريبية. يعد السطح المغطى بالفسيفساء مفيدًا في العرض والتحليل ولكنه لا يثبت في حد ذاته نجاح عملية B-rep الدقيقة.

خدمات التأثير

تمتد الخدمات Context.Service وكشف أساليب إرجاع التأثير المكتوبة. تقوم الطبقة ببناء التنفيذ وتوفير تبعياته. apps/sidecar/src/layers.ts هي نقطة التكامل للمستودعات والخدمات والمعالجات والترخيص وتكوين وقت التشغيل.

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

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

التحقق من الصحة والأخطاء

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

تستخدم الأخطاء التي تواجه HTTP مخططات التأثير والتعليقات التوضيحية للحالة. على سبيل المثال، BadRequest, Unauthorized, NotFound، و Conflict يتم الإعلان عنها في packages/api/src/errors.ts. تؤدي حالات فشل قاعدة البيانات الداخلية إلى حدوث عملية ما وتتسبب في حدوثها DatabaseError. قم بتعيين حالات الفشل الداخلية عند حدود HTTP بدلاً من كشف تفاصيل برنامج التشغيل للعملاء.

تجديد العملاء بعد تغيير العقد معهم bun run generate. تحقق من الإخراج الملتزم به bun run generate:check. المجلدات التي تم إنشاؤها هي مخرجات. يستبعد الإنشاء بشكل صريح نقاط النهاية التي لا يمكن للهدف تمثيلها.

الثبات والتكوين

تستخدم مستودعات التطبيقات Database الخدمة من @cadcamfun/db ولها query(operation, run) المساعد. يتغير packages/db/src/schema.ts قبل توليد الهجرات. مراجعة SQL والبيانات الوصفية التي تم إنشاؤها معًا؛ لا تقم بتشغيل تجربة مخطط تدميرية على قاعدة بيانات المستخدم.

يقرأ السايدكار التكوين في apps/sidecar/src/config.ts ويمر بها AppConfigService. تستخدم بيانات الاعتماد قيمًا منقحة عندما تتطلبها الخدمة. احتفظ بالرمز المميز والقيم السرية للموفر خارج السجلات والوثائق ومخرجات استكشاف الأخطاء وإصلاحها. توفر الصدفة الأصلية رمز الإطلاق المميز ومسارات التخزين الخاصة بها.

يعد استوديو التوثيق أداة محلية منفصلة مع تحديد المسار الخاص بها packages/web/script/studio-server.ts. لا تفترض أن مسار قاعدة البيانات أو جلسة تسجيل الدخول الخاصة به تتطابق مع سطح المكتب قيد التشغيل.

تَحَقّق

bun test packages/core
bun run --filter @cadcamfun/core typecheck
bun run generate:check

# Documentation content and build
bun test packages/web/test
bun run --filter @cadcamfun/web typecheck
bun run --filter @cadcamfun/web build

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

الحقول الاختيارية، والقيم الخالية، وقيم النقل

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

يختلف التحقق من صحة النقل أيضًا عن التحقق من صحة الأعمال. تسمح حمولة إنشاء المشروع باسم محذوف على مستوى المخطط، لكن يقوم المعالج بإرجاع 400 مع Project name is required إذا كانت مفقودة أو فارغة. لا يمكن للنوع الذي تم إنشاؤه بمفرده إثبات أنه سيتم قبول العملية لمورد موجود أو حساب جاري.

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

ال مرجع API للمشاريع يعرض هذه الحقول ورموز الحالة؛ ال تجول تم التقاطه يوضح نتيجة التحقق من صحة المعالج.

الحفاظ على الوثائق القابلة للتنفيذ

اكتب مثالاً على السطح العام الذي يذكره بالضبط. لدى Promise SDK وعميل Effect الكامل القائم على العقد أشكال وتغطية مختلفة للطرق/الإدخال. يختلف طلب المولد المعتمد على الإعدادات عن طلب kernel الأصلي، ويختلف البرنامج الذي تم إنشاؤه عن سجل مسار الأدوات المحفوظ.

يتم إنشاء اللقطة المرجعية لواجهة برمجة التطبيقات (API) من عقد التطبيق. بعد تغيير نقطة النهاية، قم بإعادة إنشائها داخل مساحة عمل الويب باستخدام bun run generate:api-reference. يجري bun run check:api-reference لمقارنتها مع المصدر الحالي. يجب أن يظل تجميع الموارد ونص المقالة والتنقل والاسترجاع المساعد يصف هذا العقد بأمانة.

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

أنماط التأثير المستخدمة في جميع أنحاء

import { Context, Data, Effect, Layer } from "effect"
import { AppConfigService } from "../config.ts"

export class StorageError extends Data.TaggedError("StorageError")<{
  readonly operation: string
  readonly cause: unknown
}> {}

export class Storage extends Context.Service<Storage, {
  readonly read: (key: string) => Effect.Effect<Uint8Array, StorageError>
}>()("cadcamfun/Storage") {
  static readonly layer = Layer.effect(Storage, Effect.gen(function* () {
    const config = yield* AppConfigService       // dependencies come from the context
    return Storage.of({
      read: (key) => Effect.tryPromise({
        try: () => Bun.file(`${config.dataDir}/storage/${key}`).bytes(),
        catch: (cause) => new StorageError({ operation: "read", cause }),
      }),
    })
  }))
}

• مفاتيح الخدمة ذات مساحة اسم: "cadcamfun/Database", "cadcamfun/AppConfig", "cadcamfun/ApiClient".
• الأخطاء هي Data.TaggedError داخل الخدمات و Schema.TaggedError مع httpApiStatus على حدود HTTP. يقوم المعالجون بتعيين الأول إلى الثاني.
• الموارد مع استخدام مدى الحياة Effect.acquireRelease لذلك يتم إغلاقها عند إغلاق نطاق الطبقة.
• استخدام الوظائف المسماة Effect.fn("area.name") لذا فإن الآثار تحمل اسم نطاق قابل للقراءة، على سبيل المثال cam.runKernelRequest.
• تتم قراءة التكوين مرة واحدة، في AppConfigService; لا يقرأ أي وحدة أخرى process.env في السايدكار.

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

في 3د