jorgemiranda-alt/cloudapper

Was macht cloudapper?

CloudApper ist eine No-Code-Plattform: Apps bestehen aus Formularen (Datenmodell), Menüs (Navigation), Rollen, UI-Workflows (clientseitig), Backend-Workflows (Automatisierung) und DevExpress-Berichten, die alle im App Studio bearbeitet werden (/design/... für Formulare und Menüs, /studio/... für Workflows) und in der Runtime-App (/<clientId>/app/<appId>/...) verwendet werden.

Diese Datei enthält die Regeln, die für jede Aufgabe gelten. Lies die Referenz, die zur Aufgabe passt, bevor du handelst:

Aufgabe	Lies
Verstehen, wie die Plattform funktioniert (Formulare, Felder, Workflows, Berichte, Caching)	references/platform-model.md
Aufrufen der APIs (Datensätze, Workflows, Formulare, Menüs, Rollen, UI-Workflows, Berichte)	references/api-reference.md
Erstellen oder Ändern eines Workflows; Debuggen eines Workflows, der „nicht feuert“ oder langsam ist	references/workflow-patterns.md
Steuern des Browsers mit dem Playwright MCP	references/playwright-efficiency.md
Kopieren von Funktionen oder einer ganzen App von einer App/einem Account in eine andere/n	references/copy-between-apps.md
Erstellen einer neuen App oder eines neuen Formulars im Designer	references/building-apps.md
Entwerfen, Benennen oder Überprüfen von etwas (SOLID auf CloudApper, Namenskonventionen, Workflow-/Konfigurations-/Berichtskonventionen)	references/conventions.md
Entwerfen einer Lösungs- oder Integrationsarchitektur (UKG, REST, Webhooks, SFTP, Middleware; Skalierung und Effizienz)	references/architecture.md
Dokumentieren einer App (technische / Fehlerbehebungsanleitung oder PM-Übergabeanleitung)	references/documentation.md
Überprüfen einer App oder Erstellen von Erkenntnissen / Empfehlungen	references/app-review-checklist.md
Arbeiten mit UKG-Connectoren (Pro, WFM, Recruiting, HRSD)	references/integrations-ukg.md
Der Benutzer fragt, wie man mit dir an CloudApper arbeitet oder was in diese Skill-Anleitung gehört	references/learning-and-prompting.md

Umgebungen: Frage, bevor du etwas änderst

Die meisten CloudApper-Kunden haben eine Produktions-App und eine UAT-App (Test), oft unter verschiedenen Accounts. Bestätige vor jeder Änderung (Speichern eines Formulars, Bearbeiten oder Umschalten eines Workflows, Bearbeiten von Datensätzen, Importieren eines Berichts, Ändern von Menüs), für welche Umgebung die Änderung ist, es sei denn, der Benutzer hat dies in dieser Konversation bereits gesagt:

• Frage: „Ist das für Produktion oder UAT?“ und nenne den Account/die App, bei der du angemeldet bist, damit der Benutzer eine Abweichung erkennen kann.
• Standardmäßig gilt UAT. Behandle Produktion als schreibgeschützt: keine Änderungen, keine Workflow-Ausführungen und keine Anmeldungen oder Lesevorgänge, es sei denn, der Benutzer fordert diese spezifische Aktion explizit an. Das Kopieren von der Produktion ist ein Lesevorgang; das Kopieren in die Produktion ist eine Änderung.
• Überprüfe vor jedem Schreibvorgang die Client-ID in der URL (/<clientId>/app/<appId>). Ein Skript, das schreibt, sollte die Ausführung verweigern, wenn die Seite auf dem falschen Client ist.
• Projektdaten (Accounts, Client-/App-IDs, welche App die Produktion ist) werden nicht in dieser Skill-Anleitung gespeichert. Suche in den projekteigenen Notizen oder Dokumenten und im Speicher danach; falls sie fehlen, frage den Benutzer.

Sicherheitsregeln, die für jede Aufgabe gelten

• Führe, aktiviere oder triggere niemals eigenständig einen Workflow aus. Der Benutzer startet Ausführungen. Du darfst Definitionen speichern und Ein/Aus schalten, nur wenn du darum gebeten wirst; sage klar, wenn ein Schalter das Live-Verhalten ändert.
• Erstelle ein Backup, bevor du etwas bearbeitest. Speichere die aktuelle Definition jedes Workflows/Formulars, das du ändern wirst, in einem lokalen, datierten Ordner und behalte sie, bis der Benutzer das Ergebnis bestätigt hat. (Ein zu früh gelöschtes Backup hat einmal ein Rollback unmöglich gemacht.)
• Geheimnisse. Workflow-Connectoren enthalten Anmeldedaten (UKG, andere Anbieter-APIs, Schlüssel). Gib sie niemals aus, protokolliere sie nicht und füge sie nicht in Dokumentationen ein. Wenn du Workflow-JSON untersuchst, maskiere Schlüssel wie password/secret/apikey/token/clientId und gib nur die Struktur aus. Lösche rohe Dumps mit Geheimnissen, wenn du fertig bist, und teile dem Benutzer mit, welche lokalen Ordner sie noch enthalten.
• Der Benutzer meldet sich an. Gib niemals Passwörter ein. Bitte den Benutzer, sich im Playwright-Browser anzumelden und dir mitzuteilen, wenn er fertig ist.
• Persönliche Daten. Verpixele Namen, E-Mail-Adressen und IDs in Screenshots, die du behältst oder teilst.
• Berichte zuverlässig. Wenn ein Test zeigt, dass etwas nicht funktioniert hat, sage dies mit den Beweisen (Zeitstempel, Status, Logzeilen), bevor du die nächste Lösung vorschlägst.

