A .craftingtable/ mappa — a termék valódi kimenete

A projekt gyökerében (egy Git repository-ban) él egy .craftingtable/ mappa. Ez nem az app belső adatbázisa — ez maga a termék kimenete. A fejlesztő akkor is használhatja, ha soha többé nem indítja el az appot. Innen ered a vendor-lock-in-mentesség és az ingyenes, Git-alapú csapatkollaboráció.

Szerkezet

<projekt-gyökér>/                        ← Git repository
├─ .craftingtable/
│  ├─ project.json                       # id, név, schemaVersion, edition, stack
│  ├─ settings.json                      # felhasználói beállítások (nem megosztott)
│  ├─ levels/
│  │  ├─ l1/BC-001.json    + BC-001.md   # Business Case
│  │  ├─ l2/DEV-001.json   + DEV-001.md  # User Story
│  │  ├─ l3/SCR-001.json   + SCR-001.md  # Screen & Path
│  │  └─ l4/CMP-001.json   + CMP-001.md  # Technical Spec
│  ├─ flows/FLW-001.json                 # node-ok, élek, C4 szint, node→doc hivatkozás
│  ├─ structure/
│  │  ├─ pages/PAGE-*.json               # Oldal entitások
│  │  ├─ tree.json                       # a Layout modul generált céltárgya
│  │  └─ scaffold/                       # a Layout által kiírt scaffold-fájlok
│  ├─ schemas/
│  │  ├─ models/MDL-user.json            # adatmodell
│  │  └─ api/API-auth.openapi.json
│  ├─ assets/
│  │  ├─ infra/SRV-001.json              # szerver, hálózati eszköz, felhő erőforrás
│  │  └─ packages/PKG-react.json         # npm/go/pip függőség
│  ├─ design/
│  │  ├─ tokens.json                     # W3C DTCG formátum, egyben mentve
│  │  ├─ components/CMP-button.json      # penpot ref + css/tsx snippet + kép útvonal
│  │  └─ exports/CMP-button.png
│  ├─ skills/SKL-react-frontend.md       # frontmatter + Markdown body (nem JSON!)
│  ├─ blueprints/BP-system.json          # Blueprint → Block → Part → Tweak
│  ├─ tasks/
│  │  ├─ WP-DEV-001-01.md                # generált, atomi Work Package
│  │  └─ index.json                      # lista + hash + státusz
│  ├─ exports/2026-10-01-handoff/        # Export & Handoff kimenetek (MD/HTML)
│  ├─ manifest.json                      # entitás → fájl → tartalom-hash (integritás)
│  └─ .index/                            # ← .gitignore-ban!
│     ├─ craftingtable.db                # SQLite derivált index
│     └─ snapshots/2026-08-09T10-00.zip
├─ .mcp.json                             # AI ágens konfiguráció (generált)
├─ .gitignore                            # `.craftingtable/.index/` bejegyzéssel
├─ docs/                                 # ember által olvasható, generált doksi
└─ src/ …                                # a célprojekt tényleges kódja

Entitás-azonosítók

Minden entitás stabil, ember által olvasható azonosítót kap: <TÍPUS>-<sorszám> vagy <TÍPUS>-<slug> (BC-001, DEV-014, MDL-user). Az azonosító soha nem változik átnevezéskor — a fájlnév az azonosítót követi, a cím külön mező. Ez teszi lehetővé a hivatkozások (refs) stabilitását és a Git-átnevezés-követést.

Kanonikus JSON — a Git-barátság feltétele

Ez nem stílus-kérdés, hanem termékfunkció. Enélkül a csapatkollaboráció használhatatlan.

1. Kulcsok ábécésorrendben, rekurzívan.
2. 2 szóköz behúzás, \n sorvég, záró újsor.
3. Tömbök determinisztikus sorrendben (elsődlegesen id szerint; ahol a sorrend jelentéssel bír, ott explicit order mező).
4. Lebegőpontos szám tiltva, ahol elkerülhető.
5. Timestamp: RFC3339 UTC, másodperc pontossággal (nem nanoszekundum).
6. Tartalom-alapú írás: ha a szerializált bájtsor azonos, nem írunk fájlt.
7. Egy sor = egy értelmes változás. Nincs egysoros tömör JSON.

Az elvárt eredmény egy olvasható Git-diff:

   "type": "string",
-  "maxLength": 128,
+  "maxLength": 255,

és nem: - {"name":"email","type":"string",...} + {"name":"email",...}.

Minden mentés után az engine újraszerializál és bájtra összehasonlít (canonjson.Roundtrip); CI-ban golden-file teszt védi.

Séma-verziózás és migráció

Elem	Szabály
Hol	Minden entitás-fájlban schemaVersion (semver); project.json a projekt egészéé
Patch (1.0.0 → 1.0.1)	Csak leírás változik. Nincs migráció.
Minor (1.0 → 1.1)	Csak opcionális mező hozzáadás. Régi app olvassa az újat (ismeretlen mezőt megőrzi).
Major (1.x → 2.0)	Breaking. Kötelező migrátor, a projekt megnyitásakor fut, előtte automatikus snapshot.
Visszafelé	Az app soha nem nyit meg magánál újabb major sémát — frissítési linket ad.
Ismeretlen mező	Megőrzendő — különben egy régebbi kliens mentése adatot töröl a csapattársnál.

A jelenlegi entitás-séma: 1.1.0 (a User Story acceptanceCriteriaRefs, criteria, vpc mezőivel bővült — mind additív és opcionális, az 1.0.0 fájlok változatlanul olvashatók).

Import / Export

Forgatókönyv	Mechanizmus
Csapattárs klónozza a repót	git clone / git pull — maga a .craftingtable/ mappa az export
Átadás Git nélkül dolgozó félnek	Snapshot ZIP — a JSON+MD teljes állapota egy fájlban
Visszatöltés másik/friss gépre	Snapshot ZIP kicsomagolása a projekt gyökerébe, majd reindex
Ember által olvasható átadás	Export & Handoff (MD / HTML / PDF)

Lásd még: Modulok → Git és Snapshot.