Conventions d'ingénierie

Structure des sources

Utilisez des identifiants, des commentaires, de la documentation et des messages de validation en anglais. Les projets TypeScript utilisent une vérification stricte ; les interfaces publiques doivent conserver les types explicites et décoder les valeurs externes au lieu de propager des données non contrôlées. Les manifestes de package exposent les points d’entrée source et les modules d’application utilisent des importations relatives appropriées à leur outil de génération.

Desktop propose des écrans de groupe, des composants, des magasins et des assistants sous apps/desktop/src/features. Les adaptateurs de routage restent en place src/pages, tandis que le shell de l'application et la configuration du client résident dans src/app. La géométrie de base reste indépendante de l'état de l'interface utilisateur et de l'accès à la base de données.

Géométrie et unités de sortie

La géométrie des vecteurs de base et des entités analytiques utilise des millimètres et des radians. Le placement de la scène, les commandes de fonctionnalités et les champs d'axe rotatif CAM ont des conventions d'angle spécifiques au contrat, y compris les degrés. Suivez chaque schéma lors de l'adaptation entre eux. La conversion d'affichage de l'interface utilisateur appartient à la limite d'affichage. Les opérations d'usinage utilisent en outre des paramètres d'avance, de broche, de profondeur et de dégagement avec des significations définies par leurs schémas ; un nombre nu ne devrait jamais acquérir une unité implicite à partir d’une seule étiquette.

Le G-code publie sa propre conversion de sortie et son formatage de nombres spécifiques au contrôleur. L'émetteur partagé expose formatNumber, arrondit au nombre décimal demandé, normalise le zéro négatif et suit la position émise. Le formatage du flux peut omettre une partie fractionnaire pour les valeurs entières. Utilisez l'émetteur plutôt que de formater indépendamment les mots de mouvement pour chaque appelant.

Gardez les preuves du modèle et la géométrie d'affichage approximative distinctes. Une surface pavée est utile pour le rendu et l'analyse, mais ne prouve pas en soi qu'une opération B-rep exacte a réussi.

Services d'effets

Les services s'étendent Context.Service et exposez les méthodes de retour d'effet typées. Une couche construit l'implémentation et fournit ses dépendances. apps/sidecar/src/layers.ts est le point d'intégration pour les référentiels, les services, les gestionnaires, les autorisations et la configuration du runtime.

Les ressources ayant une durée de vie, telles que les descripteurs SQLite, sont acquises et libérées dans la portée de la couche propriétaire. Utiliser Effect.try ou Effect.tryPromise traduire les exceptions étrangères en erreurs significatives. Les noms d’opérations stables dans les erreurs et le traçage permettent de diagnostiquer les échecs sans coupler les appelants à un pilote de stockage.

La composition des couches est importante : les couches sœurs fusionnées ne se fournissent pas automatiquement de services. L’enregistrement des étapes du flux de travail Sidecar est superposé après le coureur dont il a besoin ; l'étape AI est enregistrée là où le service AI est disponible.

Validation et erreurs

Les entrées et sorties HTTP sont déclarées dans packages/api/src/groups. Validez les entrées inconnues à ces limites. Le contrat comprend des messages d'erreur simples, des enveloppes de réussite/erreur et certains corps d'erreur saisis ; préserver le statut déclaré du point de terminaison et la représentation de la réponse.

Les erreurs HTTP utilisent des schémas d'effet et des annotations d'état. Par exemple, BadRequest, Unauthorized, NotFound, et Conflict sont déclarés dans packages/api/src/errors.ts. Les pannes de base de données internes entraînent une opération et provoquent DatabaseError. Mappez les échecs internes à la limite HTTP plutôt que d’exposer les détails du pilote aux clients.

Régénérer les clients après un changement de contrat avec bun run generate. Vérifiez la sortie validée avec bun run generate:check. Les dossiers générés sont des sorties ; la génération exclut explicitement les points de terminaison qu’une cible ne peut pas représenter.

Persistance et configuration

Les référentiels d'applications utilisent le Database service de @cadcamfun/db et son query(operation, run) auxiliaire. Changement packages/db/src/schema.ts avant de générer des migrations. Examiner ensemble le SQL généré et les métadonnées ; n'exécutez pas une expérience de schéma destructrice sur la base de données d'un utilisateur.