Die sechs Plattform-Fakten, die die meisten Überraschungen verursachen

Auf die harte Tour gelernt; Details und Belege in references/workflow-patterns.md.

1. Die Workflow-Reihenfolge ist wichtig (WP-001). Ein Datensatz, der von einem Workflow erstellt/aktualisiert wird, löst nur Workflows aus, die weiter hinten in der Workflow-Liste (höhere Sequence) liegen. Ein Workflow, der nach seinem Ziel platziert ist, feuert nichts. Halte die Listenreihenfolge zwischen den Umgebungen identisch.
2. Der Designer erledigt versteckte Nebenarbeiten, die die API nicht erledigt. Das Erstellen eines Formulars im Designer gewährt auch der Admin-Rolle Zugriff (Berechtigung 32655). Das Speichern eines Formularkörpers über die API erstellt das Formular und seine Standardmenüs, aber nicht die Berechtigung, sodass die Menüs in der Runtime verborgen bleiben. Unterformulare benötigen ebenfalls ihren eigenen Parent-Child-Beziehungsaufruf.
3. Ein Status-Trigger benötigt eine tatsächliche Änderung (WP-002). Workflows, die auf Status _IsUpdated ausgelöst werden, starten nicht, wenn der neue Wert dem alten entspricht (Datensätze, die auf „Running“ feststecken, können nicht durch erneutes Setzen von „Running“ erneut ausgeführt werden).
4. Ausgelöste Ausführungen eines Workflows laufen nacheinander, und eine Schleife wartet nicht immer auf sie (WP-005). Eine Schleife, die 24 Datensätze aktualisierte, war in Sekunden beendet, während die 24 Workflow-Ausführungen, die sie auslöste, über die nächste Stunde ausgeführt wurden; eine zweite Charge, die inzwischen startete, verlor ihre ausgelösten Ausführungen. Führe jeweils nur eine Charge aus.
5. Die Runtime cached die App. Nach Design-Änderungen klicke auf das Aktualisierungssymbol neben dem App-Namen (oder melde dich erneut an); Menüs für Formulare, auf die die Rolle keinen Zugriff hat, werden ausgeblendet, daher benötigen neue Formulare Rollen-Berechtigungen (siehe Kopier-Checkliste).
6. Ein Router führt jede Route aus, deren Bedingung wahr ist (WP-009), nicht nur die erste. Mache Routenbedingungen exklusiv, wenn nur ein Ergebnis gewünscht ist.

Wie man effizient arbeitet

• Bevorzuge die APIs gegenüber dem Klicken: Sie sind schneller, präzise und günstig. Verwende die UI nur für das, wofür du keine API kennst, und um zu bestätigen, was der Benutzer sehen wird.
• Führe in Playwright Code aus Dateien aus (browser_run_code_unsafe mit filename), serviere große Payloads von einem localhost-Helfer und gib kompakte Zusammenfassungen zurück (Anzahl, Namen, Status), niemals vollständiges JSON. Siehe references/playwright-efficiency.md.
• Bevor du einen Workflow bearbeitest, lies seinen Knotenbaum (Namen, Aktionstypen, Formulare) über die API, anstatt den Designer zu öffnen.
• Überprüfe nach jeder Änderung durch Rücklesen (API) und öffne bei Workflows den Builder einmal, um zu prüfen, ob er gerendert wird.
• Große oder wiederholte Aufgaben: Schreibe ein kleines Builder-Skript (Python), das das JSON aus Vorlagen bestehender Knoten erzeugt, dann ein geschütztes Anwendungsskript. Behalte beide im Projekt, damit die Änderung wiederholbar und überprüfbar ist.

Dokumentationsstandards

Nur Markdown (PDF nur auf Anfrage), nur internes Publikum (keine Kunden-E-Mails), offene Fragen im Dokument mit Warum/Wozu, Diagramme zeigen nur die laufende App und ihre Benutzer/externen Systeme. Vollständige Methode: references/documentation.md. Wenn eine App bereits eine Dokumentation oder Projektnotizen hat, lies sie, bevor du die App erneut erkundest.

Wissen zu dieser Skill-Anleitung hinzufügen

Wenn der Benutzer darum bittet, etwas zu dieser Skill-Anleitung hinzuzufügen („Füge dies zur CloudApper-Skill hinzu“):

1. Lies inbox/TEMPLATE.md im Ordner dieser Skill-Anleitung und schreibe den Entwurf nach inbox/<yyyy-mm-dd>-<kurzname>.md mit dem Status Hypothesis. Schreibe ihn generisch: keine Kunden-, App-, Formular-, Workflow- oder Personennamen, IDs, echten Hosts oder Anmeldedaten.
2. Durchsuche references/ nach Einträgen, die der Entwurf bestätigt oder widerspricht, und liste sie in den Überprüfungsnotizen des Entwurfs auf.
3. Bearbeite SKILL.md oder references/ nicht selbst, es sei denn, der Benutzer sagt, dass er ein Maintainer ist, der eine überprüfte Änderung anwendet. Sage dem Benutzer, er solle einen Pull-Request mit dem Entwurf eröffnen (CONTRIBUTING.md enthält den Ablauf).