← Alle Dokumentationen
Portal Studio Field Guide

Bauen Sie mutig. Veröffentlichen Sie sicher.

Eine praktische Referenz für Administratoren, die das Kundenerlebnis gestalten und Entwickler, die es erweitern. Es dokumentiert die reale Studio-Architektur, den geregelten Releasepfad, den Besitz von Help Centern, Identität, Migrationen, Komponentenverträge und Wiederherstellung.

Portaldokument v2Administrator + EntwicklerEnterprise Release WorkflowAktualisiert 1 August 2026
Administrator Guide · Architektur

Wissen, was Studio besitzt

Portal Studio besitzt die kundenorientierte Shell: Seiten, Komponentenplatzierung, Marken-Tokens, Reaktionsverhalten, Navigation, Fußzeile, Identitätsdarstellung, Ticketfahrten und Veröffentlichungen. Das Help Center besitzt Sprachen, Kategorien, Abschnitte und Artikelinhalte. Studio verbraucht diese Inhalte über eine geschützte Brücke; es erstellt niemals einen zweiten Artikelspeicher.

Help Center + Ticket + IdentitätsdienstePermission-safe DatenadapterPortaldokument v2 EntwurfEin Compiler und RendererPreview und veröffentlichtes Portal
Ein-Renderer-Regel: Preview und öffentliche Seiten verwenden den gleichen Dokument-/Compilervertrag. Die Veröffentlichung wechselt niemals zu einer nicht verwandten Vorlage.
Portal Studio · Workspace Karte
Leinwand, lebendDesktop · Kunde
KundenportalGleiches strukturiertes Dokument, das in der Vorschau und im öffentlichen Rendering verwendet wird
Interface Map: Job Rail, Live Canvas und Inspektor zielen auf die gleiche stabile Seite und Knotenauswahl.
Administrator · Starten Sie jetzt

Vollständige Bereitschaft vor dem Bauen tief

  1. Offen Portal Studio → Start → Ready.
  2. Bestätigen Sie die kanonische Portaladresse und öffnen Sie diese in einem separaten Tab.
  3. Legen Sie das Logo, Browser-Icon, Touch-Ikone, soziales Bild und Thema Farbe.
  4. Bestätigen Sie die Sprachen des Hilfecenters; ändern Sie die Sprachautorität in Help Center, nicht Studio.
  5. Konfigurieren Sie die Navigation und den globalen Enterprise Footer.
  6. Wählen Sie eine Ticketfahrt und konfigurieren Sie mindestens ein Anfrageformular.
  7. Halten Sie mindestens eine sichere Anmeldemethode aktiv und überprüfen Sie die Identitätserkennung.
  8. Führen Sie Qualität aus und erstellen Sie den signierten Vorschau-Handshake.
  9. Erstellen Sie die erste geregelte Freigabe, nachdem jedes Blocking-Element klar ist.

Der Bereitschaftsprozentsatz wird aus gespeicherten Arbeitsbereichsdaten und Vorschauzustand berechnet, indem ein Element direkt zum eigenen Panel ausgewählt wird.

Administrator · Build

Erstellen von Seiten und wiederverwendbaren Abschnitten

  1. Offen Erstellen → Seiten und wählen Sie eine geschützte Systemseite aus oder erstellen Sie eine benutzerdefinierte Seite.
  2. Legen Sie Route, Titel, Zugriffsmodus und Lokalverhalten fest. Geschützte Systemrouten können nicht gelöscht werden.
  3. Offen KomponentenFiltern Sie nach Job oder Laufzeit und legen Sie eine Komponente in einen kompatiblen Slot.
  4. Verwenden Sie den Inspektor für Inhalt, Aussehen, Bindung, Sichtbarkeit und Zugänglichkeit.
  5. Verwenden Sie wiederverwendbare Muster für wiederholte Strukturen; behalten Sie Organisations- oder Markenunterschiede in Varianten.
  6. Speichern Sie den Entwurf und die Übung Lade-, Leer-, Fehler-, Gast- und angemeldeten Zustände in der Vorschau.
Komponentenbibliothek · Sanitierte Schnittstellenkarte
WissenssucheGA · Kunden sicherGitterGA · HilfezentrumArtikel 2GA · übersetzte DTOAntragsformularGA · VersioniertFahrplanzeitBeta · WarnungDatendiagrammGeplant · Blöcke veröffentlichen
Schnittstellenkarte: Kategorie, Kompatibilität und Reife sind vor der Platzierung sichtbar. Geplante Komponenten blockieren die Veröffentlichung; Beta-Komponenten erfordern eine explizite Freisetzungsbehandlung.
Administrator · Marke und Responsive

