Code contributeur

Localiser l'implémentation

Commencez par le comportement que vous modifiez. Pour une action sur le bureau, suivez apps/desktop/src/app/routes.tsx à son adaptateur de page et à son écran de fonctionnalités. Localisez la requête dans son client ou son assistant de fonctionnalité, le schéma du point de terminaison dans packages/api, le gestionnaire dans apps/sidecar/src/http, et le service ou le référentiel situé en dessous.

Pour une modification de géométrie ou de sortie CN, commencez par packages/core et ses tests adjacents. Pour un problème de persistance, inspectez la requête du référentiel et packages/db/src/schema.ts. Pour le comportement natif du cycle de vie, de la boîte de dialogue de fichiers, du trousseau ou du programme de mise à jour, inspectez apps/desktop/src-tauri/src. Cela maintient un changement proche de sa responsabilité réelle.

Responsabilités de l'espace de travail

Utilisez le point d’entrée public d’un module lorsqu’il est disponible. Gardez l'accès SQLite hors de la géométrie principale et des clients. Les écrans de fonctionnalités ne doivent pas contourner l’autorisation sidecar ni intégrer les informations d’identification du serveur. Les changements transversaux devraient mettre à jour explicitement chaque limite concernée.

Modifier délibérément les contrats partagés

1. Définissez les schémas de demande, de réponse et d’erreur de saisie dans le package contractuel.
2. Implémentez le gestionnaire et son comportement de service/référentiel, y compris les contrôles de propriété.
3. Régénérez les clients et vérifiez que la sortie générée est à jour.
4. Mettez à jour les consommateurs de bureau, compagnon, plug-in ou client externe qui utilisent la surface modifiée.
5. Documentez les entrées, les sorties, le comportement en cas de panne et les limites opérationnelles pris en charge.

bun run generate
bun run generate:check
bun run --filter @cadcamfun/api typecheck
bun run --filter @cadcamfun/sidecar typecheck

Les clients générés sont les sorties du générateur de contrat. Réparez le contrat ou le générateur lorsque leurs formes sont fausses ; une correction manuscrite de la sortie générée sera perdue lors de la régénération. Préservez la sémantique client existante ou identifiez l’impact sur la compatibilité d’un changement délibéré d’API.

Conventions de mise en œuvre

Rédigez du code, des commentaires et de la documentation en anglais. Gardez les interfaces TypeScript exportées explicites et utilisez unknown plus une validation de schéma pour les valeurs non fiables. Utilisation des importations TypeScript relatives .ts extensions. Les distances CAO utilisent des millimètres et les angles de dessin utilisent des radians ; honorer explicitement les fonctionnalités à valeur de degré et les entrées rotatives CAM. Formatez les numéros NC à la limite du poteau.

Le code d’effet utilise les API de service/couche/erreur de la version épinglée. Les services possèdent des dépendances externes ; Les couches délimitées possèdent leurs propres ressources. Évitez d'ajouter des lectures de configuration de processus cachées dans un module de domaine. Gardez les calculs géométriques purs et isolez les opérations du système de fichiers, du réseau et de la base de données derrière leurs adaptateurs.

Pour un changement de schéma, modifiez schema.ts, générer une migration et effectuer à la fois une nouvelle création et une mise à niveau d'une base de données existante. Pour une modification de l'interface utilisateur, gardez les adaptateurs d'itinéraire petits et placez la logique d'interaction dans la fonctionnalité appropriée. Pour le travail natif, conservez la géométrie et la logique du référentiel dans le sidecar/core plutôt que de les déplacer dans Rust.

Vérification avant examen

• Exécutez la vérification de type du package concerné et des tests significatifs pour le comportement modifié.
• Pour une correction de bogue, démontrez la condition défaillante et son résultat corrigé.
• Pour les contrats partagés, vérifiez les clients générés et les consommateurs concernés.
• Pour des raisons de persistance, vérifiez le comportement de migration et l’intégrité des données à l’aide de bases de données isolées.
• Pour les interactions natives ou rendues, exercez le runtime cible réel en plus des tests logiques.
• Mettre à jour la documentation utilisateur/développeur et expliquer les limitations opérationnelles qui subsistent.

Les vérifications racine sont bun run typecheck et bun run test. CI propose également des tâches spécifiques à Rust et à ses compagnons. Signaler ce qui a été exécuté et toute panne ou couverture d'exécution indisponible ; distinguer un flux de travail configuré d'une exécution réussie.

Gardez les modifications modifiables

Gardez les artefacts générés, les mises à jour de dépendances, les changements de comportement et les modifications de documentation traçables vers le même objectif concret. Évitez de reformater des modules non liés. Préservez le travail des utilisateurs existants et utilisez des répertoires de données jetables pour les expériences.

N'incluez pas les jetons de lancement, les liens de couplage d'appareils, les clés de modèle, le contenu de la base de données ou les informations d'identification de signature dans les correctifs ou les captures d'écran. Les exemples doivent utiliser des espaces réservés. Un appareil local ou un fournisseur simulé peut valider un flux déterministe ; document où un véritable fournisseur ou une intégration native reste nécessaire.

Vérifications utiles

bun run --filter @cadcamfun/core typecheck
bun test packages/core
bun test apps/sidecar/test
bun test apps/desktop/src
bun run --cwd apps/mobile typecheck
bun run --cwd apps/mobile test
bun run --cwd packages/web check
bun run --cwd packages/web build

