Technische Konventionen

Quellstruktur

Verwenden Sie englische Bezeichner, Kommentare, Dokumentationen und Commit-Nachrichten. TypeScript-Projekte verwenden eine strenge Prüfung; Öffentliche Schnittstellen sollten explizite Typen beibehalten und externe Werte dekodieren, anstatt ungeprüfte Daten weiterzugeben. Paketmanifeste legen Quelleneinstiegspunkte offen, und Anwendungsmodule verwenden relative Importe, die für ihr Build-Tool geeignet sind.

Desktop bietet Gruppenbildschirme, Komponenten, Geschäfte und Helfer unten apps/desktop/src/features. Routenadapter bleiben drin src/pages, während die Anwendungs-Shell und das Client-Setup darin leben src/app. Die Kerngeometrie bleibt unabhängig vom UI-Status und Datenbankzugriff.

Geometrie und Ausgabeeinheiten

Die Kernvektor- und Analyseelementgeometrie verwendet Millimeter und Bogenmaß. Für die Szenenplatzierung, Funktionssteuerung und CAM-Rotationsachsenfelder gelten vertragsspezifische Winkelkonventionen, einschließlich Grad. Befolgen Sie bei der Anpassung zwischen ihnen jedes Schema. Die Konvertierung der UI-Anzeige gehört an die Anzeigegrenze. Bearbeitungsvorgänge verwenden zusätzlich Vorschub-, Spindel-, Tiefen- und Abstandsparameter mit durch ihre Schemata definierten Bedeutungen; Eine bloße Zahl sollte niemals allein durch eine Bezeichnung eine implizite Einheit erhalten.

G-Code stellt eine eigene Controller-spezifische Ausgabekonvertierung und Zahlenformatierung bereit. Der gemeinsame Emitter macht verfügbar formatNumber, rundet auf die angeforderte Dezimalzahl, normalisiert negative Nullen und verfolgt die ausgegebene Position. Bei der Feedformatierung wird möglicherweise ein Bruchteil für ganzzahlige Werte weggelassen. Verwenden Sie den Emitter, anstatt Bewegungswörter in jedem Aufrufer unabhängig zu formatieren.

Sorgen Sie dafür, dass Modellnachweise und ungefähre Anzeigegeometrie voneinander getrennt sind. Eine mosaikartige Oberfläche ist für das Rendern und Analysieren nützlich, beweist jedoch nicht, dass eine exakte B-Rep-Operation erfolgreich war.

Effektdienstleistungen

Dienstleistungen erweitern Context.Service und machen Sie typisierte Methoden verfügbar, die einen Effekt zurückgeben. Eine Schicht erstellt die Implementierung und stellt ihre Abhängigkeiten bereit. apps/sidecar/src/layers.ts ist der Integrationspunkt für Repositorys, Dienste, Handler, Autorisierung und Laufzeitkonfiguration.

Ressourcen mit einer Lebensdauer, wie z. B. SQLite-Handles, werden innerhalb des Geltungsbereichs der besitzenden Ebene erworben und freigegeben. Verwenden Effect.try oder Effect.tryPromise fremde Ausnahmen in sinnvolle Fehler zu übersetzen. Stabile Vorgangsnamen in Fehlern und Ablaufverfolgung machen Fehler diagnostizierbar, ohne Aufrufer an einen Speichertreiber zu koppeln.

Die Schichtzusammensetzung ist wichtig: Zusammengeführte Geschwisterschichten stellen einander nicht automatisch Dienste zur Verfügung. Die Registrierung der Sidecar-Workflow-Schritte ist nach dem benötigten Läufer geschichtet; Der AI-Schritt wird dort registriert, wo der AI-Dienst verfügbar ist.

Validierung und Fehler

HTTP-Eingaben und -Ausgaben werden in deklariert packages/api/src/groups. Validieren Sie unbekannte Eingaben an diesen Grenzen. Der Vertrag umfasst einfache Nachrichtenfehler, Erfolgs-/Fehlerumschläge und einige verschlüsselte Fehlertexte; Behalten Sie den deklarierten Status und die Antwortdarstellung des Endpunkts bei.

HTTP-bezogene Fehler verwenden Effektschemata und Statusanmerkungen. Zum Beispiel, BadRequest, Unauthorized, NotFound, und Conflict werden in deklariert packages/api/src/errors.ts. Interne Datenbankfehler führen zu einem Vorgang und verursachen Fehler DatabaseError. Ordnen Sie interne Fehler an der HTTP-Grenze zu, anstatt Treiberdetails für Clients offenzulegen.

Generieren Sie Kunden nach einer Vertragsänderung neu mit bun run generate. Überprüfen Sie die festgeschriebene Ausgabe mit bun run generate:check. Generierte Ordner sind Ausgaben; Die Generierung schließt Endpunkte explizit aus, die ein Ziel nicht darstellen kann.

Persistenz und Konfiguration

Anwendungsrepositorys verwenden die Database service von @cadcamfun/db und es ist query(operation, run) helfer. Ändern packages/db/src/schema.ts bevor Migrationen generiert werden. Überprüfen Sie generierte SQL- und Metadaten gemeinsam. Führen Sie kein destruktives Schemaexperiment für die Datenbank eines Benutzers durch.

