Von der Vorlage bis zur Freigabe

Nach dieser Anleitung steht Ihre App als Fassung im Kanal Stabil und damit im Store jeder Organisation, deren Paket sie enthält. Der Weg beginnt mit einem Befehl, der die App aus einer Vorlage anlegt, und endet mit der Bestätigung einer zweiten Person im Ops-Portal. Dazwischen sagt ein zweiter Befehl jederzeit, was noch fehlt.

Der Weg in einem Bild#

pnpm app:new <id> ─ Widget, Config, Formular, Texte, Bilder ─ pnpm app:check <id> ─ Tests
  └─► Pull Request mit Notiz ─ Versions-PR ─ Zug: Tag @szenera-app/<id>@<fassung>
        └─► release-app.yml: bauen, aufnehmen, packen, prüfen, signieren, ablegen, melden
              └─► Staging und Produktion: Release im Kanal Canary
                    └─► Ops-Portal: Release-Prüfung ⇒ Beta ⇒ Stabil, eine zweite Person bestätigt

Die Wörter dieser Seite folgen dem Glossar: Die Fassung ist die Nummer, die eine Organisation liest (1.0.0), das Release ist dieselbe Fassung im Katalog des Betreibers, und der Kanal sagt, wer sie bekommt.

1. Die App anlegen#

pnpm app:new door-sign --name="Türschild" --name-en="Door sign"
pnpm install
pnpm --filter @szenera-app/door-sign build

pnpm app:new <id> legt apps/<id>/ aus der Vorlage an und schreibt sonst nichts: keine Liste, keinen Eintrag in einer Datei der Plattform. Plattform, Katalog, Aufnahmen und Budgets finden die App über ihren Ordner.

• Die Kennung ist kebab-case und englisch (door-sign, nicht tuerschild). Sie gilt für den Ordner, das Paket @szenera-app/<id>, das Manifest, das eine Widget der Vorlage und das Datenbank-Schema apps_<id> (mit Unterstrich statt Bindestrich). Eine vergebene, eine reservierte (core) oder eine falsch geformte Kennung lehnt der Befehl ab, mit jedem Grund auf einmal, und legt dann nichts an.
• Die Namen unter --name (deutsch) und --name-en (englisch) stehen im Manifest. Ohne sie nimmt der Befehl vorerst einen Namen aus der Kennung, die Texte schreiben Sie ohnehin neu.
• pnpm install nimmt die App in den Arbeitsbereich auf. Danach steht die Lockdatei kompakt da: pnpm exec prettier --write pnpm-lock.yaml bringt sie in die Form des Baums, und pnpm lizenzhinweise schreibt die Hinweise Dritter mit dem neuen Stand der Lockdatei.
• pnpm --filter @szenera-app/<id> build baut die App. Der Seed des Katalogs liest ihr gebautes Manifest und überspringt sie bis dahin mit Hinweis.

Was die Vorlage mitbringt:

Eine App ohne Widget (eine, die eine Funktion des Portals aufsperrt) oder mit Server-Teil baut auf derselben Vorlage auf: ./runtime und ./authoring entfallen, ./backend kommt hinzu, wie unter Server-Teil: Resolver, Fetcher und Jobs beschrieben.

2. Widget, Config und Formular schreiben#

config.ts ist der Werte-Vertrag des Widgets. Jedes Feld trägt .default(), damit eine leere Config vollständig liest, und das Schema verwirft unbekannte Felder still (kein .strict()), damit eine ältere Fassung die Config einer neueren liest. Für jede spätere Fassung gilt dieselbe Regel: Felder kommen nur hinzu, mit Vorgabe, und keines verschwindet oder ändert seinen Typ. Die Grundlinie hält das fest (Schritt 6).

.describe('Beschriftung|Satz') trägt Beschriftung und Hilfetext eines Felds. Das Formular in config-ui.ts liest beides mit schemaFieldText() aus @szenera/widget-editor/config, so heißt ein Feld überall gleich. Welche Steuerelemente der Editor kennt, sagt die Feldart:

