Développement local

Processus de développement

Une session de développement de bureau complète exécute un shell Rust, un sidecar Bun et Vite. Le shell fournit des fonctionnalités natives et supervise le sidecar ; Vite fournit des ressources de visualisation Web et un rechargement à chaud. bun run desktop:dev prépare les ressources binaires et de migration avant de démarrer ces processus.

Pour un travail d'écran plus rapide, exécutez le bureau dev scénario seul. App.tsx sélectionne l'API d'aperçu en mémoire uniquement en dehors de Tauri et uniquement lorsque VITE_SIDECAR_URL est absent. Les échecs d'aperçu pour les collections d'API non prises en charge devraient renvoyer 501. Utilisez un sidecar en direct pour la persistance, l'autorisation, l'IA en streaming et les services de serveur.

CADCAMFUN_TOKEN=local-development-token CADCAMFUN_DATA_DIR=/tmp/cadcamfun-development CADCAMFUN_MIGRATIONS_DIR="$PWD/packages/db/drizzle" bun --no-env-file apps/sidecar/src/main.ts

Le jeton ci-dessus est un exemple de processus de développement local isolé. Choisissez votre propre valeur. Gardez stdin ouvert : sa fermeture arrête le sidecar. Le serveur imprime un JSON ready événement avec son port éphémère après /api/health répond ; les journaux vont sur stderr.

VITE_SIDECAR_URL=http://127.0.0.1:43111 VITE_SIDECAR_TOKEN=local-development-token bun run --filter @cadcamfun/desktop dev

Remplacez le port 43111 par le port d'événement prêt et utilisez le jeton fourni à ce sidecar avant de l'exécuter. Vite utilise le port 1420 avec une sélection de port stricte, correspondant à l'URL de développement Tauri. Le sidecar autorise les origines CORS du navigateur sur HTTP localhost/loopback et les origines Tauri prises en charge ; cela nécessite toujours l’autorisation appropriée pour les itinéraires protégés.

Répertoires de données et migrations

Le sidecar s'ouvre <CADCAMFUN_DATA_DIR>/cadcamfun.db. Tauri choisit son propre répertoire de données d'application et le transmet à l'enfant. Un processus manuel utilise le répertoire que vous fournissez. Ces bases de données sont indépendantes même lorsque leur nom de fichier est identique.

Le script de migration CLI lit DATABASE_URL et utilise autrement ./data/cadcamfun.db par rapport à son répertoire de travail. Racine db:migrate court à l'intérieur packages/db. Choisissez une URL de fichier absolue pour les opérations CLI délibérées ; ne déduisez pas la cible d’un nom de fichier relatif affiché dans un journal.

DATABASE_URL=file:/tmp/cadcamfun-cli/cadcamfun.db bun run db:migrate

Les modifications de schéma proviennent de packages/db/src/schema.ts. Courir bun run db:generate, examinez la migration générée et appliquez-la d'abord à une base de données isolée. Le sidecar utilise CADCAMFUN_MIGRATIONS_DIR lorsqu'il est fourni ; les versions packagées mettent en scène le répertoire généré en tant que ressource.

La couche de base de données active les WAL et les clés étrangères. Lorsqu'un fichier existant nécessite une migration, le chemin de mise à niveau crée une sauvegarde à côté sous backups/ et conserve les cinq dernières sauvegardes automatiques correspondantes. La première création, un schéma inchangé et des bases de données en mémoire ne créent pas de sauvegarde de mise à niveau. Préservez les données de manière indépendante avant les opérations de récupération manuelle.

Des contrôles ciblés

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

Sélectionnez les contrôles en fonction de la limite modifiée. Les changements de géométrie pure nécessitent des assertions géométriques ; Les modifications du contrat d'API nécessitent des vérifications générées par le client et les gestionnaires concernés ; les changements de persistance nécessitent des tests de référentiel et de migration ; Les modifications d’interaction avec l’interface utilisateur nécessitent le composant et le flux d’exécution appropriés. La racine test le script comprend packages, apps, et scripts.

