Codice contributo

Individuare l'implementazione

Inizia con il comportamento che stai modificando. Per un'azione sul desktop, segui apps/desktop/src/app/routes.tsx all'adattatore di pagina e alla schermata delle funzioni. Individuare la richiesta nel client o nell'helper funzionalità, lo schema dell'endpoint in packages/api, il conduttore dentro apps/sidecar/src/httpe il servizio o il repository sottostante.

Per una modifica della geometria o dell'uscita NC, iniziare da packages/core e i suoi test adiacenti. Per un problema di persistenza, controllare la query del repository e packages/db/src/schema.ts. Per verificare il comportamento del ciclo di vita nativo, della finestra di dialogo dei file, del portachiavi o dell'aggiornamento, controlla apps/desktop/src-tauri/src. Ciò mantiene un cambiamento vicino alla sua effettiva responsabilità.

Responsabilità dello spazio di lavoro

Utilizza il punto di ingresso pubblico di un modulo quando disponibile. Mantieni l'accesso SQLite fuori dalla geometria principale e dai client. Le schermate delle funzionalità non devono ignorare l'autorizzazione sidecar o incorporare le credenziali del server. Le modifiche trasversali dovrebbero aggiornare esplicitamente ciascun confine interessato.

Modificare deliberatamente i contratti condivisi

1. Definire gli schemi di richiesta, risposta ed errore digitato nel pacchetto di contratto.
2. Implementare il gestore e il relativo comportamento del servizio/repository, inclusi i controlli di proprietà.
3. Rigenerare i client e verificare che l'output generato sia aggiornato.
4. Aggiorna i consumer desktop, complementari, plug-in o client esterni che utilizzano la superficie modificata.
5. Documentare l'input, l'output, il comportamento in caso di errore e i limiti operativi supportati.

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

I client generati sono output del generatore di contratti. Correggi il contratto o il generatore quando le loro forme sono sbagliate; una correzione scritta a mano all'output generato andrà persa durante la rigenerazione. Preserva la semantica del client esistente o identifica l'impatto sulla compatibilità di una modifica deliberata dell'API.

Convenzioni di attuazione

Scrivi codice, commenti e documentazione in inglese. Mantieni esplicite le interfacce TypeScript esportate e utilizzale unknown oltre alla convalida dello schema per valori non attendibili. Utilizzo relativo delle importazioni TypeScript .ts estensioni. Le distanze CAD utilizzano i millimetri e gli angoli di disegno utilizzano i radianti; onorare esplicitamente la funzione con valore in gradi e gli ingressi rotanti CAM. Formattare i numeri NC al confine del palo.

Il codice dell'effetto utilizza le API di servizio/livello/errore della versione bloccata. I servizi possiedono dipendenze esterne; risorse proprie dei livelli con ambito. Evitare di aggiungere letture di configurazione del processo nascosto all'interno di un modulo di dominio. Mantieni puri i calcoli della geometria e isola le operazioni di file system, rete e database dietro i relativi adattatori.

Per una modifica dello schema, modificare schema.ts, generare una migrazione ed eseguire sia la nuova creazione che l'aggiornamento di un database esistente. Per una modifica dell'interfaccia utente, mantieni gli adattatori di percorso piccoli e inserisci la logica di interazione nella funzionalità pertinente. Per il lavoro nativo, mantieni la geometria e la logica del repository nel sidecar/core anziché spostarli in Rust.

Verifica prima della revisione

• Esegui il controllo del tipo del pacchetto interessato e test significativi per il comportamento modificato.
• Per una correzione di bug, dimostrare la condizione di errore e il relativo risultato corretto.
• Per i contratti condivisi, controlla i clienti generati e i consumatori interessati.
• Per la persistenza, verifica il comportamento della migrazione e l'integrità dei dati utilizzando database isolati.
• Per le interazioni native o sottoposte a rendering, esercita il runtime di destinazione effettivo oltre ai test logici.
• Aggiorna la documentazione dell'utente/sviluppatore e spiega le limitazioni operative che rimangono.

I controlli di root sono bun run typecheck e bun run test. CI ha anche Rust e lavori specifici per i compagni. Segnalare ciò che è stato eseguito ed eventuali errori o copertura del runtime non disponibile; distinguere un flusso di lavoro configurato da un'esecuzione riuscita.

Mantieni le modifiche revisionabili

Mantieni gli artefatti generati, gli aggiornamenti delle dipendenze, le modifiche al comportamento e le modifiche alla documentazione riconducibili allo stesso scopo concreto. Evitare di riformattare moduli non correlati. Conserva il lavoro esistente degli utenti e utilizza directory di dati usa e getta per gli esperimenti.

Non includere token di avvio, collegamenti di accoppiamento dei dispositivi, chiavi di modello, contenuti del database o credenziali di firma nelle patch o negli screenshot. Gli esempi dovrebbero utilizzare segnaposto. Un appuntamento locale o un fornitore deriso possono convalidare un flusso deterministico; documento in cui rimane necessaria l'integrazione con un fornitore reale o nativo.

Controlli utili

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

Usi del packaging nativo scripts/build.ts; utilizzo --help o --dry-run per verificarne le fasi. I test unitari sono separati dalla fase di controllo del tipo della pipeline di compilazione. Consulta la guida alla versione per la firma, l'architettura di destinazione e la convalida dell'aggiornamento.