Gegliedert wird das Formular in Gruppen (sections) in der festen Folge Vorlage, Quelle, Inhalt, Aussehen, Erweitert und Platzierung. Eine Gruppe mit collapsed: true startet eingeklappt, so steht „Erweitert“ niemandem im Weg. required: true kennzeichnet ein Pflichtfeld, und showWhen mit not: true zeigt ein Feld bei jedem Wert außer den genannten. Höchstens zwei Felder kompakter Art (Auswahl, Umschalter, Schalter, Regler, Farbe, Fläche) nennt quickFields: Die bietet die Leiste am gewählten Widget direkt an. Wer die Beschreibung mit defineWidgetConfigUI() aus @szenera/apps-sdk/config anlegt, erfährt schon beim Bau, wenn eine dieser Regeln nicht stimmt.

Das Einstellungs-Fenster baut sich aus dieser Beschreibung: registerAuthoring trägt sie mit registerConfigUI ein. Ein Bedienelement, das keine Feldart abbildet (etwa eine Stadtsuche), kommt als einzelnes Feld dazu (registerConfigField), nicht als ganzes Formular. Wie das Formular Felder, Kontext und Passt-Bericht verbindet, steht unter Widgets konfigurieren.

Die Werte-Typen aus @szenera/apps-sdk/config hängen nur an zod, der Bau nimmt sie ins Bündel der App. Wie das Widget seine Fläche zeichnet, Platzierungen und Ansichten anlegt, steht unter Widget, Konfiguration und Vorschau.

3. Die Texte schreiben#

Die Texte stehen auf Deutsch im Manifest, jede weitere Sprache als Block unter translations, der nur Texte trägt. Englisch ist Pflicht, und defineAppManifest lehnt einen unvollständigen Block mit dem Pfad des fehlenden Texts ab. Dieselben Regeln gelten für jeden Text, den eine Organisation liest, im Store, im Install-Dialog und im Editor: die Sie-Form, kein Semikolon, höchstens ein Gedankenstrich je Text, keine Wörter aus dem Inneren der Plattform und keine Branche in einer App für alle Branchen.

Zwei Angaben ordnen die App ein: category bestimmt den Abschnitt im Store und in der Widget-Palette, tier die Klasse (standard in jedem Paket, pro ab dem Paket Pro, addon eigens gebucht). Der Manifest-Test der App hält beide fest, damit eine verschobene Einordnung nicht still durchläuft. Eine Klasse außer standard braucht zudem ihren Eintrag in der Verkaufsliste EXPECTED_TIERS in services/api/tests/app-tier-classification-sweep.test.ts, etwa 'door-sign': 'pro': Dort steht, was verkauft wird, und ein Test der Schnittstelle hält jede App dagegen. Fehlt der Eintrag, nennt ihn pnpm app:check in der Zeile Manifest. Eine App mit fremder Quelle oder Pflichtangaben trägt dazu einen Block legal (Datenzugriff, Rechte und Bedingungen).

4. Symbol und Aufnahmen#

Das Symbol icon.svg zeichnen Sie selbst. Solange das Symbol der Vorlage mit seiner Marke data-placeholder dort liegt, bleibt die Zeile Store-Bilder rot.

Die Aufnahmen entstehen mit dem Werkzeug, das auch die CI benutzt:

node tools/app-screenshots/run.mjs --build --only=door-sign

Es nimmt jede Ansicht unter preview.variants auf, die Hauptansicht ein zweites Mal unter dem Namen aus thumbnailUrl und das Szenenbeispiel, die Hauptansicht in einer typischen Szene. Braucht eine Aufnahme mehr, eine Akzentfarbe der Umgebung oder eine feste Teil-Config, steht es in der package.json unter szenera.screenshots.

5. Mit pnpm app:check prüfen#

pnpm app:check door-sign            # aus den Quellen, ohne Bau
pnpm app:check door-sign --built    # dazu Budgets und Host-Zusage gegen den Bau

Der Befehl zeigt je Prüfung eine Zeile, mit jedem Befund darunter. Lokal und in der CI ist es derselbe Befehl, die Prüfung vor dem Bau fährt pnpm app:check --all über alle Apps.

Eine Zeile mit – ist nicht geprüft, sie zählt nicht als bestanden: Budgets und Host-Zusage brauchen den Bau, und den prüft ohnehin der Bau selbst. Ein Bündel über seinem Deckel bricht vite build, ein Import außerhalb der Zusage ebenso.

Eine frische App aus der Vorlage zeigt drei Zeilen rot, und jede verschwindet mit einem Handgriff:

