Synchronizace a obnovení

Lokální vývoj aplikací se točí kolem synchronizace: CLI znovu sestaví váš manifest a server aplikuje pouze rozdíly mezi ním a metadaty, která už jsou ve vašem pracovním prostoru. Tato stránka popisuje, po kterém příkazu sáhnout, jak číst, co synchronizace změnila, a co dělat — v daném pořadí — když lokální stav vypadá nekonzistentně.

Jaký příkaz, kdy

Pro každodenní lokální iteraci téměř vždy chcete yarn twenty dev. Nasazování a publikování slouží k vydávání verzí, ne pro lokální vývojovou smyčku.

Chcete…	Příkaz	Poznámky
Iterujte lokálně s živou synchronizací	`yarn twenty dev`	Sleduje vaše soubory a při každé změně spustí synchronizaci.
Jednorázová synchronizace a ukončení (CI, skripty, hooky)	`yarn twenty apply`	Provede jedno sestavení + synchronizaci a skončí. Přidejte `--force`, abyste přeskočili potvrzení destruktivní změny.
Náhled změn bez jejich aplikování	`yarn twenty plan`	Spočítá a vypíše rozdíly; nic nezapisuje.
Odebrat aplikaci z pracovního prostoru	`yarn twenty app:uninstall`	Přidejte `--yes` pro přeskočení výzvy.
Odeslat tarball na server	`yarn twenty app:publish --private`	Vyžaduje přísně vyšší verzi v `package.json` — viz Publikování.
Publikovat na marketplace (npm)	`yarn twenty app:publish`	—
Nainstalovat / aktualizovat nasazenou verzi	`yarn twenty app:install`	Nainstaluje aktuálně nasazenou verzi.
Vymazat lokální server a začít znovu	`yarn twenty docker:reset`	Smaže všechna lokální data — krajní řešení.

yarn twenty dev --once a yarn twenty dev --once --dry-run stále fungují jako zastaralé aliasy pro yarn twenty apply a yarn twenty plan.

Lokální synchronizace nevyžaduje zvýšení verze

Pravidlo striktně rostoucí version (VERSION_ALREADY_EXISTS při nasazení, APP_ALREADY_INSTALLED / CANNOT_DOWNGRADE_APPLICATION při instalaci) platí pro app:publish / app:install — cestu vydání. yarn twenty dev synchronizuje váš manifest na místě a nikdy nevyžaduje změnu verze, takže kvůli iteraci nemusíte sahat na package.json. Pokud zvyšujete verzi, abyste otestovali lokální změnu, používáte cestu vydání, i když chcete vývojovou smyčku.

Čtení výstupu synchronizace

Každá synchronizace vypíše změny metadat, které aplikovala (nebo by aplikovala s plan), ve stylu Terraformu — jeden blok na entitu s jejími atributy a poté souhrnný řádek:

  # objectMetadata "rocket" will be created
  + icon          = "IconRocket"
  + labelSingular = "Rocket"
  + ...

  # fieldMetadata "launchedAt" will be updated
  ~ isNullable = false -> true

Plan: 2 to add, 1 to change, 1 to destroy.

✓ Synced My App (4 files)

To je váš první diagnostický nástroj: přesně ukazuje, které objekty, pole a rozložení se změnily, takže si můžete ověřit, že synchronizace udělala to, co jste očekávali, ještě před kontrolou v UI. Destruktivní změny (to destroy) jsou uvedeny s tím, co odstraňují (např. objectMetadata "auditNote" — drops the table and all its rows) a vyžadují interaktivní potvrzení, nebo --force ve skriptech. Když synchronizace selže na jedné entitě, chyba uvede problematickou entitu a její universalIdentifier, například:

Migration action 'create' for 'fieldMetadata' (universalIdentifier: 2020...4337) failed

Tento identifikátor použijte k nalezení entity ve vašem manifestu (a případně v pracovním prostoru) místo hádání, která je v konfliktu.

Náhled změn (plan)

yarn twenty plan sestaví váš manifest, požádá server o migrační plán a vypíše ho — aniž by cokoli aplikoval. Je to bezpečný způsob, jak si předem zodpovědět otázku „co by tato synchronizace změnila?“ ještě předtím, než se k ní zavážete.

yarn twenty plan

Building manifest...
Computing metadata plan (read-only, nothing will be applied)...

  # fieldMetadata "crewCapacity" will be created
  + ...

Plan: 1 to add, 1 to change, 0 to destroy.

✓ Plan complete for My App — no changes were applied

Plán:

Nic nezapisuje — žádná migrace metadat, žádná aktualizace záznamu aplikace, žádné změny výchozí role / karty a žádná generace API klienta.
Vrací stejný diff, jaký by aplikovala skutečná synchronizace, takže můžete předem zkontrolovat vytvořené / aktualizované / smazané entity.
Je užitečný před rizikovou změnou, při kontrole změny vygenerované pomocí AI nebo ve skriptu, který má selhat, pokud se má provést neočekávaná změna.