Vorschau auf echte Reisen, nicht einen glücklichen Bildschirm

  1. Wählen Sie Gäste-Support, angemeldetes Ticket, Abrechnung Pflege, Organisation oder Wissen Handoff.
  2. Wechseln Sie Personas, Organisation, Rolle und Help Center-Sprache.
  3. Inspizieren Sie mobile, große Mobile, Tablet, Laptop, Desktop, breite und ultrabreite Haltepunkte.
  4. Überprüfen Sie geerbte, überschriebene und zurückgesetzte Werte; vermeiden Sie unnötige Breakpoint-Duplizierung.
  5. Tastatur, RTL, Reduzierte Bewegung, Laden, Leer, Nichtverfügbar und Berechtigungszustände ausführen.
  6. Verwenden Sie Test Lab für Zugänglichkeit, Nutzlast, Route, Bindung und Renderer-Ergebnisse vor der Überprüfung.
Eine grüne Leinwand ist keine Freigabeentscheidung. Reguliertes Preflight, Überprüfung des Status, der Fähigkeiten und Veröffentlichungsnachweise entscheiden darüber, ob das Portal veröffentlicht werden darf.
Administrator · Erfahrung

Betrieb eines Zendesk-Hilfecenters ohne doppelte Inhalte

  1. Erstellen Sie Kategorien, Abschnitte, Artikel, Übersetzungen, Anhänge und Vorlagen in Hilfe-Center.
  2. Sprachen dort aktivieren; lokalisierte Slugs, Suche, Feeds, SEO und Artikelchrom folgen derselben Autorität.
  3. In Studio, Platzierung Wissenssuche, Kategorie / Ressourcen-Raster, Feeds, Thema Akkordeon, Artikel, Inhaltsverzeichnis, Feedback, verwandte und vorherige / nächste Komponenten.
  4. Konfigurieren Sie vorgestellte, beliebte und aktuelle Feeds; Verwenden Sie kontextbezogene Vorschläge in Ticketflüssen.
  5. Vorschau keine Ergebnisse, lange Artikel, Anhänge, Feedback, Watch / Abonnement und Ticket Handoff.
  6. Überprüfen Sie saubere lokale Routen, kanonische / Hreflang-, strukturierte Daten und Cache-Ungültigkeit nach der Veröffentlichung.
Grenze der Behörde: Bearbeiten von Artikelinhalten und Kundensprachen im Help Center. Verwenden Sie Portal Studio nur, um zu verfassen, wie Wissen entdeckt und angezeigt wird.
Administrator · Identität und Organisationen

Anmelden sicher konfigurieren

  1. Offen Identität & Organisationen → Identität und mindestens einen Anmeldepfad aktiviert halten.
  2. Wählen Sie Standardmethode, Registrierungsrichtlinie, Sitzungsdauer, SSO-Domaindurchsetzung und Erkennungsverhalten.
  3. Hinzufügen von Anbietern mit visuellen Routingfeldern: Typ, Domains, Priorität, Präsentation, aktivierter und verifizierter Status.
  4. Aktivieren Sie für SCIM die Bereitstellung, kopieren Sie den genauen Workspace-Endpunkt und drehen Sie das Token.
  5. Kartenansprüche und Organisationsmitgliedschaft, dann Testerstellung, -aktualisierung, Gruppenmitgliedschaft und Deaktivierung mit einem Testmieter.
  6. Vorschau Gast, Kunde, delegierte Organisation und blockierte Staaten vor der Veröffentlichung.
Senden Sie niemals ein Studio Session Cookie an SCIM Es ist ein sitzungsloser, arbeitsraumgebundener Träger API Drehen eines Tokens nach versehentlicher Exposition.
Administrator · Fahrkartenfahrten

Verfassen Sie die komplette Support-Reise

  1. Wählen Sie direktes Formular, Wizard, Search-First, Hub oder Service-Desk.
  2. Erstellen Sie ein benanntes, versioniertes Anfrageformular mit Abschnitten und zugänglichen Feldbeschriftungen.
  3. Erstellen Sie visuelle Bedingungen, Routing, SLA und Genehmigungsschritte; Advanced JSON ist nur für überprüfte Entwickleränderungen gedacht.
  4. Konfigurieren Sie Liste, Detail, Thread, Zeitleiste, Anlage, Genehmigung, SLA und Antwortflächen.
  5. Testen Sie die Gästesuche, angemeldete Anfragen, Organisationssichtbarkeit, Uploadfehler, E-Mail-Benachrichtigung und Wissensablenkung.
  6. Einen Entwurf speichern; veröffentlichen Sie nur nach dem Routenadapter und dem Benachrichtigungspfadpass vor dem Flug.