Esempio: modificare la convalida del progetto

Supponiamo che un progetto crei/aggiorni le modifiche alle regole. Lo schema della richiesta è packages/api/src/projects.ts, l'adattatore HTTP è apps/sidecar/src/http/projects.tse la persistenza è implementata da ProjectRepo. Lo schema attualmente fa name facoltativo, mentre i gestori lo richiedono per la creazione e l'aggiornamento. Ispeziona entrambi i livelli prima di promettere che una richiesta valida per lo schema avrà esito positivo.

1. Definire i casi di input previsti: nome mancante, tipo non valido, testo vuoto, organizzazione accessibile e organizzazione inaccessibile.
2. Decidere quale condizione è un errore di decodifica e quale è la convalida aziendale. Conserva la forma di stato/errore documentata dell'endpoint.
3. Aggiungere asserzioni al limite del gestore/servizio pertinente e verificare che i chiamanti non autorizzati o non membri non possano ignorare la regola.
4. Se lo schema pubblico è cambiato, rigenerare entrambe le famiglie client e i consumatori typecheck.
5. Utilizza il modulo desktop e documenta eventuali modifiche ai requisiti della richiesta.

La creazione attualmente restituisce una riga di progetto semplice con HTTP 201. Elenca/ottieni righe arricchite con relazione di restituzione. Non imporre una busta di successo generica a questa famiglia senza aggiornare il suo contratto e i suoi consumatori. Altre famiglie di endpoint utilizzano intenzionalmente inviluppi diversi.

Il punto di ingresso del generatore è packages/api/scripts/generate-clients.ts. I suoi risultati vivono sotto src/client/generated e src/sdk/generated. Le modifiche alla superficie contrattuale appartengono al contratto di origine; l'output generato dovrebbe essere riproducibile.

Scegli una regressione alla giusta profondità

Una regressione geometrica dovrebbe affermare la geometria, non solo ripetere il calcolo modificato. I test di collisione esistenti forniscono modelli utili: una sovrapposizione stazionaria è una collisione al tempo zero; una spazzata rotazionale intermedia può entrare in collisione anche quando un punto finale è libero; un limite insufficiente non è risolto; e un'autorizzazione certificata viene confrontata con un fitto riferimento indipendente.

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

Scegli il confine analogo per altri lavori. Una migrazione del database richiede casi di aggiornamento/aggiornamento e comportamenti di errore del backup. Un parser di flusso necessita di frame divisi e cancellazione. Una modifica di salvataggio dell'interfaccia utente richiede la selezione della destinazione, la richiesta non riuscita, un nuovo tentativo e la riapertura dello stato salvato. Un comando nativo necessita di convalida e comportamento del ciclo di vita oltre a un controllo del tipo di frontend.

Mantieni i controlli proporzionali al cambiamento. Le modifiche ai contenuti richiedono la verifica della navigazione/del modello; non richiedono l'invenzione di nuovi test di dominio. Un test ristretto che supera solo il comportamento affermato, quindi includi il pacchetto o i controlli di integrazione richiesti dalla superficie pubblica modificata.

Contribuire alla documentazione

Il sito web è dentro packages/web. Utilizzo delle pagine di documentazione DocsLayout, un sommario, identificatori di sezione e componenti di codice/richiamo/link correlati condivisi. Conserva le convenzioni della pagina e il design visivo esistente migliorando al tempo stesso il contenuto.

1. Leggi l'implementazione, il manifest e la configurazione per ogni comportamento che documenti.
2. Utilizzare un comando supportato o una forma di richiesta e indicare la directory di lavoro, le credenziali, il percorso dati e i prerequisiti nativi necessari.
3. Descrivere il risultato e le relative modalità di fallimento. Etichettare gli esempi come esempi; chiamare una risposta catturata solo quando è stata effettivamente catturata.
4. Aggiorna i metadati di navigazione e recupero quando aggiungi o rinomini un percorso e correggi ogni collegamento locale alla vecchia posizione.
5. Esegui i controlli dell'indice e la build di Astro, quindi ispeziona la pagina renderizzata e i suoi ancoraggi.

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

Le attestazioni sull'elemento della configurazione configurato dovrebbero indicare cosa fa il flusso di lavoro. Le affermazioni sulla pubblicazione riuscita o sull'accettazione del runtime necessitano del particolare run/artefatto come prova. La documentazione dovrebbe distinguere il comportamento implementato, le impostazioni predefinite e i limiti senza trasformare le note di pianificazione interna in istruzioni sul prodotto.

Elenco di controllo delle richieste pull

• bun run typecheck passa alla radice.
• bun run test passa; il nuovo comportamento ha un test accanto al codice.
• Le modifiche al contratto vengono rigenerate: bun run generate:check e bun run --filter @cadcamfun/web check sono puliti.
• Le modifiche allo schema includono la cartella di migrazione generata e non sono mai modifiche di una migrazione applicata.
• I cambiamenti di Rust passano cargo clippy e cargo test (CI esegue entrambi).
• Il comportamento visibile all'utente si riflette nella pagina dei documenti che lo descrive.

CI esegue gli stessi comandi a ogni push, quindi un'esecuzione locale verde è il miglior predittore di una richiesta pull verde.

Nel 3D