Les vérifications du shell natif sont exécutées à partir de apps/desktop/src-tauri avec cargo clippy --all-targets -- -D warnings et cargo test. Préparez d'abord le sidecar cible et les migrations, puisque le contexte de construction de Tauri inclut ces ressources. Les tests d’intégration du système d’exploitation peuvent nécessiter un bureau natif et un trousseau.

Configuration d'exécution

apps/sidecar/src/config.ts possède la couche de configuration sidecar. Les entrées requises sont CADCAMFUN_TOKEN et CADCAMFUN_DATA_DIR. CADCAMFUN_MIGRATIONS_DIR sélectionne les ressources de migration. L'hôte IA par défaut est nikcli; CADCAMFUN_AI_HOST=direct sélectionne les appels directs, et CADCAMFUN_AI_OFFLINE prend en charge le fonctionnement hors ligne/test.

La configuration facultative comprend l'URL de l'application et les liens d'authentification de développement, les informations d'identification Stripe et les identifiants de prix, les paramètres administrateur/cron et OTEL_EXPORTER_OTLP_ENDPOINT. La facturation n'est pas disponible sans la configuration du fournisseur concerné ; l'exportation de télémétrie est désactivée sans son point de terminaison collecteur. Fournissez uniquement les entrées nécessaires à votre flux.

Les variables de point de terminaison du navigateur sont une configuration Vite, pas une configuration sidecar. Un couplage compagnon contient un jeton et une adresse HTTPS différents. Un jeton de pont d'action autonome a sa propre portée et sa propre durée de vie. Ne remplacez pas ces informations d’identification les unes par les autres.

Utilisez une configuration de processus ou des paramètres d'application explicites. L'exemple de commande sidecar désactive le chargement du fichier d'environnement de Bun. N'imprimez jamais de jetons réels, de clés de modèle, de liens d'appariement ou de matériel de signature dans des journaux ou des exemples de documentation.

Effet et propriété des ressources

Le référentiel épingle Effect à 4.0.0-rc.112. Utilisation des services Context.Service, les implémentations sont fournies via des couches et les opérations renvoient des effets typés. Utilisez le installé effect/ai-docs/src documentation lors de la modification de cette API, y compris ses modules HTTP instables.

Décodez les entrées externes aux limites. Mappez les exceptions étrangères en erreurs typées, préservez les balises d'erreur stables et laissez une couche étendue posséder les descripteurs de base de données, les travailleurs, les flux et les ressources du serveur. Le flux d'arrêt du sidecar gère un événement d'arrêt parent, la fermeture stdin et l'interruption de l'exécution ; les journaux et la sortie standard du protocole ont des destinations différentes.

Les calculs CAO/FAO de base restent des fonctions simples dans les chemins informatiques chauds. La validation d'enveloppement à la limite ne nécessite pas de placer chaque opération géométrique dans un effet. Utilisez les conventions d’unités géométriques de base et effectuez des conversions d’affichage/exportation sur le bord approprié. Les angles de dessin utilisent des radians ; certains paramètres de fonctionnalité et valeurs de l'axe rotatif CAM utilisent explicitement les degrés.

Dépannage au démarrage

• Port de Vite occupé : port libre 1420 ou arrêtez le serveur de développement existant ; le mode de port strict ne choisit pas silencieusement un autre port.
• Le démarrage continue de réessayer : inspectez la sortie sidecar prête/erreur et le chemin de migration. L'application résout à nouveau le point de terminaison tant que son budget de connexion demeure.
• Le serveur se ferme immédiatement : vérifiez la configuration requise et si le processus de lancement a fermé stdin.
• Projets manquants : confirmez le répertoire de données, le point de terminaison de l'API et si l'application utilise le faux client.
• 401 réponses : vérifiez que le client utilise le jeton du processus en cours plutôt qu'un lancement précédent.
• 501 dans l'aperçu du navigateur : utilisez un vrai sidecar pour cette collection d'API.
• La création du contexte natif échoue : organisez le binaire sidecar et les ressources de migration pour la cible correcte.

Documentation et développement compagnon

