Git workflow

ourCAD je git-native CAD. Každý dokument je bare git repo na serveru. Můžeš ho clonovat, commitovat, větvit, mergovat, time-travelovat. To je radikálně jiné než SolidWorks / Inventor / Fusion — žádný konkurent to neumí takhle.

Architektura

• Git je single source of truth — ne Postgres. DB je jen rychlá pracovní cache.
• Document = bare git repo v /opt/ourcad/data/git-repos/<id>.git
• Feature tree, sketches, constraints, assembly serializované do document.yaml (diffovatelné!)
• BRep geometrie content-addressable — objects/<sha256>.brep — dedupe + LFS-lite
• Dehydrate-idle — po 30 min nečinnosti se DB workspace vyprázdní; rehydrate při dalším otevření

Explicitní commit

Každá modelovací akce jde sync do Postgres. Git commit ale NE — to je na tobě:

1. Toolbar → Commit (modré tlačítko vpravo, badge ukazuje "N uncommitted")
2. Napiš commit message (Czech / English, doporučeno popis change)
3. Klikni Commit. Změna jde do gitu, badge zmizí.

TIP

Auto-commit existuje pro idle/close window. Po hodině nečinnosti / zavření browseru ourCAD si commitne sám pod jménem "auto-commit". Tvá ruční hodnotná history se ale buduje přes explicitní commits.

Branche (větve)

Toolbar → Branche otevře branch panel. Každý dokument má jako default main branch, můžeš vytvořit další.

Vytvoření branche

1. Branch panel → + Nová větev
2. Napiš jméno (experiment, varianta-2mm, customer-x)
3. Vyber base branch (default current)
4. Vytvořit — nová větev se vytvoří jako copy aktuální HEAD

Switch (přepnutí)

Klik na branch v panelu → ourCAD checkneme HEAD té větve, dehydrate aktuální stav, rehydrate z target branch. Persistence: branch volba se uloží do metadata.current_branch, takže po reload jsi pořád na své větvi.

Merge

Branch panel → Merge into main (nebo libovolný target). ourCAD spustí 3-way merge feature tree YAML:

• Common ancestor + your branch + target branch
• Auto-merge co se nestřetne
• Conflict resolution: left-wins (your branch). Konflikty se nahlásí v UI před commit.

Use case: konstrukční varianty

• main — release verze
• variant-mm6 — varianta s M6 závity
• variant-mm8 — varianta s M8 závity
• experiment-shell — testuju shell tloušťku

Každá varianta jde držet samostatně. Konečná release = merge vybrané větve do main.

History & time-travel

Toolbar → History otevře historii commitů.

• Klik na commit ukáže diff feature tree YAML — co se změnilo (přidané/odstraněné features, změněné parametry)
• Time-travel: klik "Otevřít v čase X" načte dokument ve stavu commitu (read-only)
• Restore: pokud chceš revert na starší stav, vytvoř novou větev z commitu a merge

TIP

Content-addressable BRepy: git checkout <old SHA> dává matching geometrii. Ne re-build z parametrů — skutečný BRep z té doby. Žádný "regen took 5 min" když si chceš jen prohlédnout starou verzi.

Releasy (schválené verze)

Schválení dokumentu ve workflow (Spravovat dokument → Workflow → Schválit) automaticky vytvoří release — trvalý, neměnný záznam schváleného obsahu (git tag release/N). První schválení = release 0, každé další schválení číslo zvýší.

