Convenzioni ingegneristiche

Struttura della fonte

Utilizza identificatori, commenti, documentazione e messaggi di commit in inglese. I progetti TypeScript utilizzano un controllo rigoroso; le interfacce pubbliche dovrebbero preservare i tipi espliciti e decodificare i valori esterni invece di propagare dati non controllati. I manifesti dei pacchetti espongono i punti di ingresso dell'origine e i moduli dell'applicazione utilizzano le importazioni relative appropriate al loro strumento di creazione.

Desktop presenta schermate di gruppo, componenti, negozi e assistenti in apps/desktop/src/features. Gli adattatori di percorso rimangono inseriti src/pages, mentre la shell dell'applicazione e la configurazione del client risiedono in src/app. La geometria principale rimane indipendente dallo stato dell'interfaccia utente e dall'accesso al database.

Geometria e unità di output

La geometria delle entità analitiche e dei vettori principali utilizza millimetri e radianti. Il posizionamento della scena, i controlli delle funzioni e i campi dell'asse rotante CAM hanno convenzioni angolari specifiche del contratto, inclusi i gradi. Segui ogni schema quando ti adatti tra loro. La conversione della visualizzazione dell'interfaccia utente appartiene al limite della visualizzazione. Le operazioni di lavorazione utilizzano inoltre parametri di avanzamento, mandrino, profondità e sicurezza con significati definiti dai relativi schemi; un numero nudo non dovrebbe mai acquisire un'unità implicita solo da un'etichetta.

Il codice G pubblica la conversione dell'output specifica del controller e la formattazione dei numeri. L'emettitore condiviso espone formatNumber, arrotonda al conteggio decimale richiesto, normalizza lo zero negativo e tiene traccia della posizione emessa. La formattazione del feed può omettere una parte frazionaria per i valori integrali. Utilizzare l'emettitore anziché formattare in modo indipendente le parole di movimento in ciascun chiamante.

Mantenere distinte le prove del modello e la geometria di visualizzazione approssimativa. Una superficie tassellata è utile per il rendering e l'analisi, ma non dimostra di per sé che l'operazione B-rep esatta sia riuscita.

Servizi di effetto

I servizi si estendono Context.Service ed esporre metodi di restituzione degli effetti tipizzati. Un livello costruisce l'implementazione e fornisce le sue dipendenze. apps/sidecar/src/layers.ts è il punto di integrazione per repository, servizi, gestori, autorizzazione e configurazione di runtime.

Le risorse con una durata, come gli handle SQLite, vengono acquisite e rilasciate nell'ambito del livello proprietario. Utilizzo Effect.try o Effect.tryPromise tradurre le eccezioni straniere in errori significativi. I nomi stabili delle operazioni negli errori e nella traccia rendono gli errori diagnosticabili senza associare i chiamanti a un driver di archiviazione.

La composizione dei livelli è importante: i livelli fratelli uniti insieme non si forniscono automaticamente servizi a vicenda. La registrazione delle fasi del flusso di lavoro Sidecar è stratificata dopo il corridore di cui ha bisogno; il passaggio AI viene registrato dove è disponibile il servizio AI.

Validazione ed errori

Gli input e gli output HTTP sono dichiarati in packages/api/src/groups. Convalida l'input sconosciuto a questi limiti. Il contratto include errori di messaggio semplice, buste di successo/errore e alcuni corpi di errore con chiave; preservare lo stato dichiarato dell'endpoint e la rappresentazione della risposta.

Gli errori relativi a HTTP utilizzano schemi di effetti e annotazioni di stato. Per esempio, BadRequest, Unauthorized, NotFound, e Conflict sono dichiarati in packages/api/src/errors.ts. Gli errori interni del database portano avanti un'operazione e causano DatabaseError. Mappare gli errori interni al confine HTTP anziché esporre i dettagli del driver ai client.

Rigenerare i clienti dopo un cambio di contratto con bun run generate. Controlla l'output impegnato con bun run generate:check. Le cartelle generate sono output; la generazione esclude esplicitamente gli endpoint che una destinazione non può rappresentare.

Persistenza e configurazione