Le sidecar lit la configuration dans apps/sidecar/src/config.ts et le fait passer AppConfigService. Les informations d'identification utilisent des valeurs expurgées lorsque le service les requiert. Conservez les valeurs secrètes des jetons et des fournisseurs hors des journaux, de la documentation et des résultats de dépannage. Le shell natif fournit son propre jeton de lancement et ses propres chemins de stockage.

Le Studio de documentation est un outil local distinct avec sa propre sélection de chemin dans packages/web/script/studio-server.ts. Ne supposez pas que son chemin de base de données ou sa session de connexion correspondent au bureau en cours d'exécution.

Vérification

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

Choisissez des contrôles qui exercent la limite affectée. Les changements purs du noyau nécessitent des cas de régression numérique et géométrique. Les modifications HTTP nécessitent une couverture de gestionnaire et de schéma. Les modifications de la documentation nécessitent des itinéraires valides, des ancres, des exemples et une création de site réussie. Un test complet de l'espace de travail est bun run test, qui comprend des packages, des applications et des scripts.

Champs facultatifs, valeurs nulles et valeurs de transport

Un champ facultatif peut être omis. Un champ nullable peut contenir explicitement null. Ce sont des propriétés distinctes : le contrat de projet exige description dans les lignes renvoyées tout en autorisant null, et une demande de création permet l'omission de ce champ. Conservez ces distinctions lors de la création de clients ou de la mise à jour de documents enregistrés.

La validation du transport est également distincte de la validation commerciale. La charge utile de création de projet autorise l'omission d'un nom au niveau du schéma, mais le gestionnaire renvoie 400 avec Project name is required s'il est manquant ou vide. Un type généré ne peut à lui seul établir qu'une opération sera admise pour une ressource ou un compte courant existant.

Les paramètres de requête HTTP sont du texte codé. Utilisez les champs de requête déclarés par le client ou le codage d'URL plutôt que de concaténer les entrées utilisateur arbitraires dans une URL. Encodez une clé ou un identifiant de projet sous la forme d'un segment de chemin unique et envoyez les jetons de support dans les en-têtes plutôt que dans les liens copiés.

Le référence de l'API des projets affiche ces champs et codes d'état ; le procédure pas à pas capturée démontre le résultat de la validation du gestionnaire.

Maintenir la documentation exécutable

Écrivez un exemple par rapport à la surface publique exacte qu’il nomme. Le SDK Promise et le client Effect basé sur un contrat complet ont des formes et des couvertures de méthodes/entrées différentes. Une requête de générateur basée sur les paramètres est différente d'une requête de noyau natif, et un programme généré est différent d'un enregistrement de parcours d'outil enregistré.

L'instantané de référence d'API est généré à partir du contrat d'application. Après avoir modifié un point de terminaison, régénérez-le dans l'espace de travail Web avec bun run generate:api-reference. Courir bun run check:api-reference pour le comparer avec la source actuelle. Le regroupement des ressources, le texte de l'article, la navigation et l'assistant de récupération doivent toujours décrire fidèlement ce contrat.

Lorsque vous documentez une réponse capturée à partir d’une exécution isolée, identifiez les identifiants normalisés, les horodatages ou les champs omis. Étiquetez les modèles de demande en tant que modèles. Ne présentez pas un identifiant inventé ou un exemple de schéma non exécuté comme réponse de production observée.

Modèles d'effets utilisés partout

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

• Les clés de service sont dotées d'un espace de noms : "cadcamfun/Database", "cadcamfun/AppConfig", "cadcamfun/ApiClient".
• Les erreurs sont Data.TaggedError services intérieurs et Schema.TaggedError avec un httpApiStatus à la limite HTTP. Les gestionnaires mappent le premier au second.
• Ressources avec une utilisation à vie Effect.acquireRelease ils se ferment donc lorsque la portée de la couche se ferme.
• Utilisation des fonctions nommées Effect.fn("area.name") donc les traces portent un nom d'étendue lisible, par exemple cam.runKernelRequest.
• La configuration est lue une fois, dans AppConfigService; aucun autre module ne lit process.env dans le sidecar.

Règles de dénomination et de mise en page

En 3D