Der Sidecar liest die Konfiguration ein apps/sidecar/src/config.ts und leitet es hindurch AppConfigService. Anmeldeinformationen verwenden geschwärzte Werte, wenn der Dienst sie benötigt. Halten Sie Token- und Provider-Geheimwerte aus Protokollen, Dokumentationen und Fehlerbehebungsausgaben fern. Die native Shell stellt ihr eigenes Starttoken und ihre eigenen Speicherpfade bereit.

Das Dokumentationsstudio ist ein separates lokales Tool mit eigener Pfadauswahl in packages/web/script/studio-server.ts. Gehen Sie nicht davon aus, dass der Datenbankpfad oder die Anmeldesitzung mit dem ausgeführten Desktop übereinstimmt.

Überprüfung

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

Wählen Sie Prüfungen aus, die die betroffene Grenze überschreiten. Reine Kerneländerungen erfordern numerische und geometrische Regressionsfälle. HTTP-Änderungen erfordern Handler- und Schemaabdeckung. Für Dokumentationsänderungen sind gültige Routen, Anker, Beispiele und eine erfolgreiche Site-Erstellung erforderlich. Ein vollständiger Arbeitsbereich-Testlauf ist bun run test, das Pakete, Apps und Skripte umfasst.

Optionale Felder, Nullen und Transportwerte

Ein optionales Feld kann weggelassen werden. Ein Feld, das NULL-Werte zulässt, kann explizit enthalten null. Es handelt sich um separate Immobilien, wie es der Projektvertrag erfordert description in zurückgegebenen Zeilen, während Null zulässig ist, und eine Erstellungsanforderung erlaubt das Weglassen dieses Felds. Behalten Sie diese Unterscheidungen beim Erstellen von Clients oder beim Patchen gespeicherter Dokumente bei.

Die Transportvalidierung unterscheidet sich auch von der Geschäftsvalidierung. Die Projekterstellungsnutzlast lässt einen weggelassenen Namen auf Schemaebene zu, aber der Handler gibt 400 mit zurück Project name is required wenn es fehlt oder leer ist. Ein generierter Typ allein kann nicht belegen, dass ein Vorgang für eine vorhandene Ressource oder ein aktuelles Konto zugelassen wird.

HTTP-Abfrageparameter sind codierter Text. Verwenden Sie die vom Client deklarierten Abfragefelder oder die URL-Codierung, anstatt beliebige Benutzereingaben in einer URL zu verketten. Codieren Sie einen Schlüssel oder eine Projektkennung als einzelnes Pfadsegment und senden Sie Bearer-Tokens in Headern statt in kopierten Links.

Der aPI-Referenz für Projekte zeigt diese Felder und Statuscodes an; Die erfasste Komplettlösung demonstriert das Validierungsergebnis des Handlers.

Pflegen Sie die ausführbare Dokumentation

Schreiben Sie ein Beispiel für die genaue öffentliche Oberfläche, die darin genannt wird. Das Promise SDK und der vollständige vertragsbasierte Effect-Client verfügen über unterschiedliche Methoden-/Eingabeformen und -abdeckungen. Eine einstellungsgesteuerte Generatoranforderung unterscheidet sich von einer nativen Kernel-Anfrage und ein generiertes Programm unterscheidet sich von einem gespeicherten Werkzeugwegdatensatz.

Der API-Referenz-Snapshot wird aus dem Anwendungsvertrag generiert. Nachdem Sie einen Endpunkt geändert haben, generieren Sie ihn im Web-Workspace mit neu bun run generate:api-reference. Laufen bun run check:api-reference um es mit der aktuellen Quelle zu vergleichen. Ressourcengruppierung, Artikeltext, Navigation und Assistentenabruf müssen diesen Vertrag dennoch getreu beschreiben.

Identifizieren Sie beim Dokumentieren einer aus einem isolierten Lauf erfassten Antwort alle normalisierten IDs, Zeitstempel oder ausgelassenen Felder. Kennzeichnen Sie Anfragevorlagen als Vorlagen. Präsentieren Sie keinen erfundenen Bezeichner oder ein nicht ausgeführtes Schemabeispiel als beobachtete Produktionsreaktion.

Durchgehend verwendete Effektmuster

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 }),
      }),
    })
  }))
}

• Dienstschlüssel haben einen Namensraum: "cadcamfun/Database", "cadcamfun/AppConfig", "cadcamfun/ApiClient".
• Fehler sind Data.TaggedError insider-Dienstleistungen und Schema.TaggedError mit einem httpApiStatus an der HTTP-Grenze. Handler ordnen das erste dem zweiten zu.
• Ressourcen mit lebenslanger Nutzung Effect.acquireRelease sie werden also geschlossen, wenn der Geltungsbereich der Ebene geschlossen wird.
• Verwendung benannter Funktionen Effect.fn("area.name") daher tragen Traces beispielsweise einen lesbaren Span-Namen cam.runKernelRequest.
• Die Konfiguration wird einmal eingelesen AppConfigService; kein anderes Modul liest process.env im Sidecar.

Benennungs- und Layoutregeln

In 3D