bun run --cwd packages/web start dirige Astro seul. bun run --cwd packages/web dev démarre Astro ainsi que l'API Studio locale. La vérification de la documentation valide l'index de l'itinéraire ; la version valide la compilation et le prérendu Astro.

Pour iOS, bun run --cwd apps/mobile start démarre Metro pour un client de développement personnalisé. bun run --cwd apps/mobile ios construit/exécute l'application native ; build exporte uniquement JavaScript. L'épinglage natif nécessite le module Swift local et ne peut pas s'exécuter dans Expo Go.

bun scripts/build.ts --help répertorie les options du pipeline de versions. --only=resources réorganise les migrations sans reconstruire, et --dry-run imprime le plan sans rien écrire.

Référence de configuration de processus

Les entrées booléennes sont décodées par la configuration de l'effet, et non par la véracité arbitraire des chaînes. Utilisez des valeurs vrai/faux explicites. Les littéraux d’hôte IA inconnus échouent au décodage. Fournir la configuration avant de créer le processus ; la modification d'une variable de terminal parent ne met pas à jour un sidecar déjà en cours d'exécution.

Utiliser Studio sur une base de données explicite

L'API Studio locale écoute sur le port de bouclage 4396. Sa priorité de chemin est CADCAMFUN_DB, alors DATABASE_URL avec un file: préfixe supprimé, puis racine du référentiel data/cadcamfun.db. Cela diffère du chemin du répertoire de travail CLI par défaut du package de base de données. Il ouvre uniquement une base de données existante et n’en crée/migre pas automatiquement.

DATABASE_URL=file:/tmp/cadcamfun-studio/cadcamfun.db   bun run db:migrate

CADCAMFUN_DB=/tmp/cadcamfun-studio/cadcamfun.db   bun run --cwd packages/web dev

La première commande initialise le fichier. La seconde démarre Studio plus Astro contre ce chemin. Un schéma récemment migré ne contient pas de session utilisateur/mot de passe simplement parce qu'il existe ; La connexion à Studio nécessite un compte approprié. Ses requêtes authentifiées utilisent le cookie de session Studio et renvoient 401 sans session valide.

Lorsque le fichier est manquant, l'API Studio renvoie 503 avec le chemin sélectionné. Lorsqu'Astro s'exécute sans le processus compagnon Studio, proxy /studio/api les requêtes ne peuvent pas atteindre le port 4396. Les pages de documentation elles-mêmes peuvent être développées avec packages/web start sans démarrer Studio.

Ancres de mise en œuvre : packages/web/script/dev.ts, script/studio-server.ts, astro.config.mjs, packages/db/src/migrate.ts, et apps/sidecar/src/config.ts.

Une boucle de développement reproductible

1. Choisissez un répertoire de données sidecar jetable et un dossier de migration explicite.
2. Démarrez le sidecar dans un terminal interactif et enregistrez le port à partir de son événement prêt.
3. Démarrez Vite dans un autre terminal avec l'URL/le jeton correspondant, ou ouvrez l'application native avec son sidecar supervisé.
4. Reproduisez une action et inspectez sa réponse et son état persistant.
5. Pour les modifications du backend, redémarrez le sidecar, mettez à jour le point de terminaison du navigateur si son port a changé et répétez l'action.
6. Arrêtez le processus avec son chemin d'interruption normal ou d'arrêt parent pour que les ressources soient finalisées.

Le sidecar draine brièvement les étendues HTTP, vérifie les points de contrôle WAL et ferme SQLite lors d'un arrêt normal. L'arrêt d'un processus sans ce chemin peut interrompre le travail en cours. Une édition de source ne remplace pas le binaire compilé déjà supervisé par Tauri ; reconstruisez le sidecar lors du test du comportement compilé.

Pour la validation du runtime compilé, scripts/smoke-sidecar.ts peut exécuter un binaire sélectionné avec un répertoire home/data isolé et une IA hors ligne. Il mesure le comportement de préparation/santé/action et exerce un travail de noyau. Sans --binary il compile d'abord un exécutable temporaire, donc prévoyez le coût de construction ; son résultat est distinct des tests au niveau source.

Quel processus s'exécute où

Boucle interne par type de changement

En 3D