Administrator · Überprüfung und Freigabe

Bewegen Sie sich durch ein geregeltes Release

Entwurf gespeichertÜberprüfungZugelassenGeplant oder veröffentlichtBeobachtet oder zurückgerollt
  1. Validierung und Testlabor durchführen, Blockierungsbefunde beheben; zulässige Warnungen mit Kontext anerkennen.
  2. Fügen Sie Release Notes hinzu und fordern Sie eine Überprüfung an. Reviewer kommentieren stabile Seiten-/Knotenpfade.
  3. Approvers inspizieren das Diff, die Vorschaufahrten, Berechtigungsänderungen und Beweise.
  4. Veröffentlichen oder planen Sie über den Hintergrundarbeiter. Leaving Studio storniert keinen dauerhaften Job.
  5. Beobachten Sie den Fortschritt, die Gesundheit und die Korrelation ID. Stoppen / wiederholen Sie nur von Job-Kontrollen.
  6. Überprüfen Sie kritische Routen, Identität, Tickets und Wissen.
LeistungsfähigkeitZweck
Ansicht / EditÜberprüfen oder ändern Sie Entwürfe ohne Freigabeberechtigung.
Überprüfen / genehmigenSeparates Feedback und Genehmigung von der Autorschaft.
Zeitplan / Veröffentlichung / RollbackUnabhängige Produktionskontrollen.
Identität / SCIM /Migration / Komponenten / DiagnoseBeschränken Sie sensible Fachoperationen.
Administrator · Migration und Erweiterung

Migration mit Beweisen und einem Weg zurück

  1. Wählen Sie den Provider Blueprint und erstellen Sie einen Trockenlauf.
  2. Überprüfen Sie entdeckte Einstellungen, nicht zugeordnete Werte, Inhaltszählungen und visuelle Paritätserfassungen.
  3. Schließen Sie sichere Zuordnungen ab und führen Sie das strukturierte Diff erneut aus.
  4. Bewerben Sie sich auf einen Entwurf, versöhnen Sie Zählungen und sehen Sie jede geschützte Reise in einer Vorschau.
  5. Aufzeichnung autorisierter Akzeptanz; Überschreiben Sie niemals die aktuelle veröffentlichte Version während des Imports.
  6. Veröffentlichen Sie durch Governance und halten Sie den Migrationsbericht, die Freigabe-ID und den Rollback-Punkt zusammen.
Entwickler-Erweiterungsleitfaden · Architektur

Verträge verlängern, keine Vorlagen

Eine sichere Erweiterung registriert einen stabilen Komponententyp und -schema, erklärt Berechtigungen und Datenanforderungen, rendert über den kanonischen Compiler und liefert deterministische Fixes/Tests. Abfragen Sie keine beliebigen Tabellen, injizieren Sie Editor JavaScript in das öffentliche Portal, erstellen Sie ein anderes Artikel-Repository oder umgehen Sie das Release Gate.

Portaldokument v2

Seiten enthalten stabile Knoten, Slots, Eigenschaften, Bindungen, responsive Overrides, Bedingungen und Zugänglichkeitsmetadaten.

Komponentenregister

Ein Vertrag füttert Studio, Compiler, Dokumentation, Migration und Fälligkeitsprüfungen.

Datenquellenregister

Zulässige, schreibgeschützte DTOs mit Berechtigungsumfang ersetzen willkürliche SQL oder dynamische Aktionen.

Ein Renderer

Preview und öffentliche Ausgabe Share Compilation, Sanitization, Budgets und Laufzeitzustände.

Entwickler · Komponentenvertrag

Definieren eines Komponentenpakets

Verwenden Sie eine kleinbuchstabige ID und semantische Version. Geben Sie beide Kompatibilitätseigenschaftennamen an, da die Paketprüfung und Sicherheitsvalidierung unabhängige Prüfungen durchführen.