• Store-Bilder: ein eigenes Symbol und die Aufnahmen aus Schritt 4.
• Verdrahtung: "@szenera-app/<id>": "workspace:*" in services/public-site/package.json und, für eine App mit Widget, in services/scene-snapshot/package.json, danach pnpm install. Der Bau beider Pakete liest die gebauten Apps, und erst die Abhängigkeit sagt ihm die Reihenfolge. Danach pnpm codegen:public-app-catalog, das den Katalog der öffentlichen Seite neu schreibt.
• Handbuch: eine Seite docs/de/handbook/apps/<id>.md vom Typ app. Die öffentliche Seite baut nur, wenn jede App eine hat.

6. Testen#

pnpm --filter @szenera-app/door-sign typecheck
pnpm --filter @szenera-app/door-sign test

Die Tests laufen gegen die Quellen, ohne Bau. tests/manifest.test.ts hält Vertrag, Kategorie, Bedingungen, Wirte und Registry, tests/compat.test.ts die Grundlinie und den Host-Bereich, die Tests unter tests/widgets/ Darstellung und Formular. Ändern Sie die Config, schreibt pnpm app-compat --update door-sign das Neue in die Grundlinie. Bricht die Änderung die Regel aus Schritt 2, schreibt der Befehl nichts, und der Test nennt das Feld.

7. Der Pull Request#

Der PR trägt eine Notiz: pnpm changeset nennt die App, und eine Notiz für eine App braucht den Abschnitt ## Kunde mit dem Satz, den eine Organisation zu dieser Fassung liest. Ohne Notiz bekommt die App keine Fassung. Die Prüfung des PR fährt pnpm app:check --all mit der übrigen Statik, und in der vollen Tiefe baut, nimmt auf, packt und prüft sie jede berührte App so, wie der Lieferweg es tut. Signiert und abgelegt wird im PR nichts.

Nach dem Merge hebt der Versions-PR die Fassung aus der Notiz, und der Zug setzt den Tag @szenera-app/<id>@<fassung>.

8. Vom Tag in den Katalog#

Zum Tag baut release-app.yml die Fassung genau einmal: Bau, Aufnahmen, das Artefakt <id>-<fassung>.szapp, die Prüfung, die Signatur, die Ablage in der Registry. Dann meldet der Lauf die Fassung Staging und Produktion, beide holen dasselbe Artefakt und legen das Release im Kanal Canary an. Dieselbe Fassung trägt damit überall dieselben Bytes. Was an einem Release liegt und wie die Kanäle wirken, steht unter Signieren und der Weg in den Katalog.

9. Prüfen und freigeben im Ops-Portal#

1. Öffnen Sie im Ops-Portal Apps, die Zeile der App und den Reiter Releases. Die neue Fassung steht in Canary, Prüfung öffnen führt zur Release-Prüfung.
2. Die Prüfung zeigt links den Store-Eintrag, wie die Organisationen ihn sehen werden, rechts die Zustimmungsfolge, den Vergleich mit der Vorgängerin, „Neu in dieser Fassung“, die Verbreitung und die Prüfliste. Fehlt der Text für die Organisationen, tragen Sie ihn hier ein.
3. Nach Beta hochstufen … dürfen Sie allein. In Beta bekommen die Fassung die Organisationen, die sich für Vorabfassungen eingetragen haben.
4. Nach einigen Tagen in Beta: Nach Stabil hochstufen … mit einer Begründung. Das legt eine Anforderung an, die Fassung bleibt so lange in Beta.
5. Eine zweite Person öffnet die Prüfung derselben Fassung und bestätigt. Erst damit steht die Fassung in Stabil, und alle Organisationen, deren Paket die App enthält, finden sie im Store.

Ergebnis prüfen#

• pnpm app:check <id> --built zeigt jede Zeile mit ✓.
• Im Ops-Portal steht die Fassung im Reiter Releases in Stabil, und der Verlauf nennt bei der Freigabe beide Personen.
• Im Store einer Organisation mit passendem Paket steht die App unter ihrer Kategorie, mit Symbol, Aufnahmen und Szenenbeispiel aus dem Artefakt.

Wenn etwas nicht klappt#

In der Nacht beweist pnpm app:probe, dass dieser Weg hält: Die Probe legt eine App aus der Vorlage an, fährt ihre Tests und ihren Bau, fragt Seed, Aufnahmen und Budgets, ob sie die App sehen, und erwartet von pnpm app:check genau die drei roten Zeilen einer frischen App.