इंजीनियरिंग सम्मेलन

स्रोत संरचना

अंग्रेजी पहचानकर्ताओं, टिप्पणियों, दस्तावेज़ीकरण और प्रतिबद्ध संदेशों का उपयोग करें। टाइपस्क्रिप्ट प्रोजेक्ट सख्त जाँच का उपयोग करते हैं; सार्वजनिक इंटरफेस को अनियंत्रित डेटा को प्रचारित करने के बजाय स्पष्ट प्रकारों को संरक्षित करना चाहिए और बाहरी मूल्यों को डीकोड करना चाहिए। पैकेज मैनिफ़ेस्ट स्रोत प्रविष्टि बिंदुओं को उजागर करता है, और एप्लिकेशन मॉड्यूल अपने निर्माण उपकरण के लिए उपयुक्त सापेक्ष आयात का उपयोग करते हैं।

डेस्कटॉप में समूह स्क्रीन, घटक, स्टोर और हेल्पर शामिल हैं apps/desktop/src/features. रूट एडेप्टर अंदर रहते हैं src/pages, जबकि एप्लिकेशन शेल और क्लाइंट सेटअप रहते हैं src/app. कोर ज्योमेट्री यूआई स्थिति और डेटाबेस एक्सेस से स्वतंत्र रहती है।

ज्यामिति और आउटपुट इकाइयाँ

कोर वेक्टर और विश्लेषणात्मक इकाई ज्यामिति मिलीमीटर और रेडियन का उपयोग करती है। दृश्य प्लेसमेंट, सुविधा नियंत्रण और सीएएम रोटरी-अक्ष फ़ील्ड में डिग्री सहित अनुबंध-विशिष्ट कोण सम्मेलन होते हैं। उनके बीच अनुकूलन करते समय प्रत्येक स्कीम का पालन करें। यूआई डिस्प्ले रूपांतरण डिस्प्ले सीमा पर होता है। मशीनिंग संचालन अतिरिक्त रूप से उनके स्कीमा द्वारा परिभाषित अर्थों के साथ फ़ीड, स्पिंडल, गहराई और निकासी मापदंडों का उपयोग करते हैं; एक खाली संख्या को कभी भी केवल एक लेबल से एक अंतर्निहित इकाई प्राप्त नहीं करनी चाहिए।

जी-कोड स्वयं नियंत्रक-विशिष्ट आउटपुट रूपांतरण और संख्या स्वरूपण पोस्ट करता है। साझा उत्सर्जक उजागर होता है formatNumber, अनुरोधित दशमलव गिनती के लिए राउंड, नकारात्मक शून्य को सामान्य करता है, और उत्सर्जित स्थिति को ट्रैक करता है। फ़ीड फ़ॉर्मेटिंग अभिन्न मानों के लिए भिन्नात्मक भाग को छोड़ सकता है। प्रत्येक कॉलर में गति शब्दों को स्वतंत्र रूप से स्वरूपित करने के बजाय एमिटर का उपयोग करें।

मॉडल साक्ष्य और अनुमानित प्रदर्शन ज्यामिति को अलग रखें। एक टेस्सेलेटेड सतह प्रतिपादन और विश्लेषण के लिए उपयोगी है लेकिन यह स्वयं यह साबित नहीं करती है कि सटीक बी-रेप ऑपरेशन सफल हुआ।

प्रभाव सेवाएँ

सेवाएँ विस्तारित होती हैं Context.Service और टाइप किए गए प्रभाव-वापसी तरीकों को उजागर करें। एक परत कार्यान्वयन का निर्माण करती है और उसकी निर्भरता की आपूर्ति करती है। apps/sidecar/src/layers.ts रिपॉजिटरी, सेवाओं, हैंडलर, प्राधिकरण और रनटाइम कॉन्फ़िगरेशन के लिए एकीकरण बिंदु है।

जीवनकाल वाले संसाधन, जैसे SQLite हैंडल, स्वामित्व परत के दायरे में प्राप्त और जारी किए जाते हैं। उपयोग Effect.try या Effect.tryPromise विदेशी अपवादों को सार्थक त्रुटियों में परिवर्तित करना। त्रुटियों और ट्रेसिंग में स्थिर ऑपरेशन नाम कॉलर्स को स्टोरेज ड्राइवर से जोड़े बिना विफलताओं का निदान करना संभव बनाते हैं।

परत संरचना मायने रखती है: सहोदर परतें एक साथ विलीन हो जाने पर स्वचालित रूप से एक दूसरे को सेवाएं प्रदान नहीं करती हैं। साइडकार वर्कफ़्लो चरण पंजीकरण को उस धावक के बाद स्तरित किया जाता है जिसकी उसे आवश्यकता होती है; एआई चरण वहां पंजीकृत है जहां एआई सेवा उपलब्ध है।

सत्यापन और त्रुटियाँ

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 एन्कोडिंग का उपयोग करें। किसी कुंजी या प्रोजेक्ट पहचानकर्ता को एकल पथ खंड के रूप में एन्कोड करें, और कॉपी किए गए लिंक के बजाय हेडर में बियरर टोकन भेजें।

The प्रोजेक्ट एपीआई संदर्भ ये फ़ील्ड और स्थिति कोड दिखाता है; पूर्वाभ्यास पर कब्जा कर लिया हैंडलर के सत्यापन परिणाम को प्रदर्शित करता है।

निष्पादन योग्य दस्तावेज़ बनाए रखें

जिस सार्वजनिक सतह का नाम इसमें दिया गया है, उसके सामने एक उदाहरण लिखें। प्रॉमिस एसडीके और पूर्ण अनुबंध-आधारित इफ़ेक्ट क्लाइंट के पास अलग-अलग विधि/इनपुट आकार और कवरेज हैं। सेटिंग्स-संचालित जेनरेटर अनुरोध मूल कर्नेल अनुरोध से भिन्न होता है, और जेनरेट किया गया प्रोग्राम सहेजे गए टूलपाथ रिकॉर्ड से भिन्न होता है।

एपीआई संदर्भ स्नैपशॉट एप्लिकेशन अनुबंध से उत्पन्न होता है। समापन बिंदु बदलने के बाद, इसे वेब कार्यक्षेत्र के अंदर पुन: उत्पन्न करें 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डी में