Utilisations des emballages natifs scripts/build.ts; utiliser --help ou --dry-run pour inspecter ses étapes. Les tests unitaires sont distincts de l'étape de vérification de type du pipeline de construction. Consultez le guide de publication pour la signature, l’architecture cible et la validation du programme de mise à jour.

Exemple : validation du projet de modification

Supposons qu’un projet crée/mette à jour les règles. Le schéma de la requête est packages/api/src/projects.ts, l'adaptateur HTTP est apps/sidecar/src/http/projects.ts, et la persistance est implémentée par ProjectRepo. Le schéma fait actuellement name facultatif, tandis que les gestionnaires l’exigent pour la création et la mise à jour. Inspectez les deux niveaux avant de promettre qu’une requête valide avec un schéma réussira.

1. Définissez les cas de saisie prévus : nom manquant, type non valide, texte vide, organisation accessible et organisation inaccessible.
2. Décidez quelle condition est une erreur de décodage et laquelle est une validation métier. Préservez la forme documentée de l’état/de l’erreur du point de terminaison.
3. Ajoutez des assertions à la limite du gestionnaire/service pertinent et vérifiez que les appelants non autorisés ou non membres ne peuvent pas contourner la règle.
4. Si le schéma public a changé, régénérez les familles de clients et les consommateurs de vérification de type.
5. Exercez le formulaire de bureau et documentez toute modification des exigences de la demande.

La création renvoie actuellement une ligne de projet nue avec HTTP 201. Répertorier/obtenir des lignes enrichies en relation de retour. N'imposez pas une enveloppe générique de réussite à cette famille sans mettre à jour son contrat et ses consommateurs. D'autres familles de points de terminaison utilisent intentionnellement des enveloppes différentes.

Le point d’entrée du générateur est packages/api/scripts/generate-clients.ts. Ses sorties vivent sous src/client/generated et src/sdk/generated. Les modifications apportées à la surface du contrat appartiennent au contrat source ; la sortie générée doit être reproductible.

Choisissez une régression à la bonne profondeur

Une régression géométrique doit affirmer la géométrie, et non seulement répéter le calcul en cours de modification. Les tests de collision existants fournissent des modèles utiles : un chevauchement stationnaire est une collision au temps zéro ; un balayage de rotation intermédiaire peut entrer en collision même lorsqu'un point final est dégagé ; une limite insuffisante n'est pas résolue ; et une autorisation certifiée est comparée à une référence indépendante dense.

bun test packages/core/src/cam/kernel/collision.test.ts
bun run --filter @cadcamfun/core typecheck
bun test packages/core

Choisissez la limite analogue pour d’autres travaux. Une migration de base de données nécessite des cas de nouvelle/mise à niveau et un comportement d’échec de sauvegarde. Un analyseur de flux nécessite des images fractionnées et une annulation. Une modification de sauvegarde de l’interface utilisateur nécessite une sélection de destination, un échec de demande, une nouvelle tentative et la réouverture de l’état enregistré. Une commande native nécessite une validation et un comportement de cycle de vie en plus d'une vérification de type frontale.

Gardez les chèques proportionnels au changement. Les modifications de contenu nécessitent une vérification de la navigation/du modèle ; ils ne nécessitent pas d'inventer de nouveaux tests de domaine. Un test restreint qui réussit ne prend en charge que son comportement affirmé, incluez donc les vérifications de package ou d'intégration requises par la surface publique modifiée.

Contribuer à la documentation

Le site Internet est en packages/web. Utilisation des pages de documentation DocsLayout, une table des matières, des identifiants de section et des composants de code/légende/lien associé partagés. Préservez ces conventions de page et la conception visuelle existante tout en améliorant le contenu.

1. Lisez l'implémentation, le manifeste et la configuration de chaque comportement que vous documentez.
2. Utilisez une forme de commande ou de demande prise en charge et indiquez le répertoire de travail, les informations d'identification, le chemin de données et les conditions préalables natives nécessaires.
3. Décrivez le résultat et ses modes de défaillance. Étiquetez les exemples comme exemples ; appeler une réponse capturée uniquement lorsqu'elle a été réellement capturée.
4. Mettez à jour les métadonnées de navigation et de récupération lors de l'ajout ou du renommage d'un itinéraire, et corrigez chaque lien local vers l'ancien emplacement.
5. Exécutez les vérifications d'index et la construction Astro, puis inspectez la page rendue et ses ancres.

bun run --cwd packages/web check
bun run --cwd packages/web typecheck
bun run --cwd packages/web build

Les déclarations concernant le CI configuré doivent indiquer ce que fait le flux de travail. Les affirmations concernant une publication réussie ou l'acceptation de l'exécution nécessitent l'exécution/l'artefact particulier comme preuve. La documentation doit distinguer les comportements mis en œuvre, les valeurs par défaut et les limites sans transformer les notes de planification internes en instructions produit.

Liste de contrôle des demandes de tirage

• bun run typecheck passe à la racine.
• bun run test passe; le nouveau comportement a un test à côté du code.
• Les modifications de contrat sont régénérées : bun run generate:check et bun run --filter @cadcamfun/web check sont propres.
• Les modifications de schéma incluent le dossier de migration généré et ne constituent jamais des modifications d'une migration appliquée.
• Les changements de Rust passent cargo clippy et cargo test (CI exécute les deux).
• Le comportement visible par l'utilisateur est reflété dans la page de documentation qui le décrit.

CI exécute les mêmes commandes à chaque poussée, donc une exécution locale verte est le meilleur prédicteur d'une demande d'extraction verte.

En 3D