{
  "schema_version": 1,
  "id": "acme.support_health",
  "slug": "acme-support-health",
  "name": "Support health",
  "version": "1.0.0",
  "entry": "renderer.php",
  "renderer": "server",
  "server_renderer": "renderer.php",
  "public_renderer": "public.js",
  "schema": {
    "type": "object",
    "properties": {
      "heading": {"type": "string", "maxLength": 120},
      "showSla": {"type": "boolean", "default": true}
    },
    "additionalProperties": false
  },
  "permissions": ["tickets.read"],
  "data_scopes": ["tickets.mine"],
  "accessibility": {
    "landmark": "section",
    "nameFrom": "heading",
    "emptyState": true,
    "errorState": true
  },
  "performance": {"max_js_bytes": 12000, "max_css_bytes": 8000},
  "performance_budget": {"js": 12000, "css": 8000, "requests": 0}
}

Knotenform

{
  "id": "node-support-health",
  "type": "custom.acme_support_health",
  "props": {"heading": "Support health", "showSla": true},
  "bindings": {"requests": {"source": "tickets.mine", "limit": 5}},
  "responsive": {"mobile": {"padding": "16px"}, "desktop": {"padding": "24px"}},
  "conditions": [{"field": "identity.signed_in", "operator": "equals", "value": true}],
  "a11y": {"label": "Support health"}
}
  • IDs bleiben über Edits und Migrationen hinweg stabil.
  • Eigenschaften weisen nicht deklarierte Felder und unsichere HTML zurück.
  • Jede datengebundene Ansicht definiert Laden, Leeren, Berechtigung und Wiederholfehlerausgabe.
  • Containerkomponenten benennen ihre Schlitze; Blätter können keine willkürlichen Kinder akzeptieren.
  • Markieren Sie die Reife ehrlich: geplante Blöcke, Beta warnt, GA erfordert vollständige Beweise.
Entwickler · Datenquellen und Bindungen

DTOs mit Erlaubnis-Safe

  1. Wählen Sie eine vorhandene gepunktete ID wie tickets.mine, knowledge.featured oder customer.profile.
  2. Nur von der DTO in ihrer Version deklarierte Bindefelder. Unbekannte Quellen scheitern mit data_source.unknown.
  3. Passen Sie den bereits autorisierten Portalkontext; akzeptieren Sie niemals Arbeitsbereich / Kundenidentität von einer nicht vertrauenswürdigen Eigenschaft.
  4. Listenlimits sind auf 1–100 festgelegt.
  5. Wenn eine neue Quelle unvermeidlich ist, fügen Sie ihre stabile Definition, sichere Zuordnung, Berechtigungen, leeres Verhalten und Vorschauvorrichtung zusammen.
{
  "success": true,
  "source": "tickets.mine",
  "contract_version": 1,
  "items": [
    {"id": 42, "number": "REQ-42", "subject": "Example", "status": "open"}
  ]
}
Mutationen erfordern eine explizite autorisierte Serviceaktion, Workspace-Bindung, CSRF/Session oder Trägervalidierung, gegebenenfalls Idempotenz und einen typisierten Fehlerumschlag.
Entwickler · Sicherheit

Bleiben Sie innerhalb der Vertrauensgrenzen

GrenzeErforderliches Verhalten
ArbeitsbereichLösen Sie sich von dem vertrauenswürdigen Host / Route / Sitzung, dann erfassen Sie jedes Lesen und Schreiben vor der Ausführung.
HTMLVerwenden Sie die Portal Sanitizer/Parser Allowlist. URLs, CSS oder Drehbuch.
VorschauBeantragen Sie das Quellenfenster gleichen Ursprungs, die signierte Kanalversion und Nonce.
IdentitätBewahren Sie Geheimnisse außerhalb von Dokumenten. SCIM ist Bearer-authentifiziert, sitzungslos und Workspace-gebunden.
PackungenLehnen Sie Traversal, absolute Pfade, Links/Spezialdateien, übergroße Archive, Prüfsummen-/Signaturfehlanpassung und unbekannte Berechtigungen ab.
FehlerGeben Sie stabilen Code, sichere Nachricht, Retryability, Remediation und Korrelations-ID zurück; melden Sie serverseitig private Ausnahmen an.
WissenLesen Sie über HelpCenterBridge. Verfassen oder duplizieren Sie niemals Artikel des Hilfecenters in einer Erweiterung.
{
  "success": false,
  "error": {
    "code": "studio.permission_denied",
    "message": "You do not have permission to publish the Portal.",
    "retryable": false,
    "correlation_id": "ps_…",
    "meta": {"capability": "publish"}
  }
}
Entwickler · Paket und Migration