• Aktuální release vidíte jako 🏷 štítek vedle stavu dokumentu; sekce Releasy ukazuje celou historii (kdo, kdy, jaká verze).
• V grafu verzí nese commit release jantarový štítek 🏷.
• Při schválení se hlavní větev automaticky zamkne proti úpravám; návrat dokumentu do stavu Rozpracováno ji zase odemkne (ruční zámky se nemění).
• Schvalovat lze jen na hlavní větvi (main) — experimentální větev nejdřív spojte s main.
• Ve výkresu se číslo release automaticky propíše do pole revize v razítku (jen číslo, např. „2"). Vlastní ne-číselné značení revize se nikdy nepřepisuje.

Připnutí komponenty na release: u vložené komponenty v sestavě (pravý klik ve stromu) nově vyberete Připnout na release N — sestava pak drží přesně schválenou verzi dílu, i když se díl dál vyvíjí. Odepnutím se komponenta vrátí ke sledování aktuálního stavu.

Sledování větve komponenty: tamtéž jde vybrat ⎇ Sledovat větev — komponenta v sestavě živě sleduje špičku zvolené větve dílu (nové commity na větvi se projeví po znovunačtení), zatímco díl samotný může zůstat na main. Hodí se pro zkoušení experimentální varianty dílu v sestavě. Odepnutí vrátí sledování aktuálního stavu dílu; graf verzí ukazuje u držené verze „⎇ větev".

Graf verzí celé sestavy

Pravý klik na branch pill → Spravovat dokument… → Verze ukazuje graf verzí — a to nejen aktuálního dokumentu, ale celého stromu vložených dokumentů (sestava → podsestavy → díly, do libovolné hloubky).

• Vlevo je seznam obsažených dokumentů s odsazením podle úrovně vnoření. Kliknutím historii dokumentu v grafu skryjete/zobrazíte; „Rozbalit vše / Sbalit vše" přepne všechny najednou. U velkých sestav se historie jednotlivých dokumentů načítá až při rozbalení — číslo u dokumentu ukazuje počet verzí i před načtením. Graf zvládne i stovky vnořených dokumentů a tisíce verzí.
• Každý dokument má vlastní barevný pruh; commity všech dokumentů jsou seřazené na společné časové ose.
• Z commitu, který dokument vložil, vede čára na drženou verzi: plná čára = připnutá verze (📌), čárkovaná = sleduje aktuální stav dokumentu.
• Commit cizího dokumentu poznáte podle barevného štítku se jménem; kliknutím ho otevřete v nové kartě, detail (▶) ukáže diff.

Správa dokumentu v samostatném okně

Hlavička okna „Spravovat dokument" nabízí Otevřít v novém okně — správa se otevře přes celou obrazovku na adrese /documents/<id>/manage. Hodí se pro velké sestavy (graf verzí má víc místa), na druhý monitor nebo pro porovnání dvou dokumentů vedle sebe. Adresu lze poslat kolegovi jako přímý odkaz.

Změny provedené v okně (zámek dokumentu, workflow přechod) se okamžitě projeví i v otevřeném editoru a naopak.

Public clone (lokální kopie)

Tvůj ourCAD dokument můžeš git clone na svůj počítač jako jakékoli git repo:

git clone https://ourcad.cloud/api/v1/documents/<document_id>/git my-part
cd my-part
git log         # vidíš historii
cat document.yaml | head -50    # feature tree v YAML
ls objects/                     # BRep blobs (sha256.brep)

Auth: Bearer token v Authorization header NEBO HTTP Basic auth.

Clone helper

Pro pohodlí docs/ourcad-clone.sh v repu — wrap script který clones repo + dotahuje BRep blobs (LFS-lite):

./docs/ourcad-clone.sh <document_id> ~/my-part

Co je v document.yaml

Top-level struktura:

name: "Vlozka Re002843"
description: "Pojistná vložka..."
material: "Steel S235"
features:
  - id: feat_001
    type: sketch
    parameters:
      planeName: XY_Top
      sketch_data: "..."
  - id: feat_002
    type: extrude
    parameters:
      sketch_id: feat_001
      distance: 25
metadata:
  current_branch: main
  active_configuration: variant-2
configurations:
  - name: variant-1
    overrides: { D: 50 }
variables:
  - name: D
    expression: "2 * R + 5"
sketch:
  feat_001:
    elements: [...]
    constraints: [...]
settings:
  display_mode: shaded
  grid_visible: true

Diffovatelný! Můžeš v lokálním klonu přečíst git diff HEAD~5 a vidíš, co se změnilo v parametrech feature × po feature.

Merge driver

Pro 3-way merge feature tree YAML ourCAD má vlastní merge driver:

• Detekuje konflikty per-feature (např. paralelní změna parametru distance ve dvou větvích)
• Auto-resolve když se konflikty netýkají stejné feature
• Levostranná preference (your branch wins) — bezpečné default

API endpointy

Endpoint	Popis
GET /git-history	List commitů
GET /git-history/{sha}	Detail commit + YAML
POST /git-commit	Explicit commit s message
GET /git-status	yaml_differs_from_head, uncommitted_operations — pro UI badge
GET / POST /documents/{id}/git/{path...}	HTTP smart protocol — git clone, push, fetch
GET /documents/{id}/brep/{featureId}	BRep blob (LFS-lite)

Backup & disaster recovery

• Server backup: git push --mirror bare repos + malý pg_dump metadata tabulek
• Rebuild po Postgres ztrátě: rehydrate všechny dokumenty z gitu (DB je disposable cache)
• User-level backup: jednou týdně si git clone svoje dokumenty lokálně

Session lock

Když dva uživatelé otevřou stejný dokument zároveň, ourCAD vytvoří Redis session lock. Druhý uživatel uvidí varování + možnost "Force takeover". Předchází race conditions při konkurenčních editech.

Lock TTL: 10 minut, heartbeat každých 30 sekund.

Příklady real-world workflow

Customer revisions

1. Klient chce změnu velikosti
2. Vytvořím větev customer-revize-A z main
3. Provedu změnu, commit, klient schválí
4. Merge customer-revize-A → main
5. Tag (commit comment "Released v2.0")

Experimentování bez rizika

1. Vytvořím experiment-thinwall z main
2. Zkouším různé tloušťky stěn
3. Nepříjde dobrý? Smazat větev — main neporušený.
4. Příjde dobrý? Merge do main.

Audit trail pro compliance

1. Každá change má author + timestamp + message v git logu
2. Před release: git log --oneline ukáže celou history
3. Pro audit / certification: stačí git push na corporate gitserver

Co dál

• 3D Modeling — co všechno se dá commitnout
• AI Agent — agent dělá změny, ty pak commituješ