Plán zobrazuje pouze náhled změn metadat a vyžaduje, aby byla aplikace alespoň jednou synchronizovaná (aby o ní pracovní prostor věděl). Pokud jej spustíte proti aplikaci, která nikdy nebyla synchronizovaná, server ohlásí, že aplikace není nainstalovaná — nejprve jednou spusťte yarn twenty dev.

Postup obnovy

Když lokální metadata vypadají špatně, postupujte v tomto pořadí a zastavte se, jakmile se problém vyřeší. Každý další krok je rušivější než ten předchozí.

Znovu synchronizujte. Znovu spusťte yarn twenty apply. Synchronizace jsou idempotentní — znovu spuštěný čistý manifest je bezpečný a často vyřeší přechodný problém.
Prohlédněte si plán. Spusťte yarn twenty plan, abyste přesně viděli, co chce další synchronizace změnit, aniž by to aplikovala.
Přečtěte si pojmenovanou chybu. Pokud synchronizace selže, poznamenejte si typ metadat a universalIdentifier ve zprávě (viz výše) a tuto entitu najděte ve svém manifestu. Konflikt obvykle ukazuje na duplicitní nebo znovu použitý identifikátor.
Odinstalujte a znovu nainstalujte. yarn twenty app:uninstall, poté znovu synchronizujte (yarn twenty dev). Tím znovu vybudujete metadata aplikace z čistého stavu, zatímco zbytek vašeho pracovního prostoru zůstane nedotčený.
Úplný reset (krajní řešení). yarn twenty docker:reset, poté znovu naplňte data a synchronizujte.

yarn twenty docker:reset smaže veškerá data ve vaší lokální instanci — každý pracovní prostor, záznam i aplikaci. Použijte jej až tehdy, když selžou předchozí kroky.

Nastala chyba v metadatech? Prosíme, vytvořte issue a přiložte chybovou zprávu selhané migrace (s typem metadat a universalIdentifier), výstup Metadata changes ze synchronizace a příkazy, které jste spustili.

Vyhněte se souběžným synchronizacím v jednom pracovním prostoru

Synchronizace aplikuje migrace metadat. Spouštění několika synchronizačních, nasazovacích nebo instalačních operací proti stejnému pracovnímu prostoru ve stejnou dobu — například z víc terminálů nebo od více AI agentů iterujících paralelně — může tyto migrace prokládat a zanechat metadata v částečně aplikovaném stavu. Server serializuje synchronizace pro každý pracovní prostor, aby tomu zabránil, ale přesto byste citlivé operace s metadaty měli směrovat přes jeden jediný proces místo toho, abyste je spouštěli souběžně. Pokud orchestrujete vývoj s více agenty, směrujte jejich volání sync/deploy/install přes jednu frontu, aby vždy běžel jen jeden proces.

Rozlišení typů selhání

Když se něco pokazí, diff metadat a pojmenované chyby vám umožní lokalizovat selhání:

Chyba sestavení manifestu — CLI selže ještě před synchronizací (MANIFEST_BUILD_FAILED, TYPECHECK_FAILED); opravte zdrojový kód své aplikace.
Chyba synchronizace / migrace — sestavení proběhne úspěšně, ale aplikování diffu selže a uvede entitu a universalIdentifier; opravte konfliktní metadata.
Chyba za běhu aplikačního kódu — synchronizace proběhne úspěšně, ale vaše logické funkce nebo komponenty se za běhu chovají nesprávně; zkontrolujte protokoly funkcí.
Lokální stav instance — neplatí nic z výše uvedeného a pracovní prostor stále vypadá chybně; pokračujte dolů po žebříčku obnovy.

Přehled

Aplikace

API

Vlastní hosting

Přispět

Jaký příkaz, kdy

Lokální synchronizace nevyžaduje zvýšení verze

Čtení výstupu synchronizace

Náhled změn (plan)

Postup obnovy

Vyhněte se souběžným synchronizacím v jednom pracovním prostoru

Rozlišení typů selhání

​Jaký příkaz, kdy

​Lokální synchronizace nevyžaduje zvýšení verze

​Čtení výstupu synchronizace

​Náhled změn (plan)

​Postup obnovy

​Vyhněte se souběžným synchronizacím v jednom pracovním prostoru

​Rozlišení typů selhání

Jaký příkaz, kdy

Lokální synchronizace nevyžaduje zvýšení verze

Čtení výstupu synchronizace

Náhled změn (plan)

Postup obnovy

Vyhněte se souběžným synchronizacím v jednom pracovním prostoru

Rozlišení typů selhání