I repository delle applicazioni utilizzano il file Database servizio da @cadcamfun/db e il suo query(operation, run) aiutante. Modifica packages/db/src/schema.ts prima di generare migrazioni. Esaminare insieme l'SQL e i metadati generati; non eseguire un esperimento di schema distruttivo sul database di un utente.

Il sidecar legge la configurazione apps/sidecar/src/config.ts e lo attraversa AppConfigService. Le credenziali utilizzano valori redatti laddove il servizio li richiede. Mantieni i valori segreti del token e del provider fuori da log, documentazione e output di risoluzione dei problemi. La shell nativa fornisce il proprio token di lancio e percorsi di archiviazione.

Lo Studio della documentazione è uno strumento locale separato con la propria selezione del percorso packages/web/script/studio-server.ts. Non dare per scontato che il percorso del database o la sessione di accesso corrispondano al desktop in esecuzione.

Verifica

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

Scegli i controlli che esercitano il confine interessato. I cambiamenti puri del kernel richiedono casi di regressione numerica e geometrica. Le modifiche HTTP richiedono la copertura del gestore e dello schema. Le modifiche alla documentazione richiedono percorsi validi, ancoraggi, esempi e una creazione del sito di successo. Lo è un test completo dell'area di lavoro bun run test, che include pacchetti, app e script.

Campi facoltativi, valori null e valori di trasporto

Un campo facoltativo può essere omesso. Un campo nullable può contenere esplicitamente null. Sono proprietà separate: il contratto a progetto lo richiede description nelle righe restituite consentendo null e una richiesta di creazione consente l'omissione di quel campo. Conserva queste distinzioni durante la creazione di client o l'applicazione di patch ai documenti salvati.

Anche la convalida del trasporto è distinta dalla convalida aziendale. Il payload di creazione del progetto consente un nome omesso a livello di schema, ma il gestore restituisce 400 con Project name is required se manca o è vuoto. Un tipo generato da solo non può stabilire che un'operazione sarà ammessa per una risorsa o un conto corrente esistente.

I parametri di query HTTP sono testo codificato. Utilizza i campi di query dichiarati del client o la codifica URL anziché concatenare l'input utente arbitrario in un URL. Codifica una chiave o un identificatore di progetto come un singolo segmento di percorso e invia i token di connessione nelle intestazioni anziché nei collegamenti copiati.

Il riferimento API progetti mostra questi campi e codici di stato; IL procedura dettagliata catturata dimostra il risultato della convalida del gestore.

Conservare la documentazione eseguibile

Scrivi un esempio confrontandolo esattamente con la superficie pubblica a cui fa riferimento. L'SDK Promise e il client Effect completo basato su contratto hanno metodi/forme di input e copertura diversi. Una richiesta di generatore guidata dalle impostazioni è diversa da una richiesta del kernel nativo e un programma generato è diverso da un record del percorso utensile salvato.

Lo snapshot di riferimento API viene generato dal contratto dell'applicazione. Dopo aver modificato un endpoint, rigenerarlo all'interno dello spazio di lavoro Web con bun run generate:api-reference. Correre bun run check:api-reference per confrontarlo con la fonte attuale. Il raggruppamento delle risorse, il testo dell'articolo, la navigazione e il recupero dell'assistente devono comunque descrivere fedelmente il contratto.

Quando si documenta una risposta acquisita da un'esecuzione isolata, identificare eventuali ID normalizzati, timestamp o campi omessi. Etichettare i modelli di richiesta come modelli. Non presentare un identificatore inventato o un esempio di schema non eseguito come risposta di produzione osservata.

Pattern di effetti utilizzati ovunque

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

• Le chiavi del servizio hanno uno spazio dei nomi: "cadcamfun/Database", "cadcamfun/AppConfig", "cadcamfun/ApiClient".
• Gli errori sono Data.TaggedError servizi interni e Schema.TaggedError con un httpApiStatus al confine HTTP. I gestori mappano il primo al secondo.
• Risorse con utilizzo permanente Effect.acquireRelease quindi si chiudono quando si chiude l'ambito del livello.
• Utilizzo delle funzioni con nome Effect.fn("area.name") quindi le tracce portano, ad esempio, un nome span leggibile cam.runKernelRequest.
• La configurazione viene letta una volta, in AppConfigService; nessun altro modulo legge process.env nel sidecar.

Regole di denominazione e layout

Nel 3D