Inspizieren, installieren und aktualisieren atomar

  1. Putz component.json an der ZIP-Wurzel und halten Sie jeden Pfad relativ.
  2. Erste Inspektion durchführen. Der Installateur sperrt die Archive 500 Eintragungen und 25 MB extrahiert; Sicherheitsvalidierung fügt unabhängige Grenzwerte hinzu.
  3. Überprüfen Sie die erwartete SHA-256 und Paketsignatur im Freigabeprozess.
  4. Installieren Sie in einem versionierten Verzeichnis.
  5. Geben Sie Eigenschaftsmigrationen für das Brechen von Schemaänderungen und bewahren Sie unbekannte Kompatibilitätsfelder.
  6. Öffnen Sie die Komponente in einem Entwurf, führen Sie jeden Zustand / Viewport / Persona-Fixment aus und veröffentlichen Sie durch Governance.
  7. Rollback aktiviert die vorherige unveränderliche Komponenten- / Dokumentfreigabe; behält seine Reproduzierbarkeitsnachweise bei.
Entwickler · Tests und Release

Beweisen Sie die Erweiterung auf dem gleichen Release-Hash

php tools/portal_studio_certify.php --source-only --json
php tools/test_portal_studio_contract.php
php tools/test_portal_one_renderer.php
php tools/test_portal_studio_engineer.php
php tools/test_portal_component_contracts.php
php tools/test_portal_one_renderer.php
php tools/test_portal_shell_contract.php
php tools/test_portal_knowledge_contract.php
node node_modules/@playwright/test/cli.js test tests/e2e/portal-studio-shell-visual-contract.spec.js tests/e2e/portal-custom-code-runtime.spec.js

Datenbank/Migration, Real-Browser-Visual, Identitätsanbieter, Autorisierungsisolation, Zugänglichkeit, Leistung, Warteschlange/Cron, Mail/Anhang, Backup/Wiederherstellung und Bereitstellung von Nachweisen an denselben unveränderbaren Release-Hash. Unbekannte erforderliche Beweise müssen die Freigabe nicht bestehen lassen.

  • Einheit: Schema, Desinfektion, DTO-Form, Bedingungen, Migrationen und typisierte Fehler.
  • Vertrag: Laden/Leeren/Fehler/Erfolg, Laufzeit, Zeitnischen, Bindungen und Parität mit einem Sender.
  • Browser: Tastatur, Fokus, Semantik, RTL, Zoom/Reflow, reduzierte Bewegung und jeder Haltepunkt.
  • Sicherheit: Workspace-übergreifende Sonden, gefälschte Aktionen, Paketangriffe, Preview-Spoofing und geheimes Leckage.
  • Operationen: dauerhafter Fortschritt, Verlassen/Rückkehren, Stoppen/Wiederholen/Fortsetzen, Scheduler-Herzschlag und Rollback.
Administrator + Entwickler · Recovery

Fehlerbehebung nach Zustand und Korrelations-ID

StaatWas zu tun ist
GenehmigungDie benannte Fähigkeit anfordern. Versteckte Benutzeroberfläche ist Bequemlichkeit; das Backend setzt sie immer durch.
ValidierungÖffnen Sie die gemeldete Seite / Node / Feld, korrigieren Sie es und führen Sie dann den Preflight erneut aus.
KonfliktNeue Version laden, Änderungen vergleichen und absichtlich neu anwenden. Niemals erzwingend überschreiben.
Offline/retryableBehalten Sie den Entwurf, stellen Sie die Konnektivität wieder her, versuchen Sie es erneut mit der Aktion und überprüfen Sie den dauerhaften Jobzustand.
Tödlich / nicht verfügbarKopieren Sie die Korrelations-ID und den Zeitstempel für die Unterstützung.
Publish gescheitertÜberprüfen Sie die Preflight-/Jobausgabe, wiederholen Sie nur wiederholbare Phasen oder kehren Sie zum letzten gesunden Release zurück.
SCIM 401/403Bestätigen Sie Endpoint/Workspace, Bearer-Token, aktivierten Zustand und Rotation; Verwenden Sie niemals ein Browsersitzungscookie.
Wissen ist abgestandenÜberprüfen Sie locale/publication im Help Center, dann prüfen Sie die Cache-Ungültigkeit und die saubere lokalisierte Route.

Verwenden Sie Print → Speichern als PDF für eine kontrollierte Offline-Kopie.